docs: convert :Example: RST code blocks to proper Python doctest format

[Copilot]

What do these changes do

Convert :Example: docstring sections from RST :: code-block format to runnable Python doctest format (>>>) across all pythainlp/ modules.

What was wrong

Example sections used RST literal-block syntax (:: + indented code + # output: ... comments), which Sphinx renders but Python's doctest module cannot execute or validate:

# Before — not runnable as doctest
:Example:
::

    from pythainlp.util import remove_dangling

    remove_dangling("๊ก")
    # output: 'ก'

How this fixes it

Converted all discoverable :Example: blocks in the affected files to proper doctest format with verified expected outputs (run against compact + extra dependencies). Examples requiring optional dependencies or corpus downloads are marked # doctest: +SKIP. Several incorrect expected outputs in the original comments were also fixed in the process.

# After — runnable doctest
:Example:

    >>> from pythainlp.util import remove_dangling
    >>> remove_dangling("๊ก")
    'ก'

Files converted:

pythainlp/util/:

• collate, digitconv, keyboard, normalize, numtoword, wordtonum — initial batch
• trie, syllable, morse, encoding, lcs, emojiconv — second batch
• thai — analyze_thai_text example converted per review feedback

pythainlp/soundex/:

• udom83, lk82, metasound, prayut_and_somchaip, core — live doctests with verified outputs
• sound — marked +SKIP (requires optional panphon dependency)

pythainlp/morpheme/:

• thaiwordcheck — flattened sub-section structure into standard doctest block
• word_formation — converted assert statements to >>> / expected-output pairs

pythainlp/transliterate/:

• core (romanize, transliterate, pronunciate) — royin/iso_11940 run live; engine-specific examples marked +SKIP
• spoonerism, wunsen — marked +SKIP (optional deps)

pythainlp/ancient/:

• aksonhan, currency — live doctests with verified outputs

pythainlp/braille/:

• core — live doctests with verified outputs

pythainlp/tokenize/:

• core, _utils — core examples live; ML-engine examples marked +SKIP

pythainlp/corpus/:

• common, core, phupha, util — marked +SKIP (require corpus downloads)

pythainlp/tools/:

• misspell, path — marked +SKIP (non-deterministic or environment-specific)

pythainlp/tag/:

• locations, named_entity, pos_tag, thai_nner, thainer, tltk — marked +SKIP (require NER/POS models)

pythainlp/translate/:

• core, en_th, small100, th_fr, zh_th — marked +SKIP (require translation models)

pythainlp/augment/:

• lm/phayathaibert, lm/wangchanberta, word2vec/bpemb_wv, word2vec/ltw2v, word2vec/thai2fit, wordnet — marked +SKIP (require neural models)

pythainlp/benchmarks/:

• metrics — live doctests with verified outputs (pure computation)

pythainlp/chat/, pythainlp/chunk/, pythainlp/classify/, pythainlp/coref/, pythainlp/el/, pythainlp/generate/, pythainlp/khavee/, pythainlp/lm/, pythainlp/parse/, pythainlp/phayathaibert/, pythainlp/spell/, pythainlp/summarize/, pythainlp/ulmfit/, pythainlp/word_vector/, pythainlp/wsd/:

• All examples marked +SKIP (require ML models or optional dependencies)

Your checklist for this pull request

• Passed code styles and structures
• Passed code linting checks and unit test

[coveralls]

coverage: 66.633%. remained the same
when pulling 7892663 on copilot/update-documentation-and-doctests
into 9dfae5a on dev.

[Copilot]

Pull request overview

This PR focuses on improving PyThaiNLP’s documentation quality by converting docstring :Example: sections (primarily under pythainlp/util/) into runnable Python doctests and by cleaning up docstring formatting/typos across the codebase.

Changes:

• Convert many :Example: docstring blocks from RST literal blocks (:: + # output:) to doctest prompts (>>>) with concrete expected outputs.
• Standardize and clarify docstrings (params/return types, wording, typos, references) across multiple modules.
• Add/refresh a CHANGELOG.md “[Unreleased]” entry describing the documentation/doctest cleanup.

Reviewed changes

Copilot reviewed 55 out of 55 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pythainlp/word_vector/core.py	Removes redundant __init__ docstring (class docstring remains).
pythainlp/wangchanberta/init.py	Adds module docstring.
pythainlp/util/wordtonum.py	Converts :Example: blocks to doctest; docstring wording updates.
pythainlp/util/trie.py	Converts :Example: block to doctest.
pythainlp/util/time.py	Refines parameter docs for time_data.
pythainlp/util/thai.py	Docstring refactors; examples formatting changed (see comments).
pythainlp/util/syllable.py	Converts :Example: blocks to doctest.
pythainlp/util/strftime.py	Fixes incorrect function reference in docs.
pythainlp/util/spell_words.py	Docstring param/return type cleanup.
pythainlp/util/phoneme.py	Improves reference formatting and clarifies comments.
pythainlp/util/numtoword.py	Converts :Example: blocks to doctest.
pythainlp/util/normalize.py	Converts :Example: blocks to doctest; docstring typing/deprecation markup updates.
pythainlp/util/morse.py	Converts :Example: blocks to doctest; docstring cleanup.
pythainlp/util/lcs.py	Converts :Example: block to doctest.
pythainlp/util/keywords.py	Docstring formatting fixes for examples.
pythainlp/util/keyboard.py	Converts examples to doctest and updates parameter docs.
pythainlp/util/encoding.py	Fixes encoding cookie; converts examples to doctest.
pythainlp/util/emojiconv.py	Converts :Example: block to doctest.
pythainlp/util/digitconv.py	Converts :Example: blocks to doctest; docstring restructuring.
pythainlp/util/date.py	Fixes incorrect example output comment.
pythainlp/util/collate.py	Converts :Example: block to doctest.
pythainlp/util/abbreviation.py	Updates return type docs to match typing.
pythainlp/ulmfit/tokenizer.py	Docstring rewrite/cleanup and doctest formatting alignment.
pythainlp/ulmfit/core.py	Docstring cleanup + corrected exception type documentation.
pythainlp/transliterate/thai2rom.py	Adds short summary + missing :rtype:.
pythainlp/transliterate/lookup.py	Docstring clarity improvements.
pythainlp/transliterate/iso_11940.py	Docstring clarity improvements + :rtype:.
pythainlp/transliterate/core.py	Fixes typo in documented engine list.
pythainlp/translate/core.py	Docstring formatting fix + clearer return typing docs.
pythainlp/tools/path.py	Updates example output path to be less version-specific.
pythainlp/tokenize/tcc.py	Fixes return-type description mismatch (set vs list).
pythainlp/tokenize/longest.py	Docstring wording/formatting cleanup.
pythainlp/tokenize/etcc.py	Fixes duplicated :return: and corrects :rtype:.
pythainlp/tokenize/core.py	Extensive docstring formatting/typing improvements across APIs.
pythainlp/tag/pos_tag.py	Removes duplicated/incorrect option docs; fixes example typo.
pythainlp/tag/_tag_perceptron.py	Fixes doctest continuation formatting for list literal.
pythainlp/summarize/core.py	Docstring standardization + adds missing :rtype:.
pythainlp/spell/pn.py	Adds SPDX headers; improves docstring typing/formatting.
pythainlp/soundex/metasound.py	Fixes typo in example ())).
pythainlp/soundex/complete_soundex.py	Updates documented expected outputs; doctest examples present (see comments).
pythainlp/morpheme/word_formation.py	Docstring clarity improvements.
pythainlp/lm/text_util.py	Docstring clarity improvements.
pythainlp/khavee/core.py	Docstring grammar fixes.
pythainlp/generate/core.py	Docstring clarity improvements + corrected :rtype:.
pythainlp/corpus/util.py	Docstring corrections + example fixes.
pythainlp/corpus/tnc.py	Docstring formatting and reference cleanup.
pythainlp/corpus/core.py	Converts ad-hoc @param docs to Sphinx-style :param:.
pythainlp/corpus/common.py	Updates corpus file references + docstring return typing cleanup.
pythainlp/cli/misspell.py	Adds module docstring.
pythainlp/cli/benchmark.py	Adds module docstring.
pythainlp/classify/param_free.py	Docstring expansions for save/load.
pythainlp/benchmarks/word_tokenization.py	Docstring clarity improvements + minor signature docs fixes.
pythainlp/ancient/currency.py	Fixes grammar in error message (“supported”).
pythainlp/ancient/aksonhan.py	Docstring clarity/grammar improvements.
CHANGELOG.md	Adds “[Unreleased]” entry describing the docs/doctest cleanup.

Comments suppressed due to low confidence (1)

pythainlp/util/thai.py:316

• The PR aims to convert :Example: blocks to runnable doctests, but this example is still written as an RST literal block (::) with print(...) and # output: comments. doctest won’t execute/verify it as-is; please convert to >>> style (and avoid print) or mark it as skipped if it relies on optional dependencies.

[bact]

Some strftime doctests are wrong (the 1:40 AM ones). Need to fix that.
Need more reviews on others as well.

[bact]

All wrong doctests fixed. doctests enabled as much as possible. Still skipped those required optional dependencies.

[Copilot]

Pull request overview

Copilot reviewed 98 out of 98 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 98 out of 98 changed files in this pull request and generated 1 comment.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.1% Duplication on New Code

See analysis details on SonarQube Cloud