{{tag>dev python code documentation}}

:TODO_DOCUPDATE:

====== 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 [[https://peps.python.org/pep-0257/|PEP 257]].

[[dev/python/annotations|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

<code python>
"""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
</code>

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
<code python>
"""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
"""
</code>


===== Références =====

  * https://www.tutorialspoint.com/documentation-generation-using-the-pydoc-module-in-python
  * https://realpython.com/documenting-python-code/
  * https://towardsdatascience.com/documenting-python-code-with-sphinx-554e1d6c4f6d?gi=4be44bfeb728
  * https://sphinx-tutorial.readthedocs.io/step-1/
  * https://docutils.sourceforge.io/rst.html#user-documentation
  * https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
  * https://www.devdungeon.com/content/restructuredtext-rst-tutorial-0
  * https://www.datacamp.com/tutorial/docstrings-python
  * https://gist.github.com/jesugmz/d83b5e9de7ccc16f71c02adf7d2f3f44