Dans cet article, nous allons passer en revue les (très) bases de la génération de documentation à partir de docstrings dans votre code Python. C’est un peu compliqué, mais après l’avoir fait une fois, il sera facile de répéter le processus dans chaque nouveau projet.

Pour nos besoins, nous supposerons que vous (1) croyez à la valeur de documenter votre code; (2) souhaitez générer des documents à partir de vos chaînes de documents et (3), avez choisi d’utiliser Sphinx pour accomplir le travail.

Enfin, il est supposé que vous avez déjà configuré un environnement virtuel distinct pour votre application. Pour ceux qui sont intéressés, j’aime beaucoup le gestionnaire d’environnement pyenv. Il a même un installateur pratique.

Vous devrez installer sphinx via pip. Au minimum, vous aurez besoin de la version 1.3, mais à moins d’avoir de bonnes raisons, vous devez installer la version la plus récente.

$ pip install sphinx

Étape 2: Configurez votre projet avec Quickstart

Lorsque vous installez le package sphinx, un certain nombre d’utilitaires de ligne de commande sont également configurés.

L’un d’eux, sphinx-quickstart générera rapidement un fichier de configuration de base et une structure de répertoire pour votre documentation.

Exécutez cette commande dans le répertoire de base de votre projet (c’est-à-dire la racine du dépôt Git). Il vous posera un certain nombre de questions qui détermineront ses actions. Vous pouvez généralement accepter les valeurs par défaut, mais voici quelques suggestions pour savoir quand s’écarter de la valeur par défaut :

Une fois le programme exécuté, vous remarquerez qu’un nouveau dossier ./docs existe dans votre répertoire de projet. De plus, il y a trois nouveaux fichiers dans ce dossier : conf.pyindex.rst et Makefile.

Étape 3 : Réglage du conf.py File

Le fichier conf.py par défaut généré par l’utilitaire de démarrage rapide mesure environ 170 lignes, donc je n’inclurai pas le tout ici. Il y a cependant quelques éléments que nous devons mettre à jour avant de continuer.

Indiquez à Sphinx l’emplacement de votre package Python

La première chose que nous devons faire est d’indiquer où se trouve le package Python contenant votre code de programme par rapport au fichier conf.py. Si votre structure de répertoire ressemble à ceci:

Vous devrez indiquer dans le fichier conf.py que Sphinx doit monter d’un niveau de répertoire pour trouver le paquet Python.

L’endroit à placer est à la fin de la première section du fichier de configuration. Juste avant les paramètres General Configuration, vous verrez ceci:

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

S’il n’était pas commenté, cela indiquerait que votre paquet se trouve dans le même répertoire que le fichier conf.py. Vous devrez le changer en ceci:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Ajoutez « Napoleon” à la liste des extensions Sphinx à utiliser

Prêt à l’emploi, Sphinx ne comprend que les chaînes de documents écrites dans un texte reStructuredText traditionnel. Si vous avez eu le privilège de travailler avec de telles chaînes de documents, vous saurez qu’elles sont douloureuses à écrire et pas du tout conviviales à lire en les regardant directement dans le code source.

L’extension Napoleon permet à Sphinx de comprendre les chaînes de documents écrites dans deux autres formats populaires : NumPy et Google.

Tout ce que nous avons à faire est d’ajouter sphinx.ext.napoleon à la liste extensions. Lorsque vous avez terminé, cela devrait ressembler à ceci:

extensions = 

Étape 4: Mettre à jour l’index.rst

À ce stade, nous pourrions réellement exécuter le processus de génération pour générer notre documentation. Mais ce serait assez décevant. Voici ce que nous obtiendrions:

Autant que j’aimerais que Sphinx aille trouver nos docstrings pour nous et les arrange bien sans autre configuration, ce n’est pas tout à fait magique.

Pour aller de l’avant, nous devrons apporter quelques modifications mineures à notre fichier index.rst, qui ressemble actuellement à ceci:

Commençons par nous débarrasser du commentaire en haut qui n’est que du bruit:

Maintenant, bien qu’il y ait un certain nombre de choses que nous pourrions faire ici, nous allons nous limiter au strict minimum pour garder ce post à une longueur quelque peu raisonnable.

Voyez-vous cette ligne .. toctree::? C’est ce que Sphinx appelle une directive. Nous devons ajouter des directives autodoc à notre fichier index.rst afin que Sphinx sache sur quels objets de code nous souhaitons utiliser l’extension autodoc.

Je vais aller de l’avant et en ajouter un indiquant à Sphinx que je veux qu’il documente les membres publics de mon module main.py dans le package my_project:

Étape 5: Écrivez vos Docstrings

Nous ne couvrirons pas la façon d’écrire des docstrings dans le style Numpy ou Google dans ce post.

Cependant, voici le code de main.py qui contient quelques docstrings simples de style NumPy qui seront repris par notre directive autodoc :

Étape 6: Générez vos documents !

Il est maintenant temps de récolter les fruits de votre travail. Assurez-vous d’être dans le répertoire ./docs et exécutez ce qui suit: make html

Si vous avez suivi jusqu’à présent, vous devriez voir quelque chose comme ceci:

Tant que vous voyez ce glorieux message build succeeded à la fin, vous êtes prêt à allez voir votre belle création.

Sur la ligne de commande, exécutez open _build/html/index.html (ou ouvrez simplement cette page dans votre navigateur manuellement) et vous devriez voir quelque chose comme ceci:

Prochaines étapes

Nous venons de rayer la surface ici et il y a encore beaucoup de verrues dans notre documentation simple.

Dans le prochain article sur ce sujet, nous approfondirons les directives de l’extension autodoc et obtiendrons un meilleur contrôle du contenu et de l’apparence de notre documentation.