wikinotes

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.
• On crée un sous repertoire dans build pour la documentation.

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.

...
extensions = [
  'sphinx_rtd_theme',
]

• https://towardsdatascience.com/documenting-python-code-with-sphinx-554e1d6c4f6d?gi=d2b08f5fbc51
• https://www.sphinx-doc.org/en/master/
• https://blog.flozz.fr/2020/09/07/introduction-a-sphinx-un-outil-de-documentation-puissant/