sphinx

Documenter son projet avec Sphinx : session de la PyConFR 2025

Soumis par francoistonic le

Durant la conférence PyCon France 2025, Françoise Conil a présenté Sphinx. Sphinx est un des outils phares pour créer la documentation de son projet. La session s'est focalisée naturellement sur Python. L'un des avantages de Sphinx est sa souplesse : différent format de sortie, Markdown, reStructuredText, une communauté active. La 1ere version remonte à 2008.

Son installation est simple : pip install sphinx. Françoise Conil conseille de l'utiliser en environnement venv ou uv. Il faut tout d'abord configurer et générer la structure documentaire (commande quickstart) puis séparer documentation et sources (--sep). La documentation est structurée : elle contient un fichier conf.py, un fichier racine puis le make/makefile pour générer la doc. Il est possible de créer une table des matières et les liens entre les documents : toctree. Il est possible d'avoir plusieurs niveaux de profondeur. 

Naturellement, on peut intégrer à la documentation Sphinx, la documentation PyDoc. 

Voir la présentation (slides) : https://perso.liris.cnrs.fr/francoise.conil/documenter-avec-sphinx_pyconfr-2025/#/title-slide

Autre prise en main : https://blog.flozz.fr/2020/10/04/documenter-un-projet-python-avec-sphinx/

Sphinx + Markdown : créer un site web

Soumis par francoistonic le

Créer un site web avec Sphinx et Markdown ? Mike Driscoll relève le défi ! Sphinx est un puissant outil pour créer les documents techniques sur nos projets Python. ReStructuredText et Markdown. Il est possible de mixer les deux "univers".

Chaque page de la documentation ou d'un site web peut être écrit avec l'un ou l'autre ou les deux. 

1 / les dépendances

Il faut installer sphinx et myst-parser en utlisant venv pour disposer d'un environnement de développement virtuel. 

python -m venv NAME_OF_VENV_FOLDER

python -m pip install myst-parser sphinx

Puis, il faut installer sphinx via pip (pip3 si vous êtes sur Python 3). 

2 / création du site

Ensuite, nous créons un projet Sphinx qui fournira la structure du projet. On utilise sphinx-quickstart [nom du site]

Puis nous indiquons à notre projet Sphinx que nous allons utiliser markdown. C'est là que myst_parser joue son rôle. 

3 / Buildons !

Voilà notre projet, très simple, peut être buildé : sphinx-build -M html .\source\ .\build\

Les fichiers HTML sont créés automatiquement dans le dossier build/html. Bien entendu, vous pouvez étendre le contenu et les pages. 

Post source : https://www.blog.pythonlibrary.org/2025/07/01/creating-a-website-with-sphinx-and-markdown/