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 le répertoire source de la documentation en doc. Il faudra ensuite modifier le 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

• 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/