Sphinx utilise Python et make pour construire la documentation:
sudo apt install build-essential python3 python3-pip python3-venv
Créer et activer l'environnement virtuel du projet et on installe les modules via pip3. Ici en plus du module sphinx on installe le thème read the docs
cd my_app source app_env/bin/activate pip3 install sphinx sphinx_rtd_theme
Le script sphinx-quickstart assiste l'utilisateur pour la création de l'arborescence de base de la documentation et son intégration au sein du projet.
Se placer à la racine du projet et lancer la commande sphinx-quickstart
sphinx-quickstart
Ici on fait le choix de séparer les répertoires source et build de la documentation.
Pour plus de clarté, on fait le choix de renommer les répertoires :
source → doc : Pour sphinx source contient les fichiers sources de la documentation mais dans un projet de code, cela peut porter à confusion.Il faudra ensuite modifier le fichier Makefile:
mv source doc mkdir build/doc
# Minimal makefile for Sphinx documentation # # You can set these variables from the command line, and also # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build SOURCEDIR = doc BUILDDIR = build/doc
Tester une compilation
make html
Le thème “Read The Doc” a été téléchargé mais il n'est pas encore utilisé. Modifier le fichier de configuration doc/conf.py :
... # Utilise le thème Read the Doc html_theme = 'sphinx_rtd_theme'
Les nombreuses options de configuration du thème son décrite dans la documentation officielle du thème.
sphinx_rtd_theme pour permettre la traduction des éléments de l'interface. Modifier le fichier conf.py
... extensions = [ 'sphinx_rtd_theme', ]