Démarrer avec Sphinx

Configurer votre projet et votre environnement de développement

Dans un nouveau répertoire, créer un fichier appelé README.rst avec le contenu suivant :

README.rst

Lumache
=======

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.

Le moment est venu de créer un environnement virtuel Python et d’installer les outils requis. Pour cela, ouvrez un terminal, cd dans le répertoire que vous venez de créer, et exécutez les commandes suivantes :

$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install sphinx

Note

La méthode d’installation utilisée ci-dessus est décrite plus en détails dans Installation depuis PyPI . Pour le reste de ce tutoriel, les instructions supposeront un environnement virtuel Python.

Si vous avez correctement exécuté les instructions, vous devriez disposer des outils en ligne de commande de Sphinx. Vous pouvez le vérifiez simplement en exécutant la commande :

(.venv) $ sphinx-build --version
sphinx-build 4.0.2

Si une sortie similaire est affichée, vous êtes en bonne voie !

Créer la structure de la documentation

Ensuite, depuis la ligne de commande, exécutez la commande suivante :

(.venv) $ sphinx-quickstart docs

Celle-ci vous posera une série de questions nécessaires à la création de la structure de base de répertoires et de configuration pour le projet dans le dossier docs. Pour continuer, répondez à chaque question de la manière suivante :

• > Séparer les répertoires source et de sortie (y/n) [n]: Tapez « y » (sans guillemets) et pressez Entrée.

• > Nom du projet: Saisissez « Lumache » (sans guillemets) et pressez Entrée.

• > Nom(s) de(s) l'auteur(s): Écrivez « Graziella » (sans guillemets) et pressez Entrée.

• > Version du projet []: Saisissez « 0.1 » (sans guillemets) et pressez Entrée.

• > Langue du projet [en]: Laissez vide (par défaut, Anglais) et pressez Entrée.

Passé la dernière question, vous verrez le répertoire docs avec le contenu suivant :

docs
├── build
├── make.bat
├── Makefile
└── source
   ├── conf.py
   ├── index.rst
   ├── _static
   └── _templates

L’objet de chacun de ces fichiers est :

build/

Un dossier vide (pour le moment) qui recevra la documentation générée

make.bat et Makefile

Scripts pratiques pour simplifier certaines opérations Sphinx courantes, telles que générer le contenu.

source/conf.py

Un script Python contenant la configuration du projet Sphinx. Il inclut le nom du projet et la version donnés à sphinx-quickstart, ainsi que quelques paramètres supplémentaires.

source/index.rst

Le document racine du projet, qui sert de page d’accueil et contient la racine de « l’arborescence de la table des matières » (ou toctree).

Grâce à cette étape d’initialisation, vous avez déjà tout ce qu’il faut pour générer la documentation au format HTML pour la première fois. Pour cela, exécutez cette commande :

(.venv) $ sphinx-build -M html docs/source/ docs/build/

Et finalement, ouvrez le fichier docs/build/html/index.html dans votre navigateur. Vous devriez voir affichée une page comme celle-ci :

La documentation fraîchement crée de Lumache

Nous y voilà ! Vous venez de créer votre première documentation HTML avec Sphinx. Maintenant, vous pouvez commencer à la personnaliser.