La documentation est indispensable pour que des personnes souhaitent utiliser votre application, faire remonter des bugs ou même contribuer. Pour essayer de satisfaire le plus grand nombre, une documentation devrait au moins contenir
- des tutoriels,
- des petits guides sur les domaines
- une documentation de référence (par exemple l’API).
Le fait d’écrire ces différentes parties a d’autres avantages
- se rappeler ce qu’on a fait il y a six mois.
- Avoir un meilleur code.
- Etre un meilleur rédacteur en anglais (issue, email, ...)
Pour écrire de la documentation d’applications Python, sphinx est largement utilisé maintenant. Il s’appuie sur ReadTheDocs pour la diffusion en ligne. Il existe différentes extensions à sphinx qui offrent d’autres fonctionnalités comme nbsphinx qui permet d’intégrer des notebooks jupyter à la documentation finale.
Différents formats peuvent être utilisés pour la rédaction de documentation
- markdown
- restructured text
- notebook jupyter
- ...
Initialiser sa documentation avec sphinx¶
Il vous faut dans un premier temps installer sphinx à l’aide d’une des commandes suivantes
pip install sphinxmamba install sphinxpixi add sphinx
Nous pouvons à présent initier l’arborescence de la documentation demandée par sphinx Pour ce faire
Créer un répertoire
docà la racine de son projetAller dans ce répertoire
Exécuter la commande suivante
sphinx-quickstartRépondre aux questions !!!
Il est toujours possible de changer ses réponses en modifiant le fichier de configuration créé lors de cette phase.
Vous devriez obtenir une arborescence qui ressemble à ça
! tree examples/calculator/docexamples/calculator/doc
├── _build
├── conf.py
├── index.rst
├── make.bat
├── Makefile
├── _static
└── _templates
3 directories, 4 files
Les extensions de sphinx¶
Comme dit précédemment, il en existe de nombreuses. Nous donnons ici un échantillon dont on se sert assez régulièrement pour la documentation de logiciel scientifique.
autodoc¶
Cette extension permet de documenter automatiquement
- des modules,
- des classes,
- des fonctions,
à partir de leur docstring.
Il faut ajouter dans les extensions de conf.py
extensions = [..., “sphinx.ext.autodoc”, ...]
Voici un exemple de docstring
def add(value1, value2): “”“add two values. :param value1: The first value :type value1: float or int :param value2: The second value :type value2: float or int :returns: the addition between value1 and value2 :rtype: float or int “”” pass
Pour insérer la documentation de cette fonction dans la documentation, il suffit de créer un fichier rst avec comme contenu
.. autofunction:: addSi vous souhaitez documenter un module
.. automodule:: mymod
:members:
:undoc-members:Si vous souhaitez documenter un module
.. autoclass:: myclass
:members:
:private-members:
:special-members:Pour plus d’information, voir la page de autodoc.
Il est possible de générer l’ensemble des fichiers rst de son API en utilisant le script sphinx-apidoc.
! sphinx-apidoc -f -o api examples/calculatorLisibilité des docstrings¶
L’utilisation de la sémantique de l’autodoc dans les docstrings est un peu lourde et rend la documentation dans le code difficile à lire.
Vous avez deux extensions qui permettent d’améliorer considérablement la lisibilité
Nous nous intéresserons dans la suite à l’extension numpydoc.
Pour l’utiliser, il faut ajouter dans l’extension dans le fichier conf.py
extensions = [..., "numpydoc", ...]Voici un exemple de documentation avec le style NumPy.
def add(value1, value2):
"""add two values.
Parameters
----------
value1 : float or int
the first value
value2 : float or int
the second value
Returns
-------
float or int
the addition between value1 and value2
"""
passnbsphinx¶
Il est toujours intéressant de mettre des tutoriels dans son package permettant aux nouveaux utilisateurs de se familiariser rapidement avec l’outil. Les notebooks s’y prêtent très bien. nbsphinx permet d’intégrer ces notebooks à la documentation.
Pour installer l’extension, il suffit de faire
pip install nbsphinxou
mamba install nbsphinxPour activer l’extension, il suffit de l’ajouter à la liste extension du fichier conf.py
extensions = [..., 'nbsphinx', ...]Il est possible ensuite de mettre les notebooks dans le toctree au même titre que les fichiers rst.
Read The Docs¶
RTD permet de construire et d’héberger votre documentation sphinx en se basant sur votre CSV (git, mercurial, ...). Chaque tag et branche sont convertis en version et RTD conserve l’historique des différentes versions.
Lorsque vous faites un push sur votre dépôt, RTD lance automatiquement la génération de la documentation ce qui fait que votre documentation est toujours à jour ! Il faut noter également que le multi langue est supporté.
Enfin, deux autres caractéristiques intéressantes: le recherche dans la documentation est plus puissante que celle que vous trouvez dans sphinx de base. La documentation est indexée via elasticsearch et vous pouvez faire des recherche plein texte. Plusieurs formats de sortie sont supportés: html, pdf, zipped html, epub, ...
Le thème¶
Enfin, sachez qu’il existe différents thèmes pour la documentation. RTD a longtemps eu un thème par défaut appelé sphinx_rtd_theme. Depuis l’arrivée de jupyter-book et de myst, les choses évoluent et les sites offrent de plus en plus de possibilités au niveau du placement du contenu et de sa mise en page.
Exercices¶
Le répertoire step0 reprend la dernière étape du TP précédent en ayant ajouté des docstrings de type numpydoc pour chacune des fonctions.
Références¶
- Sphinx tutorial
- blog d’Eric Holscher
- What to write - Jacob Kaplan-Moss
- Teach, Don’t Tell - Steve Losh