Accueil / Sphinx

Sphinx

Le générateur de documentation Python le plus utilisé. Il prend tes docstrings et tes fichiers texte, et produit un site web HTML navigable, professionnel, prêt à publier.

Documentation

À quoi ça sert

Tu as bien documenté tes fonctions avec des docstrings. C'est super, mais ça reste invisible : seul quelqu'un qui lit ton code y a accès.

Sphinx résout ça en générant un site web HTML à partir de :

  • Tes docstrings (via l'extension autodoc).
  • Des fichiers reStructuredText (.rst) ou Markdown que tu écris pour les guides, tutoriels, README, etc.

Le résultat : un site avec recherche intégrée, navigation latérale, références croisées cliquables, hébergeable gratuitement (GitHub Pages, Read the Docs…). C'est la doc de Python, NumPy, Django, Pandas, FastAPI… Tu en as déjà vu des dizaines sans le savoir.

En une phrase

Sphinx transforme ton code documenté + quelques fichiers texte en un site web de doc complet et joli.

Un exemple d'usage

Tu as un module calculs.py avec des docstrings au format Google :

python 
def moyenne(valeurs: list[float]) -> float:
    """Calcule la moyenne arithmétique d'une liste de nombres.

    Args:
        valeurs: Liste de nombres dont on veut la moyenne.

    Returns:
        La moyenne arithmétique.

    Raises:
        ZeroDivisionError: Si la liste est vide.
    """
    return sum(valeurs) / len(valeurs)

Tu lances sphinx-build, et Sphinx génère une page HTML qui affiche le nom de la fonction, sa signature, les paramètres typés, le retour, les exceptions — chacun avec son explication, le tout indexé et cherchable.

How-to : générer ta première doc

  1. Installer Sphinx

    Avec UV (voir la fiche UV) :

    bash 
    uv add --dev sphinx furo myst-parser

    Trois paquets utiles d'un coup :

    • sphinx — le générateur lui-même.
    • furo — un thème HTML moderne et joli (alternative au défaut un peu daté).
    • myst-parser — pour écrire en Markdown plutôt qu'en reStructuredText.

  2. Initialiser le projet de doc

    Sphinx fournit un assistant qui crée la structure pour toi. Lance-le dans un sous-dossier docs :

    bash 
    mkdir docs && cd docs
uv run sphinx-quickstart

    L'assistant te pose quelques questions :

    • Separate source and build directories? → n (plus simple).
    • Project name → le nom de ton projet.
    • Author name → toi.
    • Project language → fr (ou en).

    Tu obtiens une arbo du type :

    arbo 
    docs/
├── conf.py          # config de Sphinx
├── index.rst        # page d'accueil
├── Makefile         # raccourcis (Linux/macOS)
└── make.bat         # raccourcis (Windows)

  3. Configurer Sphinx

    Édite docs/conf.py pour activer les extensions importantes :

    python 
    import os
import sys

# Permet à autodoc de trouver ton code
sys.path.insert(0, os.path.abspath("../src"))

project = "Mon projet"
author = "Toi"
language = "fr"

extensions = [
    "sphinx.ext.autodoc",        # lit les docstrings
    "sphinx.ext.napoleon",       # comprend les styles Google / NumPy
    "sphinx.ext.viewcode",       # lien vers le code source
    "sphinx.ext.intersphinx",    # liens vers d'autres docs Sphinx
    "myst_parser",                # support du Markdown
]

html_theme = "furo"           # thème moderne
html_static_path = ["_static"]

# Liens vers la doc Python officielle
intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
}
    Napoleon = Google / NumPy style

    Sans sphinx.ext.napoleon, Sphinx attend les docstrings au format reStructuredText. Avec, il accepte aussi les styles Google et NumPy — beaucoup plus lisibles.

  4. Inclure tes modules dans la doc

    Édite docs/index.rst pour ajouter une section API :

    rst 
    Bienvenue !
===========

Ceci est la documentation de mon projet.

.. toctree::
   :maxdepth: 2
   :caption: Sommaire

   api

Index et recherche
==================

* :ref:`genindex`
* :ref:`search`

    Crée docs/api.rst :

    rst 
    Référence de l'API
==================

.. automodule:: calculs
   :members:
   :undoc-members:
   :show-inheritance:

    automodule dit à Sphinx : « va lire le module calculs et génère une page à partir de toutes ses docstrings ». Magique.

  5. Générer le site HTML

    Depuis le dossier docs/ :

    bash 
    uv run sphinx-build -b html . _build/html

# ou avec le Makefile fourni
make html

    Ouvre docs/_build/html/index.html dans ton navigateur. Tu vois ta doc, avec ta page d'accueil et la référence API extraite des docstrings.

  6. Itérer en live (sphinx-autobuild)

    Pour une boucle de feedback rapide, installe sphinx-autobuild :

    bash 
    uv add --dev sphinx-autobuild
uv run sphinx-autobuild docs docs/_build/html

    Ça lance un serveur sur http://localhost:8000 et recharge la page automatiquement à chaque modification. Idéal quand tu rédiges.

  7. Configurer VS Code

    1. Installe l'extension reStructuredText (lextudio.restructuredtext) — coloration, prévisualisation et lint des fichiers .rst.
    2. Si tu écris ta doc en Markdown via myst-parser, l'extension Markdown All in One est très utile.
    3. Dans .vscode/settings.json, indique l'interpréteur du venv pour que les liens vers le code Python depuis la doc fonctionnent en Ctrl+clic.

  8. Publier la doc en ligne (gratuit)

    Deux options classiques :

    • Read the Docs — tu connectes ton dépôt GitHub, RTD construit la doc à chaque push et l'héberge sur tonprojet.readthedocs.io.
    • GitHub Pages — un workflow GitHub Actions builde la doc et la pousse sur la branche gh-pages.

    Workflow GitHub Actions minimal pour Pages :

    yaml 
    name: Docs
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install sphinx furo myst-parser
      - run: sphinx-build docs docs/_build/html
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html

Aide-mémoire

bash 
# Initialiser un projet de doc
sphinx-quickstart

# Builder le site HTML
sphinx-build -b html docs docs/_build/html
make html                    # si Makefile présent

# Mode live
sphinx-autobuild docs docs/_build/html

# Nettoyer
make clean

Directives Sphinx utiles

rst 
.. automodule:: mon_module      # tout un module
   :members:

.. autoclass:: MaClasse         # une classe
   :members:

.. autofunction:: ma_fonction   # une fonction

.. note::                       # encadré "note"
   Texte de la note.

.. warning::                    # encadré d'avertissement
   Attention !

.. code-block:: python          # bloc de code colorisé

   print("hello")

Pour aller plus loin