Il y a deux niveaux de documentation :
docstring
).Pour améliorer la lisibilité on peut enrichir la mise en page à l'aide de balises assez discrètes pour que le code reste lisible. Le monde Python propose deux langages pour cela :
rst
)md
)Pour la documentation d'une fonction, il faut aussi choix le style qu'on désire pour décrire les arguments, la valeur de retour et d'autres points moins visibles. Voici les trois styles les plus courants :
La fonction suivante utilise le style Google et le commentaire est écrit en rst
(écrire un commentaire
en md
pose des problèmes d'interprétation pour l'instant).
# %load package/factorial.py
def factorial(n) -> int:
"""
Return n!
Factorial(n) or n! = n * (n-1) * (n-2) * ... * 1 and
0! = 1 (since n! = (n+1)! / (n+1))
Args:
n (int): a positive integer
Returns:
int
Raises:
TypeError: if n is not an int
ValueError: if n < 0
Here are some tests. Note that tests also show how to use the function.
>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> factorial(-2)
Traceback (most recent call last):
...
ValueError: n should be positive
>>> factorial(3.1) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
TypeError:...
"""
if type(n) != int:
raise TypeError('Not an integer')
if n < 0:
raise ValueError('n should be positive')
res = 1
for i in range(2,n+1):
res *= i
return res
À partir de ce commentaire on peut appeler l'aide en ligne ou générer une documentation.
# aide en ligne. help(factorial) donne le même résultat
factorial?
Voici un exemple de docstring
avec le style Numpy :
import numpy as np
np.zeros?
La génération de la documentation nécessite l'utilisation d'un logiciel pour obtenir du HTML ou un autre format. Sphinx est largement utilisé pour cela et voici le résultat :
Il n'entre pas dans le cadre de ce cours d'expliquer l'utilisation de Sphinx. On va simplement donner ici les commandes qui permettent de générer un site web avec l'API de son projet.
Installation à main :
sphinx
et sphinx-autoapi
docs
.cd docs
, puis initier Sphinx : sphinx-quickstart
(accepter les réponses par défaut)index.rst
pour avoir la table des matières ainsi (attention à l'alignement vertical, 'a' en dessous de ':') :.. toctree::
:maxdepth: 2
:caption: Contents:
autoapi/index.rst
conf.py
extensions = ['sphinx.ext.doctest', 'autoapi.extension']
autoapi_type = 'python'
autoapi_dirs = ['../src']
make html
et ouvrir avec votre navigateur _build/html/index.html
.Pour automatiser la mise à jour du site web avec Nox (donc après avoir fait à la main l'installation), on peut ajouter
ces lignes à notre fichier noxfile.py
:
@nox.session(python="3.8")
def docs(session):
"""Build the documentation."""
session.run("make", "-C", "docs/", "html")
Et la mise à jour se fait avec nox -s docs
.
{{ PreviousNext("91 Tests.ipynb", "../lesson3 Object Python/01 Classes and objects.ipynb") }}