From 28cb25335d836eb859933828e15a72fbdc6db482 Mon Sep 17 00:00:00 2001
From: youen <youen@noreply.localhost>
Date: Thu, 1 Jun 2023 19:55:59 +0000
Subject: [PATCH] =?UTF-8?q?Ajout=20d'infos=20sur=20le=20syst=C3=A8me=20de?=
 =?UTF-8?q?=20documentation=20multiversion?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Compiler-la-documentation.md | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/Compiler-la-documentation.md b/Compiler-la-documentation.md
index ed1048d..8526f17 100644
--- a/Compiler-la-documentation.md
+++ b/Compiler-la-documentation.md
@@ -36,7 +36,7 @@ Installer [Sphinx](https://www.sphinx-doc.org/en/master/index.html)
 
 ``` shell
 pip install -U pip setuptools wheel
-pip install Sphinx myst-parser sphinx_rtd_theme linkify-it-py
+pip install Sphinx myst-parser sphinx_rtd_theme linkify-it-py sphinx-multiversion
 ```
 
 ## Prise en charge du format PDF
@@ -64,6 +64,7 @@ extensions = [
 ```
 
 # Générer la documentation au format HTML
+## Une seule version
 
 ``` shell
 cd projet-de-documentation
@@ -71,6 +72,26 @@ source outils/bin/activate
 make html
 ```
 
+## Multiversion
+L'extension [sphinx-multiversion](https://holzhaus.github.io/sphinx-multiversion/master/index.html) 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
+``` shell
+cd projet-de-documentation
+source outils/bin/activate
+make html_versions
+```
+
+### Configuration
+Au delà de la [configuration du système de base](https://holzhaus.github.io/sphinx-multiversion/master/configuration.html), 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
 
 ``` shell