Comment configurer Sphinx pour documenter votre code Python

Sphinx est l'un des outils les plus populaires pour générer de la documentation. Dans la communauté Python, les développeurs utilisent ce logiciel gratuit et open source. Il peut extraire du texte directement de votre code ou de vos fichiers de démarquage, puis l'utiliser pour générer de la documentation dans divers formats tels que texte brut, HTML, PDF et EPUB.

Installer le Sphinx

Avant de configurer Sphinx, jetez un œil à ce qu'il fait et à certaines de ses principales caractéristiques.

Qu'est-ce que le Sphinx et à quoi sert-il ?

Comme mentionné, Sphinx est un générateur de documentation. Par défaut, il utilise le langage de balisage reStructuredText (RST), mais via des extensions tierces, il peut également utiliser Markdown, le populaire langage de balisage de texte brut. Il convertit ensuite ces fichiers RST ou Markdown en HTML, PDF, pages de manuel ou autres formats que vous préférez.

Certaines des fonctionnalités incluses dans Sphinx sont :

• Capacité à générer de la documentation à partir du code.
• Possibilité de référencer différentes pages de document à l'aide de liens automatiques pour les fonctions, les classes, les citations et les termes du glossaire.
• Coloration syntaxique des blocs de code.
• Prise en charge des thèmes qui peuvent modifier l'apparence des documents.
• Définition facile de l'arborescence du document grâce à une table des matières.
• Possibilité d'intégrer des extensions tierces pour ajouter plus de fonctionnalités aux documents, telles que le test d'extraits de code.

Installation du Sphinx

Avant d'installer Sphinx, assurez-vous d'avoir Python 3 installé dans votre environnement de développement. Vous pouvez ensuite utiliser le gestionnaire de paquets pip pour installer Sphinx en exécutant la commande suivante dans votre terminal :

pip installer sphinx

Cela téléchargera et installera Sphinx et ses dépendances.

Après l'installation, exécutez ce qui suit à l'invite de commande.

sphinx-build --version

Si tout a bien fonctionné, vous devriez voir le numéro de version du package Sphinx que vous venez d'installer.

Création d'un nouveau projet Sphinx

Une fois que vous avez installé Sphinx, accédez à votre répertoire de travail et exécutez la commande sphinx-quickstart pour créer un nouveau projet Sphinx.

sphinx-démarrage rapide

Cette commande vous invitera à répondre à une série de questions sur la façon de configurer votre projet Sphinx. Vous pouvez spécifier le nom du projet et utiliser les options par défaut pour les autres questions. À l'avenir, vous souhaiterez peut-être personnaliser les réponses en fonction de votre projet.

Si vous listez le contenu de votre répertoire, vous verrez que cette commande crée des fichiers pour vous. Le conf.py contient les valeurs de configuration et le index.rst sert de page d'accueil de votre documentation. Le répertoire de construction hébergera la documentation générée et Sphinx utilise un Makefile (make.bat sous Windows) pour construire la documentation.

Rédaction de documentation avec Sphinx

Le fichier index.rst à la racine de votre répertoire est la page d'accueil de votre application. Alors, ouvrez-le avec un éditeur de texte comme VS Code—ou tout autre bon éditeur de code gratuit- pour le modifier.

Vous pouvez modifier le fichier index.rst comme bon vous semble, mais une chose qu'il devrait au moins avoir est la directive racine toctree (arbre de la table des matières). Ceci est essentiel car il connecte plusieurs fichiers à une seule hiérarchie de documents.

Pour ajouter de la documentation au fichier index.rst, vous pouvez utiliser le balisage RST.

Prenons l'exemple d'un fichier index.rst pour le module math_utils. Ce fichier peut inclure un bref aperçu de l'objectif du module et une table des matières qui renvoie à d'autres pages de la documentation.

Bienvenue sur Math Utils
.. toctree ::
: profondeur max: 2
Commencer

Pour utiliser ce module, vous aurez besoin des éléments suivants :
* Python installé.
* Un éditeur de texte
Utilitaires mathématiques

Le module `math-utils` fournit des fonctions mathématiques de base comme l'addition et
soustraction.

Vous pouvez ajouter d'autres fichiers .rst si nécessaire. Par exemple, vous pouvez créer un guide de contribution dans un fichier nommé contribuer.rst contenant les directives de contribution suivantes.

Guide de contribution
Nous accueillons les contributions à notre projet! Voici quelques lignes directrices pour
contribuant:
- Forkez le projet sur GitHub.
- Effectuez vos modifications sur une nouvelle branche.
- Rédigez des tests pour vous assurer que vos modifications fonctionnent correctement.
- Soumettez une pull request avec vos modifications.
- Effectuez les modifications demandées.
Merci d'avoir contribué !

Vous pouvez ensuite lier ce fichier depuis index.rst en ajoutant une nouvelle section à la directive toctree :

.. toctree ::
: profondeur max: 2
 :légende: Table des matières

 contribuant

Cela crée un nouvel élément nommé contribution dans la table des matières qui amène l'utilisateur à la page de contribution lorsqu'il clique dessus.

Une fois que vous avez écrit la documentation, l'étape suivante consiste à la construire. Ici, construire la documentation signifie générer des pages HTML, manuelles ou PDF à partir des fichiers RST.

Construire la documentation

Pour construire la documentation à l'aide de Sphinx, vous devrez exécuter la commande make html à la racine de votre dossier où se trouve le makefile.

faire du HTML

Vous devriez voir les fichiers HTML dans le dossier de construction. S'il y a eu des erreurs lors de la construction, Sphinx vous le fera savoir dans le terminal.

Pour afficher la documentation, ouvrez le fichier index.html dans votre navigateur :

Vous devriez pouvoir accéder au guide de contribution à partir de la table des matières.

Personnalisation de la documentation

À l'heure actuelle, la documentation a un style de base. Si vous souhaitez le personnaliser, en ajoutant peut-être les couleurs de votre marque, ou même en ajoutant un mode sombre, vous pouvez installer et utiliser d'autres thèmes intégrés ou créez votre propre thème personnalisé.

Pour démontrer, essayez de changer le thème en celui appelé nature :

1. Ouvrez le fichier de configuration Sphinx conf.py dans le répertoire de votre projet Sphinx.
2. Recherchez la ligne qui définit l'option html_theme et changez-la en nature
3. Enregistrez le fichier de configuration et reconstruisez la documentation pour voir vos modifications.

Voici à quoi devrait ressembler la page d'accueil de la documentation.

Si vous ne souhaitez pas utiliser les thèmes intégrés, vous pouvez toujours utiliser un thème Sphinx tiers plutôt.

Documenter votre code à l'aide de Docstrings

Sphinx génère votre documentation Python à partir du texte que vous écrivez dans les fichiers RST. Bien que cela soit suffisant dans certains cas, vous pouvez également utiliser des docstrings dans votre code au niveau du module.

Les Docstrings vivent directement dans les fichiers source de votre projet. Ils vous permettent de décrire ce que fait le code, de fournir des exemples et même de créer des tests pour ces exemples. Une fois que vous avez écrit des docstrings, vous pouvez en générer une documentation à l'aide de Sphinx.