Python : Génération de la documentation
La documentation embarquée dans le code (les docstrings) peut être extraite et mise en forme par le module pydoc.
Les conventions d'écriture des docstring sont abordées dans la PEP 257.
Les annotations de types (type hinting) participent également à la lisibilité et la documentation du code.
Comme pour les commentaires, la recommandation de longueur de ligne d'une docstring est de 72 caractères.
- class docstrings : Description des classes et des méthodes de classe. La docstring doit être placée immédiatement sous la classe ou la méthode avec une indentation d'un niveau
Le formatage général recommandé d'une docstring comprend:
- La description brève
- Un saut de ligne
- Le développement de la docstring
- Une ligne vide
"""Description brève Corps de la docstring. On développe ici la documentation nécessaire à l'exploitation correcte du code. """ # Notez la ligne vide séparant la docstring du code qui suivra ci-dessous
Des formatages particuliers peuvent être utilisés au sein de la doctring comme reStructuredText. Ils sont ensuite exploités par des outils tiers comme Sphinx pour générer de la documentation sous différents dormat (html, man etc) ou vérifier le code.
Ci-dessous un exemple de docstring formatée avec reStructuredText
"""Gets and prints the spreadsheet's header columns
:param file_loc: The file location of the spreadsheet
:type file_loc: str
:param print_cols: A flag used to print the columns to the console
(default is False)
:type print_cols: bool
:returns: a list of strings representing the header columns
:rtype: list
"""