Différences

Ci-dessous, les différences entre deux révisions de la page.

--- dev:python:documentation_du_code [2022/12/28 22:58] – yoann
+++ dev:python:documentation_du_code [2023/01/03 23:29] (Version actuelle) – yoann
@@ Ligne 5: / Ligne 5: @@
 ====== Python : Génération de la documentation ======
-La documentation embarquée dans le code peut être extraite et mise en forme par le module pydoc.
+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>
-Les conventions d'écriture des docstring sont abordées dans la [[https://peps.python.org/pep-0257/|PEP 257]]
 ===== 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

wikinotes

Outils pour utilisateurs

Outils du site

Différences

Outils de la page