Vous avez maintenant un code propre, bien structuré, vérifié par un linter. C’est parfait. Mais qui, à part vous, sait comment utiliser votre projet ? Qui sait ce que fait la fonction update_path ? Qui connaît la théorie mathématique derrière les splines ?
La documentation est souvent le parent pauvre des projets scientifiques. On se dit qu’on la fera plus tard, quand le code sera fini. Mais le code n’est jamais vraiment fini, et la documentation n’est jamais écrite. Pourtant, un projet sans documentation est comme un livre sans titre ni résumé : personne ne saura par où commencer.
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
...
On sait pourquoi documenter et dans quel format écrire. Passons aux choses sérieuses : installer Sphinx et créer la structure de notre documentation. C’est plus simple que vous ne le pensez, vous allez voir.
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
La structure de base est en place. Mais pour l’instant, elle est vide. Le vrai pouvoir de Sphinx, il est dans ses extensions : des modules qui ajoutent des fonctionnalités comme la documentation automatique de l’API, l’intégration de notebooks Jupyter, ou un rendu mathématique avancé. Voyons les plus utiles pour un projet scientifique.
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.
Vous avez maintenant de quoi générer une documentation riche : API automatique, notebooks intégrés, maths avec LaTeX. Mais une doc, ça ne sert à rien si personne ne peut la lire. Voyons comment la publier en ligne, automatiquement.
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, ...
Read The Docs s’occupe de l’hébergement et de la reconstruction automatique. Parlons maintenant de l’apparence : le thème. Parce qu’une documentation agréable à lire, c’est une documentation qu’on a envie de lire.
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é pydata_sphinx_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.
Vous avez à présent une vue d’ensemble de ce que Sphinx peut faire. Il est temps de mettre les mains dans le cambouis et de construire la documentation de splinart de A à Z.
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¶
What to write - Jacob Kaplan-Moss
Teach, Don’t Tell - Steve Losh
Ce qu’on a accompli¶
Nous avons mis en place une documentation complète pour notre projet :
Sphinx comme générateur de documentation
MyST Parser pour écrire en Markdown (plus simple que reStructuredText)
Autodoc + numpydoc pour générer automatiquement la documentation de l’API
nbsphinx pour intégrer des notebooks Jupyter
pydata-sphinx-theme pour un rendu moderne
Vous avez maintenant une documentation qui explique ce que fait le projet, décrit la théorie mathématique sous-jacente, fournit des tutoriels sous forme de notebooks, et documente l’API de manière automatique.
Le meilleur dans tout ça ? À chaque fois que vous modifierez vos docstrings ou vos notebooks, il suffira de relancer la commande de build pour mettre à jour la documentation.