Déploiement documentaire¶

Statut¶

CURRENT pour make docs-build ; HISTORICAL pour le nom docs-deploy.

Le dépôt actuel ne fournit pas de cible make docs-deploy dans son Makefile.

Le mécanisme de publication vérifiable côté dépôt est la reconstruction du site servi avec :

make docs-build

Cette page conserve le vocabulaire historique docs-deploy, mais le futur mainteneur doit utiliser les commandes réellement présentes dans le dépôt.

Architecture actuelle¶

La documentation publique est construite depuis :

docs/

vers :

site/

Le service nginx-docs sert ce répertoire généré. Dans l’environnement VPS documenté, le site est exposé localement via le service de documentation et le répertoire site/ est monté dans nginx.

Le build actuel utilise MkDocs/Material configuré par mkdocs.yml.

Workflow sûr¶

Depuis la racine du dépôt :

make docs-check

Puis, après validation du lot :

make docs-build

La cible docs-build :

exécute un build MkDocs strict et propre ;
régénère le répertoire site/ ;
écrit le commit Git courant dans :

site/.ccx-docs-commit

Ce marqueur permet ensuite de vérifier que le site servi correspond bien au code courant.

Vérification post-build¶

La cible :

make doctor

contrôle notamment :

que le service documentation répond ;
que le marqueur .ccx-docs-commit servi correspond au HEAD Git courant ;
que le Runtime canonique reste correctement câblé.

Un build réussi ne suffit donc pas : il faut aussi vérifier que la version servie est fraîche.

Conditions avant reconstruction du site servi¶

Avant make docs-build :

le lot doit être relu ;
make docs-check doit passer ;
les pages CURRENT doivent avoir été vérifiées contre le dépôt lorsque nécessaire ;
les pages TARGET/HISTORICAL doivent être explicitement marquées ;
la navigation doit rester cohérente.

Dans le chantier de transmission actuel, on valide aussi avec :

./.venv-docs/bin/mkdocs build --clean

Le warning upstream Material/MkDocs 2.0 peut apparaître. Il doit être distingué des erreurs propres au dépôt.

Ce que le déploiement documentaire ne doit pas faire¶

Ne jamais utiliser la publication pour :

tester un lot encore incertain ;
masquer un build strict en échec ;
publier une page CURRENT non vérifiée ;
modifier manuellement les fichiers générés dans site/ comme source de vérité ;
contourner mkdocs.yml ou la navigation canonique.

Les fichiers dans site/ sont des artefacts générés. La source reste sous docs/ et dans la configuration MkDocs.

En cas de site servi obsolète¶

Symptôme typique :

make doctor

signale que le commit servi ne correspond pas au HEAD.

Procédure :

vérifier l’état Git ;
exécuter make docs-check ;
reconstruire avec make docs-build ;
relancer make doctor ;
ne modifier ni .ccx-docs-commit ni site/ manuellement pour faire disparaître l’alerte.

En cas de build cassé¶

Ne pas reconstruire partiellement site/ à la main.

Corriger d’abord :

le Markdown ;
mkdocs.yml ;
les liens ;
les plugins/configurations concernés.

Puis relancer le workflow complet.

Relation avec `docs-report`¶

Le dépôt ne fournit actuellement pas de commande docs-report obligatoire entre contrôle et build.

La page docs-report décrit un besoin de revue/gouvernance, pas une étape CLI CURRENT.

À retenir¶

La séquence actuelle et vérifiable est :

édition sous docs/
      ↓
make docs-check
      ↓
revue
      ↓
make docs-build
      ↓
make doctor

Le nom docs-deploy est historique ; ne créez pas une commande correspondante uniquement pour satisfaire cette ancienne documentation.