Pipeline de génération de la documentation
La documentation ZeroClaw combine du Markdown rédigé à la main avec des références et des extraits générés à partir de types Rust, de définitions de commandes, de registres, de contrats WIT, de fichiers de workflow et de métadonnées d’interface. Le fichier généré n’est pas une seconde source de vérité : corrigez la source d’origine ou le générateur, puis reconstruisez la documentation.
Utilisez cette page lorsqu’une modification touche un schéma, un flag CLI, une fonctionnalité ou un inventaire matériel, un contrat de plugin, un mappage de touches par défaut, un registre de thèmes, une directive mdBook, une référence générée, une porte de documentation, ou un workflow de déploiement. Pour les valeurs de configuration spécifiquement, lisez également Config lifecycle. Pour les sorties traduites, poursuivez avec Localization catalog lifecycle.
Correspondance source-sortie
| Surface | Source canonique | Materializer | Sortie | État du dépôt | Consommateur |
|---|---|---|---|---|---|
| Référence de configuration | zeroclaw_config::schema::Config plus les dérivations Configurable | cargo mdbook refs ou cargo mdbook build, via markdown-schema | docs/book/src/reference/config.md | Fichier dérivé ignoré | Chapitre de référence de configuration et directives basées sur un schéma |
| Référence de la CLI | Arborescence des commandes Clap dans src/main.rs | cargo mdbook refs ou cargo mdbook build, via markdown-help | docs/book/src/reference/cli.md | Fichier dérivé ignoré | Référence de l’interface en ligne de commande |
| Chemins d’installation | Contrats de routes typés dans xtask/src/generate/spec.rs et corps de comportement générés dans les moteurs de rendu des installateurs | cargo generate installers, via xtask/src/generate/docs.rs et xtask/src/generate/install_sh.rs | docs/book/src/_snippets/install.md, les blocs de commandes Unix générés dans le README et les guides de plateforme, les sections générées de routage et d’aide à la sélection dans install.sh, ainsi que le bloc Windows précompilé dans docs/book/src/setup/windows.md | Surfaces générées suivies | Configuration initiale liée au README, routes Unix exécutables, guide de démarrage rapide et pages de configuration des plateformes |
| Référence de la syntaxe SOP | catalogue de la syntaxe de parse_steps dans crates/zeroclaw-runtime/src/sop/mod.rs et ConditionOp::catalog() | cargo generate sop-syntax, via xtask/src/generate/sop_syntax.rs | Régions marquées relatives au comportement de l’analyseur et aux opérateurs conditionnels dans docs/book/src/sop/syntax.md | Régions générées suivies | Référence de rédaction des SOP |
| Référence de l’API Rust | Éléments Rust publics dans les crates de l’espace de travail | cargo doc dans cargo mdbook refs ou cargo mdbook build | target/doc/, copié dans docs/book/book/api/ | Sortie de compilation ignorée | Référence de l’API publiée |
| Matrice de fonctionnalités | Inventaire des canaux, emplacements modèle-fournisseur, outils par défaut, et docs/book/feature-matrix-parity.toml | xtask/src/cmd/mdbook/feature_matrix.rs lors des compilations de locale | docs/book/src/_snippets/feature-matrix-*.md | Extraits dérivés ignorés | Pages de comparaison des fonctionnalités via {{#include}} |
| Tableaux matériels | Registre des cartes matérielles et catalogue d’outils, descriptions des transports dans le générateur, cibles du workflow de publication et seuil de mémoire faible dans install.sh | xtask/src/cmd/mdbook/hardware.rs lors des constructions de locale | docs/book/src/_snippets/hardware-*.md | Extraits dérivés ignorés | Guides sur le matériel et les cibles de publication |
| Valeurs du contrat de plugin | Contrats WIT, guides des plugins et limites de src/plugin_registry.rs | xtask/src/cmd/mdbook/plugins.rs lors des compilations de la locale | docs/book/src/_snippets/plugin-*.md | Extraits dérivés ignorés | Guides de création de plugins |
| zerocode tables de clés | Mappage de touches par défaut dans apps/zerocode/src/keymap/actions.rs | xtask/src/cmd/mdbook/keymap.rs lors des compilations de locale | docs/book/src/_snippets/zerocode-*-keys.md | Extraits dérivés ignorés | zerocode pages de raccourcis clavier |
| Blocs de groupe de pairs | docs/book/peer-groups.toml | xtask/src/cmd/mdbook/peer_groups.rs préprocesseur mdBook | Contenu du chapitre développé | Uniquement au moment de la compilation | Pages de canaux et de groupes de pairs utilisant des directives de groupes de pairs |
| CSS et noms de thème | web/src/contexts/themes.json | xtask/src/cmd/mdbook/themes.rs lors des builds de locale | Fragments CSS/de noms ignorés et zone de marqueur générée dans le fichier suivi docs/book/theme/index.hbs | Mixte : les fichiers dérivés sont ignorés ; le modèle situé en dehors de son marqueur reste rédigé manuellement | Sélecteur de thème mdBook et référence du thème zerocode |
| Sélecteur de langue | locales.toml et docs/book/theme/lang-switcher.js.tpl suivi | inject_lang_switcher_locales pendant les compilations de locale | docs/book/theme/lang-switcher.js | Fichier dérivé ignoré | Sélecteur de langue publié |
| Chapitres rédigés | docs/book/src/**/*.md et les extraits suivis | Préprocesseurs et moteurs de rendu mdBook | HTML de paramètres régionaux/version sous docs/book/book/ | Source suivi, sortie ignorée | Site de documentation publié |
| Types d’API Dashboard | zeroclaw_gateway::openapi::build_spec() et les types d’exécution du gateway | cargo web gen-api | target/openapi.json, web/src/lib/api-generated.ts, web/src/lib/api-descriptions.ts, et web/src/lib/api-enums.ts | Fichiers dérivés ignorés | Compilation du tableau de bord TypeScript |
Cette matrice décrit les surfaces à forte valeur actuelles, et non chaque fichier auxiliaire produit lors d’une compilation. La règle réutilisable est la propriété : une valeur générée doit avoir une seule entrée canonique et un seul chemin de matérialisation déterministe.
Ordre d’assemblage de mdBook
cargo mdbook est la surface de commandes xtask définie dans .cargo/config.toml. Ses principales commandes composent le pipeline plutôt que d’invoquer directement un simple mdbook build.
cargo mdbook refs génère le Markdown de la CLI et de la configuration à partir du code en direct, compile la rustdoc du workspace et copie la sortie de l’API dans l’arborescence de compilation de la documentation. cargo mdbook build exécute la séquence complète adaptée à la publication :
- Générer
reference/cli.mdetreference/config.mdà partir de l’arborescence de commandes actuelle et du schéma de configuration. - Générer la documentation rustdoc de l’espace de travail.
- Matérialiser les extraits de thème, keymap, matériel, matrice de fonctionnalités et plugin.
- Exécute mdBook une fois pour chaque langue dans
locales.toml, avec les préprocesseurs configurés pardocs/book/book.toml. - Vérifier les liens dans la locale principale rendue.
- Assemblez le répertoire de version, la redirection de langue, l’arborescence rustdoc et les ressources de thème partagées sous
docs/book/book/.
Le préprocesseur peer-group développe ses directives pendant que mdBook traite chaque chapitre. Les autres préprocesseurs mdBook standard gèrent les liens, les blocs Mermaid et la localisation gettext. Les références générées doivent donc exister avant le prétraitement des chapitres, tandis que le développement des directives et la traduction ont lieu lors de la construction des paramètres régionaux.
Le workflow de déploiement de la documentation initialise le sous-module de traduction, installe les outils mdBook requis, exécute cargo mdbook build, et fusionne la version assemblée dans la branche gh-pages. Il n’appelle pas de fournisseur de traduction ni ne répare les catalogues lors du déploiement.
Sorties suivies et de compilation uniquement
Les fichiers suivis sont des entrées ou des modèles révisables : Markdown rédigé, locales.toml, docs/book/peer-groups.toml, métadonnées de parité de la matrice de fonctionnalités, modèles de thème, sources Rust/WIT et définitions de workflow. Le chemin docs/book/po est un gitlink suivi vers le dépôt distinct du catalogue de traductions ; son contenu et ses tags de version ont leur propre cycle de vie.
Les fichiers ignorés sont des matérialisations reproductibles : les références de CLI et de configuration, la plupart des extraits générés, rustdoc, le HTML généré, le JavaScript du sélecteur de langue, le CSS de thème généré et le client API TypeScript du tableau de bord. Ils peuvent exister dans une arborescence de travail après une génération de la documentation sans avoir à figurer dans un commit. Les éléments d’installation suivis sont des exceptions explicites : docs/book/src/_snippets/install.md, les blocs de commandes Unix générés dans le README et les guides de plateforme, les régions générées des routes et des assistants de sélection dans install.sh, et le bloc précompilé pour Windows dans docs/book/src/setup/windows.md.
docs/book/theme/index.hbs est le cas mixte notable. Il s’agit d’un modèle suivi, mais le générateur de thème réécrit uniquement la région de liste de thèmes balisée à partir de themes.json. Si une commande de génération standard modifie cette région, vérifiez si le registre canonique ou le générateur a changé ; ne traitez pas la liste générée comme un contenu créé de manière indépendante.
Gardes de dérive et de validation
Différents contrôles couvrent différentes classes d’échecs :
| Vérifier | Ce que cela prouve | Ce qu’il ne prouve pas |
|---|---|---|
| Contrôle qualité de la documentation | La modification du Markdown respecte la politique des tirets cadratins dans le texte et markdownlint | Les références ou extraits ignorés ont été régénérés à partir du code actuel |
| Passerelle de lien ajouté | Les nouveaux liens Markdown locaux dans le diff comparé sont résolus | Les liens existants, les liens générés en dehors du diff ou la navigation rendue fonctionnent tous |
cargo mdbook check | Les catalogues PO analysent et réussissent les audits de réponse générée, de littéral protégé et de chemin local | Les références CLI/config et les extraits ignorés correspondent aux sources Rust actuelles |
cargo mdbook refs | La référence CLI/config en Markdown et la rustdoc peuvent être générées à partir du code actuel | Chaque langue et thème s’assemblent pour former un site complet |
cargo mdbook build | Références complètes, extraits, builds de locales, liens rendus et assemblage du site terminés | Les sorties ignorées sont validées ou comparées par la CI de PR ordinaire |
| Flux de travail d’épinglage de traduction | Le gitlink docs/book/po est initialisé et respecte le contrat d’épinglage du dépôt de catalogue | La couverture du catalogue est complète ou la qualité de la traduction est acceptable |
| Déploiement de la documentation | La référence sélectionnée est compilée et peut être fusionnée dans la mise en page gh-pages versionnée | Une PR source normale a régénéré chaque sortie ignorée avant la revue |
La CI obligatoire des PR exécute les contrôles bloquants de qualité de la documentation et des liens ajoutés, mais elle n’exécute pas la compilation complète de mdBook pour chaque modification de la documentation. Les réviseurs doivent demander les éléments de preuve supplémentaires les plus ciblés couvrant le générateur modifié ou la limite de rendu concernée, plutôt que de supposer que des contrôles de texte réussis prouvent que la sortie générée est à jour.
Règles de correction
- Corriger les erreurs de référence de configuration dans le schéma typé, les dérivations ou le générateur schema-to-Markdown.
- Corriger les erreurs de référence de la CLI dans la définition de la commande Clap ou le générateur d’aide Markdown.
- Corrigez le comportement de l’installation stable dans le contrat de route typé ou son moteur de rendu, puis exécutez
cargo generate installers; ne modifiez pas manuellement l’extrait d’installation suivi. - Corrigez le comportement de la syntaxe SOP ou les descriptions des opérateurs dans le catalogue de l’analyseur d’exécution, puis exécutez
cargo generate sop-syntax; ne modifiez pas manuellement les listes marquées dans la référence de syntaxe. - Corrigez les erreurs de snippets basés sur les sources dans le registre propriétaire, le fichier de métadonnées, le contrat ou le générateur de snippets.
- Corriger la dérive de la liste de thèmes dans
themes.jsonou dans le générateur de régions marquées, et non en modifiant manuellement les boutons générés. - Corrigez le contenu traduit ou le comportement de repli au cours du cycle de vie du catalogue, et non dans le code HTML généré de la locale.
- Ne validez jamais
docs/book/book/, la sortie rustdoc ou toute autre matérialisation ignorée simplement pour donner l’impression qu’une compilation locale est à jour. - Lorsque le comportement du générateur lui-même change, examinez à la fois la modification de la source et un exemple représentatif de sortie régénérée, puis exécutez la vérification qui consomme cette sortie.
Pointeurs source
- Composition des commandes mdBook :
xtask/src/cmd/mdbook/ - Références de la CLI et de la configuration :
xtask/src/cmd/mdbook/refs.rs - Génération des versions localisées et assemblage du site :
xtask/src/cmd/mdbook/build.rs - Configuration du préprocesseur mdBook :
docs/book/book.toml - Registre des paramètres régionaux :
locales.toml - Contrôles de qualité et des liens de la documentation :
scripts/ci/docs_quality_gate.sh,scripts/ci/docs_links_gate.sh - Validation du pin de traduction :
.github/workflows/validate-translations-pin.yml - Déploiement de la documentation :
.github/workflows/docs-deploy.yml - Génération OpenAPI du tableau de bord : Création du tableau de bord web
- Commandes de construction locales : Construire la documentation localement