documenting prosody: tamam

Sphinx/source/index.rst

@@ -3,12 +3,13 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Aruudy documentation!
-==================================
+.. automodapi:: aruudy.poetry.prosody
+    :no-inheritance-diagram:
 
-.. toctree::
-    :maxdepth: 2
-    :caption: Contents:
 
-.. automodapi:: aruudy.poetry.prosody
+.. automodapi:: aruudy.poetry.meter
+    :no-inheritance-diagram:
+
+
+.. automodapi:: aruudy.poetry.foot
     :no-inheritance-diagram:

aruudy/poetry/prosody.py

@@ -19,6 +19,13 @@
 # limitations under the License.
 #
 
+"""This module is used for prosody tasks:
+        - normalize a text
+        - find prosody form of a text
+        - find the meter
+
+"""
+
 import re
 from aruudy.poetry import meter, foot
 
@@ -33,15 +40,17 @@
 
 
 def normalize(text):
-    """Normalize a given text, by:
+    """Normalize a given text.
+
+    The text is normalized by:
         - deleting non Arabic characters.
         - Deleting Tatweel (a character used as ligature )
-        - Vocalize and correct letters
+        - Vocalizing and correcting letters
 
     Parameters
     ----------
     text : str
-        The text you want to normalize.
+        The text to be normalized.
 
     Returns
     -------
@@ -210,13 +219,63 @@ def _prosody_add(text):
 
 
 def prosody_form(text):
+    """Generates the prosody form.
+
+    The prosody form is generated by:
+        - deleting some letters such as al-
+        - adding some letters; for example, shadda.
+
+    Parameters
+    ----------
+    text : str
+        A normal vocalized Arabic text.
+
+    Returns
+    -------
+    str
+        The text in its prosody form.
+
+    """
     res = text
     res = _prosody_del(text)
     res = _prosody_add(res)
     return res
 
 
 class Shatr(object):
+    """Shatr (Hemistich) object.
+
+    In Arabic, a verse is composed of two hemistiches (shatr).
+    This object will contain all information about a given text.
+
+    Parameters
+    ----------
+    text : str
+        The text to be analysed.
+
+    Attributes
+    ----------
+    orig : str
+        the original input text.
+    norm : str
+        the text after normalization.
+    prosody : str
+        prosody form of a text.
+    ameter : str
+        the Arabic meter using "w" as watad (peg) and "s" as sabab (cord).
+    emeter : str
+        the English meter using "-" for long syllables and "u" for short ones.
+    bahr : Bahr
+        The bahr (meter) of the input text.
+    parts : list(dict)
+        The text split into different parts.
+        Each part is a dict with these components:
+            - emeter: the english meter of that part
+            - type: the type of that part: is it regular or else
+            - part: the text of that part
+            - mnemonic: the mnemonic text of that part
+
+    """
     def __init__(self, text):
         self.orig = text
         self.norm = normalize(text)
@@ -232,6 +291,21 @@ def __init__(self, text):
                 part["type"] = foot.ZUHAF_ILLA[part["type"]]
 
     def to_dict(self, bahr=False):
+        """Generates a dict object of the Bahr.
+
+        Parameters
+        ----------
+        bahr : bool
+            if true: the bahr object will be dictionarized too.
+            By default, it is False. Hence, the "bahr" is an object of
+            type Bahr
+
+        Returns
+        -------
+        dict
+            A dictionary object describing the Shatr.
+
+        """
         res = {
             "norm": self.norm,
             "prosody": self.prosody,
@@ -251,4 +325,17 @@ def __init__(self, text, sep="\t"):
         self.original = text
 
 def process_shatr(text):
+    """process a shatr.
+
+    Parameters
+    ----------
+    text : str
+        The text representing the shatr (part of verse).
+
+    Returns
+    -------
+    Shatr
+        The Shatr containing information about the text.
+
+    """
     return Shatr(text)