Documenter son projet avec Sphinx
PyConFR 2025 - 1 novembre 2025
Description
- créé pour la documentation du langage Python 1
- plusieurs formats de sortie : HTML, PDF via LaTeX, pages man, etc
- sources au format reStructuredText ou Markdown
- peu médiatisé mais très employé, au-delà de la communauté Python 2
La communauté est active sur Sphinx
Évolution du nombre de stars GitHub 3
Read the Docs : fonctionnement
Read the Docs recommande de s’authentifier à partir d’une plateforme d’hébergement de code (GitHub, GitLab, Bitbucket) plutôt que par email / mot de passe.
- connecter Read the Docs à un hébergeur Git facilite l’import et la configuration des dépôts
- il est possible de connecter son compte Read the Docs à plusieurs hébergeurs Git
La génération de la documentation est déclenchée par l’hébergeur Git via un webhook dont on paramétre le déclenchement :
Intégrer des extraits de code
code-block est une directive Sphinx qui permet d’insérer une portion de code avec une coloration syntaxique spécifiée par un lexer, ici « python » :
Exemple de camembert avec matplotlib :
.. code-block:: python
:caption: matplotlib ax.pie() example
:linenos:
:emphasize-lines: 7
import matplotlib.pyplot as plt
labels = 'Frogs', 'Hogs', 'Dogs', 'Logs'
sizes = [15, 30, 45, 10]
fig, ax = plt.subplots()
ax.pie(sizes, labels=labels)Rendu :
La directive code-block dispose de plusieurs options, dont :
caption: titrelinenos: numéroter les lignesemphasize-lines: mettre des lignes en surbrillance
Coloration syntaxique : Pygments
Pygments est la librairie Python qui réalise la coloration syntaxique de code.
Pygments supporte 598 langages / format.
$ pygmentize -L
Pygments version 2.19.2, (c) 2006-2024 by Georg Brandl,
Matthäus Chajdas and contributors.
* pycon, python-console:
Python console session
* pytb, py3tb:
Python Traceback (filenames *.pytb, *.py3tb)
* python, py, sage, python3, py3, bazel, starlark, pyi:
Python (filenames *.py, *.pyw, *.pyi, *.jy, *.sage,
*.sc, SConstruct, SConscript, *.bzl, BUCK, BUILD,
BUILD.bazel, WORKSPACE, *.tac)On peut créer un lexer si besoin.
Le style d’affichage de la section de code change selon les thèmes.
Utilisation du lexer python-console :
.. code-block:: pycon
>>> import pygments.styles
>>> styles = list(pygments.styles.get_all_styles())
>>> styles
['abap', 'algol', 'algol_nu', 'arduino', 'autumn', …]Rendu avec le thème bizstyle :
Rendu avec le thème Read the Docs :
nbsphinx, nbsphinx-link
nbsphinx est un parseur de fichiers .ipynb qui permet l’intégration de notebooks Jupyter 1.
nbsphinx-link permet d’inclure des notebooks qui ne sont pas dans le dossier des « sources ».
Installation des extensions Sphinx :
$ pip install nbsphinx nbsphinx-linkDéclaration dans conf.py :
extensions = ['nbsphinx', 'nbsphinx_link']Insérer le chemin des notebooks sans l’extension .ipynb :
Warning
Les fichiers .ipynb qui ne contiennent pas la sortie des cellules sont automatiquement exécutés lors de la compilation Sphinx (désactivable).
Mermaid
Mermaid permet de générer des diagrammes et des graphiques à partir de descriptions textuelles.
Installation de l’extension Sphinx :
$ pip install sphinxcontrib-mermaidInstructions dans conf.py :
extensions = ['sphinxcontrib.mermaid']
mermaid_init_js = """mermaid.initialize({
startOnLoad: true,
sequence: {showSequenceNumbers: true}
});"""Exemple de diagramme de séquence
.. mermaid::
sequenceDiagram
autonumber
Bob->>Alice: Authentication Request
Alice->>Bob: Authentication Response
Bob->>Alice: dummy
Bob->>Alice: Yet another authentication Request
Alice->>Bob: Yet another authentication Response
Bob->>Alice: dummy
PlantUML
PlantUML est un autre outil de génération de diagrammes à partir de descriptions textuelles. Il nécessite Java, Graphviz et le jar PlantUML 1.
Installation de l’extension Sphinx :
$ pip install sphinxcontrib-plantumlInstructions dans conf.py :
extensions = ['sphinxcontrib.plantuml']
local_plantuml_path = os.path.join(os.path.dirname(__file__),
"utils", "plantuml-lgpl-1.2025.9.jar")
plantuml = f"java -Djava.awt.headless=true -jar {local_plantuml_path}"Exemple de diagramme de séquence
.. uml::
!theme aws-orange
autonumber 10 10 "<b>[000]"
Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response
Bob -> Alice : dummy
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response
Bob -> Alice : dummy
Sphinx-Gallery
Sphinx-Gallery permet de créer des “galeries HTML” à partir de code Python.
Exemple NetworkX
Note
Extension utilisée par matplotlib, NetworkX, scikit-learn, …
Voir le Getting started et son projet exemple.
Thèmes intégrés
Sphinx utilise le thème alabaster par défaut et intègre 9 autres thèmes 1 2.
Il suffit de déclarer le thème à utiliser avec la variable html_theme dans le fichier de configuration conf.py.
# Fichier conf.py
html_theme = 'alabaster'
# Fichier conf.py
html_theme = 'bizstyle'
Thèmes Read the Docs et Furo
Des thèmes complémentaires sont présentés sur le site sphinx-themes.org. Pour utiliser un de ces thèmes, il faut installer le package du thème au préalable.
Installation du thème Read the Docs par pip
$ pip install sphinx-rtd-themeDéclaration du thème dans conf.py
html_theme = 'sphinx_rtd_theme'
Installation du thème Furo par pip
$ pip install furoDéclaration du thème dans conf.py
html_theme = 'furo'
Extension Sphinx Design
sphinx{design} apporte plusieurs composants d’interface utilisateur qui améliorent le rendu visuel : grids, cards, dropdowns, tabs, badges and button-links et icons.
Thème PyData
Le thème PyData, basé sur Bootstrap, permet une présentation plus riche 1.
- lire la page Theme Structure and Layout pour comprendre la structure de l’interface
- lire la page Utilisation des composants sphinx{design}
- voir Gallerie de projets utilisant ce thème : matplotlib, astropy, Sepal, …
Installation du thème PyData par pip
$ pip install pydata-sphinx-themeDéclaration du thème dans conf.py
html_theme = 'pydata_sphinx_theme'
Sphinx : un outil riche pour la documentation technique
- Installez Sphinx dans un environnement virtuel
- Générez la structure du projet avec
sphinx-quickstart - Ajoutez du contenu
- Intégrez la documentation du code
- Adoptez le thème de votre choix
- Enrichissez votre documentation à l’aide des nombreuses extensions
- Si vous voulez utiliser du Markdown, passez à MyST
Et si vous voulez maîtriser Sphinx et reStructuredText, n’hésitez pas à contribuer à la traduction de la documentation python
Diátaxis
Read the Docs recommande la méthodologie Diátaxis pour architecturer la documentation.
Versions de documentation
Un projet peut avoir plusieurs versions de documentations sur Read the Docs 1.
$ git tag -a 0.1.0 -m "First step reached - PlantUML activated on Read the Docs"
$ git push origin --tags
Énumération des objets: 1, fait.
Décompte des objets: 100% (1/1), fait.
Écriture des objets: 100% (1/1), 206 octets | 206.00 Kio/s, fait.
Total 1 (delta 0), réutilisés 0 (delta 0), réutilisés du pack 0
To github.com:fconil/Sphinx-with-PlantUML-on-RTD.git
* [new tag] 0.1.0 -> 0.1.0