Cette page décrit comment utiliser sphinx-web pour publier une nouvelle version de la documentation.
sphinx-web est un serveur web qui utilise sphinx pour gérer et compiler divers documents, y compris des pages HTML permettant de choisir une version de documentation à afficher, et télécharger un PDF pour chaque version. Ce sont ces pages web qui sont publiées sur https://documentation.vhelio.org/
Le système multiversion utilise la configuration de la branche prod pour compiler toutes les versions. Par conséquent, modifier le fichier conf.py dans la branche d'une version de la documentation n'aura pas d'effet sur ce qui est compilé par le serveur. Au besoin, il faudra intégrer les changements dans le fichier conf.py de la branche prod, et s'assurer que tout est rétro-compatible pour compiler les anciennes versions. Chaque version peut toutefois définir des variables dans le fichier source/current_version_data.py.
Checklist pour publier une nouvelle version
- dans la branche
main, vérifier que l'avertissement en haut deindex.mdpointe bien vers la dernière version (donc la nouvelle version) - modifier le numéro de la dernière version dans le fichier
config.pyde la brancheprod - compiler et uploader le PDF de la dernière version sur le forum, et reporter son URL dans le fichier
source/current_version_data.pydans la branche de la nouvelle version - créer un tag git qui pointe sur le commit à utiliser pour la nouvelle version, nommé d'après le numéro de version, par exemple
v6.3.12 - si la compilation ne se déclenche pas automatiquement, utiliser l'interface admin de sphinx-web pour lancer la compilation de la branche
prod - vérifier que la doc est bien à jour sur le serveur public