Plus de frameworks - Notre lab

Sphinx¶

Sphinx est un générateur de documentation open source, principalement utilisé pour créer des documentations techniques, en particulier pour les projets Python. Il transforme des fichiers texte (souvent en reStructuredText ou Markdown) en sites web statiques, PDF, ePub, etc.

Voici un mode opératoire standardisé pour installer et utiliser Sphinx dans un environnement de développement Python.

🛠️ Installation et configuration¶

1. Prérequis¶

Python 3.6+ doit être installé.
pip (le gestionnaire de paquets Python) doit être disponible.

Vérification :

python --version
pip --version

2. Création d’un environnement virtuel (recommandé)¶

python -m venv env
source env/bin/activate  # Sous Windows : env\Scripts\activate

3. Installation de Sphinx¶

pip install sphinx

4. Initialisation d’un projet Sphinx¶

Dans le répertoire souhaité :

sphinx-quickstart

Répondre aux questions interactives pour générer la structure du projet. Cela crée notamment :

conf.py : fichier de configuration
index.rst : page d’accueil de la documentation
Makefile ou make.bat : pour la génération

5. (Optionnel) Installation d’un thème¶

Exemple avec le thème Read the Docs :

pip install sphinx-rtd-theme

Modifier conf.py :

html_theme = "sphinx_rtd_theme"

6. Génération de la documentation HTML¶

make html

(Sous Windows : .\make.bat html)

Le site est généré dans le dossier _build/html/.

7. (Optionnel) Affichage en temps réel avec rechargement automatique¶

Installation :

pip install sphinx-autobuild

Lancement du serveur local :

sphinx-autobuild source/ _build/html

La documentation est alors accessible via http://127.0.0.1:8000 avec rechargement automatique à chaque modification.