6 Compiler la documentation

Installation de Sphinx (debian 11)

Installer le paquet d'environnement virtuel python, ainsi que pip (ce qui installera aussi python si nécessaire)

sudo apt update
sudo apt install python3-venv python3-pip make

Nous supposons pour la suite que le projet de documentation est structuré ainsi :

projet-de-documentation
├─ build
├─ outils
├─ source
├─ make.bat
└─ Makefile

Créer une environnement virtuel python. Cela permet d'installer des modules python qui ne seront utilisés que par ce projet (et donc d'avoir d'autres modules, ou d'autres versions des mêmes modules, dans d'autres projets).

cd projet-de-documentation
python3 -m venv outils

Activer l'environnement python (à refaire chaque fois que vous relancez un terminal pour exécuter des commandes python sur ce projet)

cd projet-de-documentation
source outils/bin/activate

Installer Sphinx

pip install -U pip setuptools wheel
pip install Sphinx myst-parser sphinx_rtd_theme linkify-it-py sphinx-multiversion

Prise en charge du format PDF

Pour pouvoir compiler la documentation dans un fichier PDF, le système nécessite un passage par weasyprint et Latex (pour la génération du sommaire). Il faut installer des paquets supplémentaires :

sudo apt install fonts-freefont-otf latexmk texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra texlive-lang-french tex-gyre texlive-xetex pdftk libipc-run3-perl liblatex-encode-perl

Pour pouvoir intégrer des images au format SVG dans le PDF, il faut également ajouter un module python

cd projet-de-documentation
source outils/bin/activate
pip install sphinxcontrib-svg2pdfconverter weasyprint sphinx_weasyprint_builder

Et finalement, ajouter une extension dans source/conf.py qui indique également l'outil à utiliser pour convertir les SVG. Par exemple en utilisant inkscape :

extensions = [
    'sphinxcontrib.inkscapeconverter',
]

Générer la documentation au format HTML

Une seule version

cd projet-de-documentation
source outils/bin/activate
make html

Multiversion

L'extension sphinx-multiversion permet de générer un ensemble de pages HTML contenant plusieurs versions. Il est alors possible de choisir la version dans une liste déroulante.

Principe de fonctionnement

Le principe est que cette extension liste les branches et tags dans le dépôt git local (elle ne consulte pas les informations sur le remote git). Il est possible de configurer quels tags et branches sont retenues comme versions via des expressions régulières. Par exemple la branche "main" et tous les tags commençant par "v" suivi de chiffres.

Il est important de noter que les fichiers source de chaque version sont utilisés, en revanche seule la configuration de la branche actuelle est utilisée pour compiler toutes les versions (y compris les fichiers CSS et templates par exemple). Il faut donc conserver une rétro-compatibilité du thème et de la configuration avec les ancienes sources. Cela permet en retour que les modifications du thème soit répercutées sur toutes les versions, afin d'avoir une documentation homogène.

Compiler la documentation multiversion

cd projet-de-documentation
source outils/bin/activate
make html_versions

Configuration

Au delà de la configuration du système de base, quelques modifications ont été ajoutées :

l'extension rtd_current_version améliore la compatibilité de sphinx-multiversion avec le thème ReadTheDocs
l'extension version_data permet de définir des variables python différentes dans chaque version, qui seront accessibles dans les templates. Ces variables peuvent être définies dans le fichier current_version_data.py

Générer la documentation au format PDF

cd projet-de-documentation
source outils/bin/activate
make pdf