|
All checks were successful
Documentation / publish (push) Successful in 1m47s
Le menu de version pointait sur /main/ à la racine du domaine : DOCS_BASE_PATH était vide alors que les pages sont servies sous /two/. Le thème colle l'URL d'une version devant le chemin de la page sans la résoudre, un chemin relatif y casserait donc selon la profondeur de la page. Les URL de switcher.json sont désormais relatives à switcher.json lui-même, et version-switcher.js les résout depuis cet emplacement une fois le menu rempli. Le site fonctionne ainsi sous n'importe quel sous-chemin, sans réglage. Le script est injecté par le workflow dans chaque version construite (sphinx-build -D) : une version figée comme 0.2.0, construite depuis le conf.py de son tag, le reçoit sans retoucher le tag. Vérifié en local avec les étapes du workflow : site servi sous /two/ et à la racine, liens du menu corrects sur une page de premier niveau et de sous-répertoire. Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr> |
||
|---|---|---|
| .. | ||
| _static | ||
| architecture | ||
| concepts | ||
| demarrage | ||
| deploiement | ||
| developpement | ||
| exploitation | ||
| schemas | ||
| versions | ||
| conf.py | ||
| index.rst | ||
| README.md | ||
| requirements.txt | ||
Documentation two
Construction locale, avec rechargement automatique :
TMPDIR=$(mktemp -d)
python3 -m venv "${TMPDIR}/venv"
source "${TMPDIR}/venv/bin/activate"
pip install --upgrade pip
pip install -r requirements.txt
sphinx-autobuild . "${TMPDIR}/build"
Construction simple, avec les mêmes options que la CI (avertissements bloquants) :
sphinx-build -b html -W --keep-going . _build/html
La référence de l'API est générée depuis ../api/agent.yaml : c'est la source unique du
contrat, la documentation ne la recopie pas.
Schémas
Les schémas simples sont en mermaid, directement dans les pages. Les schémas travaillés sont des
SVG dans schemas/, en deux variantes :
schemas/<nom>.svg thème clair → .. figure:: /schemas/<nom>.svg :class: only-light
schemas/<nom>-dark.svg thème sombre → .. figure:: /schemas/<nom>-dark.svg :class: only-dark
schemas/ est dans exclude_patterns : Sphinx n'y cherche pas de pages, mais copie les fichiers
référencés par une directive figure ou image.
Les schémas d'architecture (architecture-ensemble et architecture-cluster) sont générés : ne
pas éditer leurs SVG, modifier schemas/gen_ensemble.py ou schemas/gen_cluster.py (même style,
le second réutilise les fonctions du premier), puis régénérer les deux variantes :
python3 -B schemas/gen_ensemble.py schemas
python3 -B schemas/gen_cluster.py schemas
Un export draw.io se dépose tel quel sous ce nom. Exporter en SVG éditable (« Include a copy of my diagram ») pour pouvoir rouvrir le fichier dans draw.io ensuite.