doc: add more examples

README-vi.md

@@ -75,4 +75,32 @@ True
 CccdResult(id='123456', is_male=False, birth_year=1992, birth_country='vn', birth_province='Bắc Giang')
 ```
 
+- Để lấy dấu thanh từ một đoạn văn hoặc chữ tiếng Việt:
+
+```python
+>>> from ctnx.misc import separate_tone
+>>> separate_tone("Đẩu")
+('Đâu', '?')
+>>> toneNames = {'': 'thanh', '/': 'sắc', '\\': 'huyền', '?': 'hỏi', '~': 'ngã', '.': 'nặng'}
+>>> ' '.join(toneNames[separate_tone(syll)[1]] for syll in "Tôi thầm cảm ơn Đẩu đã giữ mình ở nán lại".split(' '))
+'thanh huyền hỏi thanh hỏi ngã ngã huyền hỏi sắc nặng'
+```
+
+- Để thao tác với các âm tiết (còn gọi là chữ hoặc tiếng) tiếng Việt:
+
+```python
+>>> from ctnx.syllable import Syllable
+>>> text = "ba ngày một trận nhẹ năm ngày một trận nặng"
+>>> a = [Syllable.from_string(x) for x in text.split(' ')]
+>>> a
+[Syllable(b, a, ), Syllable(ng, ay, , \), Syllable(m, ô, t, .), Syllable(tr, â, n, .), Syllable(nh, e, , .), Syllable(n, ă, m), Syllable(ng, ay, , \), Syllable(m, ô, t, .), Syllable(tr, â, n, .), Syllable(n, ă, ng, .)]
+>>> for syll in a:
+...     syll.onset = 'nh'
+...
+>>> a
+[Syllable(nh, a, ), Syllable(nh, ay, , \), Syllable(nh, ô, t, .), Syllable(nh, â, n, .), Syllable(nh, e, , .), Syllable(nh, ă, m), Syllable(nh, ay, , \), Syllable(nh, ô, t, .), Syllable(nh, â, n, .), Syllable(nh, ă, ng, .)]
+>>> ' '.join(str(x) for x in a)
+'nha nhày nhột nhận nhẹ nhăm nhày nhột nhận nhặng'
+```
+
 Để biết thêm cách sử dụng, hãy xem tài liệu (tiếng Anh) nằm ở [chiecthuyenngoaixa.readthedocs.io](https://chiecthuyenngoaixa.readthedocs.io/en/latest/).

README.md

@@ -83,4 +83,32 @@ True
 CccdResult(id='123456', is_male=False, birth_year=1992, birth_country='vn', birth_province='Bắc Giang')
 ```
 
+- To extract tones from a Vietnamese syllable or text:
+
+```python
+>>> from ctnx.misc import separate_tone
+>>> separate_tone("Đẩu")
+('Đâu', '?')
+>>> toneNames = {'': 'thanh', '/': 'sắc', '\\': 'huyền', '?': 'hỏi', '~': 'ngã', '.': 'nặng'}
+>>> ' '.join(toneNames[separate_tone(syll)[1]] for syll in "Tôi thầm cảm ơn Đẩu đã giữ mình ở nán lại".split(' '))
+'thanh huyền hỏi thanh hỏi ngã ngã huyền hỏi sắc nặng'
+```
+
+- To manipulate Vietnamese syllables:
+
+```python
+>>> from ctnx.syllable import Syllable
+>>> text = "ba ngày một trận nhẹ năm ngày một trận nặng"
+>>> a = [Syllable.from_string(x) for x in text.split(' ')]
+>>> a
+[Syllable(b, a, ), Syllable(ng, ay, , \), Syllable(m, ô, t, .), Syllable(tr, â, n, .), Syllable(nh, e, , .), Syllable(n, ă, m), Syllable(ng, ay, , \), Syllable(m, ô, t, .), Syllable(tr, â, n, .), Syllable(n, ă, ng, .)]
+>>> for syll in a:
+...     syll.onset = 'nh'
+...
+>>> a
+[Syllable(nh, a, ), Syllable(nh, ay, , \), Syllable(nh, ô, t, .), Syllable(nh, â, n, .), Syllable(nh, e, , .), Syllable(nh, ă, m), Syllable(nh, ay, , \), Syllable(nh, ô, t, .), Syllable(nh, â, n, .), Syllable(nh, ă, ng, .)]
+>>> ' '.join(str(x) for x in a)
+'nha nhày nhột nhận nhẹ nhăm nhày nhột nhận nhặng'
+```
+
 For further usages, see the documentation, which is hosted on [chiecthuyenngoaixa.readthedocs.io](https://chiecthuyenngoaixa.readthedocs.io/en/latest/).

ctnx/syllable.py

@@ -286,7 +286,7 @@ def vowel(self) -> str:
             return self.nucleus
 
     @property
-    def rhyme(self) -> str:
-        """The rhyme of the syllable, which is the combination of the vowel and the coda."""
+    def rime(self) -> str:
+        """The rime of the syllable, which is the combination of the vowel and the coda."""
 
         return self.vowel + self.coda

docs/source/usage.rst

@@ -76,4 +76,34 @@ Other functions and classes are put into separate sub-modules. For example:
         >>> validation.parse_cccd("024192123456")
         CccdResult(id='123456', is_male=False, birth_year=1992, birth_country='vn', birth_province='Bắc Giang')
 
+* To extract tones from a Vietnamese syllable or text:
+
+    .. doctest::
+        :pyversion: >= 3.8
+
+        >>> from ctnx.misc import separate_tone
+        >>> separate_tone("Đẩu")
+        ('Đâu', '?')
+        >>> toneNames = {'': 'thanh', '/': 'sắc', '\\': 'huyền', '?': 'hỏi', '~': 'ngã', '.': 'nặng'}
+        >>> ' '.join(toneNames[separate_tone(syll)[1]] for syll in "Tôi thầm cảm ơn Đẩu đã giữ mình ở nán lại".split(' '))
+        'thanh huyền hỏi thanh hỏi ngã ngã huyền hỏi sắc nặng'
+
+* To manipulate Vietnamese syllables:
+
+    .. doctest::
+        :pyversion: >= 3.8
+
+        >>> from ctnx.syllable import Syllable
+        >>> text = "ba ngày một trận nhẹ năm ngày một trận nặng"
+        >>> a = [Syllable.from_string(x) for x in text.split(' ')]
+        >>> a
+        [Syllable(b, a, ), Syllable(ng, ay, , \), Syllable(m, ô, t, .), Syllable(tr, â, n, .), Syllable(nh, e, , .), Syllable(n, ă, m), Syllable(ng, ay, , \), Syllable(m, ô, t, .), Syllable(tr, â, n, .), Syllable(n, ă, ng, .)]
+        >>> for syll in a:
+        ...     syll.onset = 'nh'
+        ...
+        >>> a
+        [Syllable(nh, a, ), Syllable(nh, ay, , \), Syllable(nh, ô, t, .), Syllable(nh, â, n, .), Syllable(nh, e, , .), Syllable(nh, ă, m), Syllable(nh, ay, , \), Syllable(nh, ô, t, .), Syllable(nh, â, n, .), Syllable(nh, ă, ng, .)]
+        >>> ' '.join(str(x) for x in a)
+        'nha nhày nhột nhận nhẹ nhăm nhày nhột nhận nhặng'
+
 See :doc:`generated/api` section for full references.