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 langage de balisage en texte brut populaire. 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 que Python 3 est 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 :
Cela téléchargera et installera Sphinx et ses dépendances.
Après l’installation, exécutez ce qui suit à l’invite de commande.
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.
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.
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.
Vous pouvez ensuite lier ce fichier depuis index.rst en ajoutant une nouvelle section à la directive toctree :
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.
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 :
- Ouvrez le fichier de configuration Sphinx conf.py dans le répertoire de votre projet Sphinx.
- Recherchez la ligne qui définit l’option html_theme et changez-la en nature
- 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.
Abonnez-vous à notre newsletter
Comment documenter le code Python pour Sphinx ?
Vous trouverez ci-dessous un guide étape par étape pour générer facilement une documentation propre et bien organisée à partir de code Python à l’aide de Sphinx.
- Installez Sphinx.
- Initialisez la configuration Sphinx.
- Mettez à jour le fichier conf.py.
- Générez automatiquement les premiers fichiers.
- Construisez le HTML.
- Balisage Sphinx avancé.
Comment configurer le projet Sphinx pour Python ?
Configurer l’environnement virtuel
- Créez d’abord un environnement virtuel Python 3 à l’aide du module venv inclus avec Python 3. python -m venv py3-sphinx.
- Maintenant, « activez » l’environnement. Recherchez le nom de l’environnement virtuel entre parenthèses après l’activation.
- Vérifiez maintenant que python est maintenant lié à Python 3.
Comment créer une documentation Sphinx dans Pycharm ?
Pour générer la documentation Sphinx Appuyez sur Alt+Maj+F10 puis appuyez sur 0 .
Comment créez-vous un code Python pour la documentation ?
Tout ce que vous avez à faire est de mettre votre documentation dans une docstring, puis pycco la générera et vous offrira également une prise en charge complète du démarquage. Alors imaginez si à la base de votre répertoire de projet vous avez un dossier appelé project_docs qui contient : install_docs.py.
