Contrôle documentaire (`docs-check`)¶

Statut¶

CURRENT pour la cible make docs-check du dépôt.

Cette page documente l’usage opérateur du contrôle documentaire local avant publication.

Commande actuelle¶

Depuis la racine du dépôt :

make docs-check

Le Makefile exécute un build MkDocs strict dans un répertoire temporaire hors de l’arbre servi :

mkdocs build --strict --clean --site-dir <tmp>

Cette séparation est importante : le contrôle ne doit pas remplacer silencieusement le site actuellement servi.

Rôle¶

make docs-check sert à valider que la documentation peut être construite proprement avant une publication ou une modification de l’arbre servi.

Il permet notamment de détecter :

échec de build MkDocs ;
erreurs ou warnings traités comme bloquants par --strict ;
références documentaires invalides détectées par MkDocs/plugins chargés ;
problèmes de configuration empêchant la génération du site.

Il ne prouve pas à lui seul que la documentation est pédagogiquement complète ou techniquement exacte.

Position dans le workflow actuel¶

modification documentaire
        ↓
make docs-check
        ↓
revue humaine / validation du lot
        ↓
make docs-build
        ↓
vérification du site servi

Le dépôt ne fournit pas, via le Makefile actuel, de cibles docs-report ou docs-deploy à considérer comme CURRENT par défaut.

Quand l’utiliser¶

Lancer make docs-check :

après création, suppression ou déplacement de pages ;
après modification de mkdocs.yml ;
après changement de navigation ;
avant toute reconstruction du site servi ;
avant de considérer un lot documentaire comme prêt à être transmis.

Lecture du résultat¶

Un contrôle réussi signifie que le build strict s’est terminé sans erreur bloquante.

Il faut néanmoins distinguer :

les erreurs réellement liées au dépôt ;
les avertissements upstream connus de l’écosystème MkDocs/Material ;
les problèmes de contenu qu’un build ne peut pas détecter.

Dans le workflow de transmission actuel, le build non strict utilisé pour validation peut afficher le warning upstream Material/MkDocs 2.0. Ce warning externe ne doit pas être reformulé comme un défaut propre à la documentation.

Ce que `docs-check` ne garantit pas¶

Même après succès, vérifier séparément :

que les pages CURRENT décrivent bien l’implémentation réelle ;
que les pages TARGET sont marquées comme telles ;
que les commandes documentées existent réellement ;
que les liens conceptuels conduisent vers la bonne couche ;
que la navigation est compréhensible pour un mainteneur sans historique du projet.

Effets¶

make docs-check est une opération de validation documentaire.

Elle ne doit pas :

modifier les données métier ;
toucher au schéma ;
lancer le Pipeline ;
modifier le Runtime WordPress ;
écraser le répertoire site/ servi par nginx-docs.

Elle peut naturellement créer puis supprimer des fichiers temporaires de build.

En cas d’échec¶

Procédure recommandée :

lire la première erreur MkDocs utile ;
identifier le fichier ou la configuration concernée ;
corriger la source ;
relancer make docs-check ;
ne reconstruire le site servi qu’après succès.

Éviter de contourner --strict uniquement pour faire passer un lot.

Vérification complémentaire¶

Le site servi possède son propre mécanisme de fraîcheur. La cible :

make docs-build

construit le site puis écrit le commit Git courant dans :

site/.ccx-docs-commit

make doctor compare ensuite cette valeur au HEAD courant pour détecter une documentation servie obsolète.

À retenir¶

make docs-check valide la capacité à construire la documentation strictement sans toucher à l’arbre servi.

Il s’agit d’un garde-fou technique, pas d’un substitut à la revue de fond.

Contrôle documentaire (docs-check)¶