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 à partir de votre code ou de vos fichiers markdown, puis l’utiliser pour générer de la documentation dans différents formats tels que le texte brut, le HTML, le PDF et l’EPUB.
Configuration de Sphinx
Avant de configurer Sphinx, nous allons voir ce qu’il fait et quelques-unes de ses principales caractéristiques.
Qu’est-ce que Sphinx et que fait-il ?
Comme nous l’avons mentionné, Sphinx est un générateur de documentation. Par défaut, il utilise le langage de balisage reStructuredText (RST), mais grâce à des extensions tierces, il peut également utiliser Markdown, le langage de balisage de texte brut le plus répandu. Il convertit ensuite ces fichiers RST ou markdown en HTML, PDF, pages de manuel ou tout autre format que vous préférez.
Voici quelques-unes des fonctionnalités de Sphinx :
- Possibilité de générer de la documentation à partir du code.
- Possibilité d’établir des références croisées entre différentes pages du document à l’aide de liens automatiques pour les fonctions, les classes, les citations et les termes du glossaire.
- Mise en évidence de la syntaxe des blocs de code.
- Prise en charge des thèmes qui peuvent modifier l’aspect et la convivialité de la documentation.
- Définition facile de l’arborescence du document à travers une table des matières.
- Possibilité d’intégrer des extensions tierces pour ajouter plus de fonctionnalités aux documents, comme des extraits de code à tester.
Installation de Sphinx
Avant d’installer Sphinx, assurez-vous que Python 3 est installé dans votre environnement de développement. Vous pouvez ensuite utiliser le gestionnaire de paquets pip pour installer Sphinx en lançant la commande suivante dans votre terminal :
pip install 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 s’est bien passé, vous devriez voir le numéro de version du paquetage Sphinx que vous venez d’installer.
Création d’un nouveau projet Sphinx
Une fois Sphinx installé, accédez à votre répertoire de travail et exécutez la commande sphinx-quickstart pour créer un nouveau projet Sphinx.
sphinx-quickstart
Cette commande vous invite à répondre à une série de questions sur la configuration de 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 pourrez 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 quelques fichiers pour vous. Le fichier conf.py contient les valeurs de configuration et le fichier index.rst sert de page d’accueil à votre documentation. Le répertoire build hébergera la documentation générée, et Sphinx utilise un Makefile (make.bat sous Windows) pour construire la documentation.
Ecrire de la documentation avec Sphinx
Le fichier index.rst à la racine de votre répertoire est la page d’accueil de votre application. Ouvrez-le donc 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 toctree (arbre de la table des matières) de la racine. Cette directive est essentielle car elle permet de relier plusieurs fichiers à une seule hiérarchie de documents.
Pour ajouter de la documentation au fichier index.rst, vous pouvez utiliser la balise RST.
Prenons l’exemple d’un fichier index.rst pour le module math_utils. Ce fichier pourrait inclure une brève présentation de l’objectif du module et une table des matières qui renvoie à d’autres pages de la documentation.
Welcome to Math Utils
======================
.. toctree::
:maxdepth: 2
Getting Started
---------------
To use this module, you'll need the following:
* Python installed.
* A text editor
Math Utils
----------
The `math-utils` module provides basic math functions like addition and
subtraction.
Vous pouvez ajouter d’autres fichiers .rst si nécessaire. Par exemple, vous pouvez créer un guide de contribution dans un fichier nommé contributing.rst contenant les directives de contribution suivantes.
Contributing Guide
==================
We welcome contributions to our project! Here are some guidelines for
contributing:
- Fork the project on GitHub.
- Make your changes on a new branch.
- Write tests to ensure that your changes work correctly.
- Submit a pull request with your changes.
- Make any requested changes.
Thank you for contributing!
Vous pouvez ensuite lier ce fichier à index.rst en ajoutant une nouvelle section à la directive toctree :
.. toctree::
:maxdepth: 2
:caption: Table of Contents
contributing
Cela crée un nouvel élément nommé contributing dans la table des matières, qui conduit l’utilisateur à la page de contribution lorsqu’il clique dessus.
Une fois la documentation rédigée, l’étape suivante consiste à la construire. Ici, construire la documentation signifie générer des pages HTML, manuelles ou PDF à partir des fichiers RST.
Création de la documentation
Pour construire la documentation à l’aide de Sphinx, vous devez exécuter la commande make html à la racine du dossier où se trouve le fichier makefile.
make html
Vous devriez voir les fichiers HTML dans le dossier de construction. S’il y a eu des erreurs pendant la construction, Sphinx vous le fera savoir dans le terminal.
Pour voir la documentation, ouvrez le fichier index.html dans votre navigateur :
Vous devriez être en mesure de naviguer vers le guide de contribution à partir de la table des matières.
Personnalisation de la documentation
Pour l’instant, la documentation a un style basique. Si vous souhaitez la personnaliser, en ajoutant 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éer votre propre thème personnalisé.
Pour faire une démonstration, essayez de changer le thème pour celui appelé « nature » :
- Ouvrez le fichier de configuration Sphinx conf.py dans le répertoire de votre projet Sphinx.
- Cherchez la ligne qui définit l’option html_theme et changez-la en nature
- Sauvegardez le fichier de configuration et reconstruisez la documentation pour voir vos changements.
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.
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 les docstrings dans votre code pour le documenter au niveau du module.
Les docstrings se trouvent directement dans les fichiers source de votre projet. Elles 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 générer de la documentation à partir de celles-ci en utilisant Sphinx.
