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

CHANGELOG.md

@@ -17,6 +17,13 @@ and this project adheres to
 - Full release notes: <https://github.com/PyThaiNLP/pythainlp/releases>
 - Commit history: <https://github.com/PyThaiNLP/pythainlp/compare/v5.3.1...v5.3.3>
 
+## [Unreleased]
+
+### Changed
+
+- Fix doctests, docstring formatting, typos, and outdated content
+  across all modules (#1392).
+
 ## [5.3.3] - 2026-03-26
 
 Security fixes and thai2rom_onnx bug fixes.

pythainlp/ancient/aksonhan.py

@@ -29,28 +29,24 @@
 def aksonhan_to_current(word: str) -> str:
     """Convert AksonHan words to current Thai words
 
-    AksonHan (อักษรหัน) writes down two consonants for the \
-    spelling of the /a/ vowels. (สระ อะ).
+    AksonHan (อักษรหัน) writes two consonants to spell
+    the short /a/ vowel (สระ อะ).
 
-    Today, รร is an aksonHan word that is still used in Thai.
+    Today, รร is an aksonhan pattern still used in Thai.
 
     :param str word: Thai word
     :return: Thai AksonHan to be converted to current Thai word
     :rtype: str
 
     :Example:
-    ::
 
-        from pythainlp.ancient import aksonhan_to_current
-
-        print(aksonhan_to_current("จกก"))
-        # output: จัก
-
-        print(aksonhan_to_current("บงงคบบ"))
-        # output: บังคับ
-
-        print(aksonhan_to_current("สรรเพชญ")) # รร is still used.
-        # output: สรรเพชญ
+        >>> from pythainlp.ancient import aksonhan_to_current
+        >>> print(aksonhan_to_current("จกก"))
+        จัก
+        >>> print(aksonhan_to_current("บงงคบบ"))
+        บังคับ
+        >>> print(aksonhan_to_current("สรรเพชญ"))  # รร is still used.
+        สรรเพชญ
 
     """
     if len(word) < 3:

pythainlp/ancient/currency.py

@@ -26,22 +26,10 @@ def convert_currency(value: float, from_unit: str) -> dict[str, float]:
     :rtype: dict[str, float]
 
     :Example:
-    ::
 
-        from pythainlp.ancient import convert_currency
-
-        print(convert_currency(8, "บาท"))
-        # output:
-        # {
-        #  'เบี้ย': 51200.0,
-        #  'อัฐ': 512.0,
-        #  'ไพ': 256.0,
-        #  'เฟื้อง': 64.0,
-        #  'สลึง': 32.0,
-        #  'บาท': 8.0,
-        #  'ตำลึง': 2.0,
-        #  'ชั่ง': 0.1
-        # }
+        >>> from pythainlp.ancient import convert_currency
+        >>> print(convert_currency(8, "บาท"))
+        {'เบี้ย': 51200.0, 'อัฐ': 512.0, 'ไพ': 256.0, 'เฟื้อง': 64.0, 'สลึง': 32.0, 'บาท': 8.0, 'ตำลึง': 2.0, 'ชั่ง': 0.1}
 
     """
     conversion_factors_to_att = {
@@ -57,7 +45,7 @@ def convert_currency(value: float, from_unit: str) -> dict[str, float]:
 
     if from_unit not in conversion_factors_to_att:
         raise NotImplementedError(
-            f"Currency unit '{from_unit}' is not support."
+            f"Currency unit '{from_unit}' is not supported."
         )
 
     # start from 'อัฐ'

pythainlp/augment/lm/phayathaibert.py

@@ -80,14 +80,13 @@ def augment(
         :rtype: List[str]
 
         :Example:
-        ::
 
-            from pythainlp.augment.lm import ThaiTextAugmenter
+            >>> from pythainlp.augment.lm import ThaiTextAugmenter  # doctest: +SKIP
 
-            aug = ThaiTextAugmenter()
-            aug.augment("ช้างมีทั้งหมด 50 ตัว บน", num_args=5)
+            >>> aug = ThaiTextAugmenter()  # doctest: +SKIP
+            >>> aug.augment("ช้างมีทั้งหมด 50 ตัว บน", num_args=5)  # doctest: +SKIP
 
-            # output = ['ช้างมีทั้งหมด 50 ตัว บนโลกใบนี้ครับ.',
+            ['ช้างมีทั้งหมด 50 ตัว บนโลกใบนี้ครับ.',
                 'ช้างมีทั้งหมด 50 ตัว บนพื้นดินครับ...',
                 'ช้างมีทั้งหมด 50 ตัว บนท้องฟ้าครับ...',
                 'ช้างมีทั้งหมด 50 ตัว บนดวงจันทร์.‼',

pythainlp/augment/lm/wangchanberta.py

@@ -76,14 +76,13 @@ def augment(self, sentence: str, num_replace_tokens: int = 3) -> list[str]:
         :rtype: List[str]
 
         :Example:
-        ::
 
-            from pythainlp.augment.lm import Thai2transformersAug
+            >>> from pythainlp.augment.lm import Thai2transformersAug  # doctest: +SKIP
 
-            aug = Thai2transformersAug()
+            >>> aug = Thai2transformersAug()  # doctest: +SKIP
 
-            aug.augment("ช้างมีทั้งหมด 50 ตัว บน")
-            # output: ['ช้างมีทั้งหมด 50 ตัว บนโลกใบนี้',
+            >>> aug.augment("ช้างมีทั้งหมด 50 ตัว บน")  # doctest: +SKIP
+            ['ช้างมีทั้งหมด 50 ตัว บนโลกใบนี้',
              'ช้างมีทั้งหมด 50 ตัว บนสุด',
              'ช้างมีทั้งหมด 50 ตัว บนบก',
              'ช้างมีทั้งหมด 50 ตัว บนนั้น',

pythainlp/augment/word2vec/bpemb_wv.py

@@ -60,13 +60,12 @@ def augment(
         :return: list of synonyms
         :rtype: list[str]
         :Example:
-        ::
 
-            from pythainlp.augment.word2vec.bpemb_wv import BPEmbAug
+            >>> from pythainlp.augment.word2vec.bpemb_wv import BPEmbAug  # doctest: +SKIP
 
-            aug = BPEmbAug()
-            aug.augment("ผมเรียน", n_sent=2, p=0.5)
-            # output: ['ผมสอน', 'ผมเข้าเรียน']
+            >>> aug = BPEmbAug()  # doctest: +SKIP
+            >>> aug.augment("ผมเรียน", n_sent=2, p=0.5)  # doctest: +SKIP
+            ['ผมสอน', 'ผมเข้าเรียน']
         """
         self.sentence: str = sentence.replace(" ", "▁")
         self.temp: list[tuple[str, ...]] = self.aug.augment(

pythainlp/augment/word2vec/ltw2v.py

@@ -56,12 +56,11 @@ def augment(
         :rtype: List[Tuple[str]]
 
         :Example:
-        ::
 
-            from pythainlp.augment.word2vec import LTW2VAug
+            >>> from pythainlp.augment.word2vec import LTW2VAug  # doctest: +SKIP
 
-            aug = LTW2VAug()
-            aug.augment("ผมเรียน", n_sent=2, p=0.5)
-            # output: [('เขา', 'เรียนหนังสือ'), ('เขา', 'สมัครเรียน')]
+            >>> aug = LTW2VAug()  # doctest: +SKIP
+            >>> aug.augment("ผมเรียน", n_sent=2, p=0.5)  # doctest: +SKIP
+            [('เขา', 'เรียนหนังสือ'), ('เขา', 'สมัครเรียน')]
         """
         return self.aug.augment(sentence, n_sent, p)

pythainlp/augment/word2vec/thai2fit.py

@@ -57,12 +57,11 @@ def augment(
         :rtype: List[Tuple[str]]
 
         :Example:
-        ::
 
-            from pythainlp.augment.word2vec import Thai2fitAug
+            >>> from pythainlp.augment.word2vec import Thai2fitAug  # doctest: +SKIP
 
-            aug = Thai2fitAug()
-            aug.augment("ผมเรียน", n_sent=2, p=0.5)
-            # output: [('พวกเรา', 'เรียน'), ('ฉัน', 'เรียน')]
+            >>> aug = Thai2fitAug()  # doctest: +SKIP
+            >>> aug.augment("ผมเรียน", n_sent=2, p=0.5)  # doctest: +SKIP
+            [('พวกเรา', 'เรียน'), ('ฉัน', 'เรียน')]
         """
         return self.aug.augment(sentence, n_sent, p)

pythainlp/augment/wordnet.py

@@ -191,13 +191,12 @@ def augment(
         :rtype: list[list[str]]
 
         :Example:
-        ::
 
-            from pythainlp.augment import WordNetAug
+            >>> from pythainlp.augment import WordNetAug  # doctest: +SKIP
 
-            aug = WordNetAug()
-            aug.augment("เราชอบไปโรงเรียน")
-            # output: [('เรา', 'ชอบ', 'ไป', 'ร.ร.'),
+            >>> aug = WordNetAug()  # doctest: +SKIP
+            >>> aug.augment("เราชอบไปโรงเรียน")  # doctest: +SKIP
+            [('เรา', 'ชอบ', 'ไป', 'ร.ร.'),
              ('เรา', 'ชอบ', 'ไป', 'รร.'),
              ('เรา', 'ชอบ', 'ไป', 'โรงเรียน'),
              ('เรา', 'ชอบ', 'ไป', 'อาคารเรียน'),

pythainlp/benchmarks/metrics.py

@@ -131,24 +131,22 @@ def bleu_score(
     :rtype: BleuScore
 
     :Example:
-    ::
 
-        from pythainlp.benchmarks import bleu_score
-
-        references = ["สวัสดีครับ วันนี้อากาศดีมาก"]
-        hypotheses = ["สวัสดีค่ะ วันนี้อากาศดี"]
-        score = bleu_score(references, hypotheses)
-        print(f"BLEU score: {score['bleu']:.2f}")
-
-    ::
-
-        # Multiple references per hypothesis
-        references = [
-            ["สวัสดีครับ", "สวัสดีค่ะ"],  # two refs for first hypothesis
-            ["ลาก่อนครับ", "ลาก่อนค่ะ"],  # two refs for second hypothesis
-        ]
-        hypotheses = ["สวัสดี", "ลาก่อน"]
-        score = bleu_score(references, hypotheses)
+        >>> from pythainlp.benchmarks import bleu_score
+
+        >>> references = ["สวัสดีครับ วันนี้อากาศดีมาก"]
+        >>> hypotheses = ["สวัสดีค่ะ วันนี้อากาศดี"]
+        >>> score = bleu_score(references, hypotheses)
+        >>> print(f"BLEU score: {score['bleu']:.2f}")
+        BLEU score: 28.12
+
+        >>> # Multiple references per hypothesis
+        >>> references = [
+        ...     ["สวัสดีครับ", "สวัสดีค่ะ"],  # two refs for first hypothesis
+        ...     ["ลาก่อนครับ", "ลาก่อนค่ะ"],  # two refs for second hypothesis
+        ... ]
+        >>> hypotheses = ["สวัสดี", "ลาก่อน"]
+        >>> score = bleu_score(references, hypotheses)
     """
     from pythainlp.tokenize import word_tokenize
 
@@ -282,16 +280,18 @@ def rouge_score(
     :rtype: dict[str, RougeScore]
 
     :Example:
-    ::
-
-        from pythainlp.benchmarks import rouge_score
 
-        reference = "สวัสดีครับ วันนี้อากาศดีมาก"
-        hypothesis = "สวัสดีค่ะ วันนี้อากาศดี"
-        scores = rouge_score(reference, hypothesis)
-        print(f"ROUGE-1 F-measure: {scores['rouge1']['fmeasure']:.4f}")
-        print(f"ROUGE-2 F-measure: {scores['rouge2']['fmeasure']:.4f}")
-        print(f"ROUGE-L F-measure: {scores['rougeL']['fmeasure']:.4f}")
+        >>> from pythainlp.benchmarks import rouge_score
+
+        >>> reference = "สวัสดีครับ วันนี้อากาศดีมาก"
+        >>> hypothesis = "สวัสดีค่ะ วันนี้อากาศดี"
+        >>> scores = rouge_score(reference, hypothesis)
+        >>> print(f"ROUGE-1 F-measure: {scores['rouge1']['fmeasure']:.4f}")
+        ROUGE-1 F-measure: 0.6000
+        >>> print(f"ROUGE-2 F-measure: {scores['rouge2']['fmeasure']:.4f}")
+        ROUGE-2 F-measure: 0.2500
+        >>> print(f"ROUGE-L F-measure: {scores['rougeL']['fmeasure']:.4f}")
+        ROUGE-L F-measure: 0.6000
     """
     from pythainlp.tokenize import word_tokenize
 
@@ -391,14 +391,14 @@ def word_error_rate(
     :rtype: float
 
     :Example:
-    ::
 
-        from pythainlp.benchmarks import word_error_rate
+        >>> from pythainlp.benchmarks import word_error_rate
 
-        reference = "สวัสดีครับ วันนี้อากาศดีมาก"
-        hypothesis = "สวัสดีค่ะ วันนี้อากาศดี"
-        wer = word_error_rate(reference, hypothesis)
-        print(f"WER: {wer:.4f}")
+        >>> reference = "สวัสดีครับ วันนี้อากาศดีมาก"
+        >>> hypothesis = "สวัสดีค่ะ วันนี้อากาศดี"
+        >>> wer = word_error_rate(reference, hypothesis)
+        >>> print(f"WER: {wer:.4f}")
+        WER: 0.4000
     """
     from pythainlp.tokenize import word_tokenize
 
@@ -469,14 +469,14 @@ def character_error_rate(
     :rtype: float
 
     :Example:
-    ::
 
-        from pythainlp.benchmarks import character_error_rate
+        >>> from pythainlp.benchmarks import character_error_rate
 
-        reference = "สวัสดีครับ"
-        hypothesis = "สวัสดีค่ะ"
-        cer = character_error_rate(reference, hypothesis)
-        print(f"CER: {cer:.4f}")
+        >>> reference = "สวัสดีครับ"
+        >>> hypothesis = "สวัสดีค่ะ"
+        >>> cer = character_error_rate(reference, hypothesis)
+        >>> print(f"CER: {cer:.4f}")
+        CER: 0.3000
     """
     # Work with characters directly (no tokenization needed)
     ref_chars = list(reference)