生成されたドキュメントパイプライン
ZeroClaw のドキュメントは、手作業で記述された Markdown と、Rust の型、コマンド定義、レジストリ、WIT コントラクト、ワークフローファイル、UI メタデータから生成された参照やスニペットを組み合わせて構成されています。生成されたファイルは第二の信頼できる情報源ではありません。所有元のソースまたはジェネレーターを修正してから、ドキュメントを再ビルドしてください。
変更がスキーマ、CLI フラグ、機能インベントリまたはハードウェアインベントリ、プラグインコントラクト、デフォルトキーマップ、テーマレジストリ、mdBook ディレクティブ、生成リファレンス、docs gate、またはデプロイメントワークフローに関係する場合は、このページを参照してください。構成値については、あわせて Config lifecycle も読んでください。翻訳済み出力については、Localization catalog lifecycle に進んでください。
ソースから出力への対応表
| Surface | 正規ソース | マテリアライザー | 出力 | リポジトリの状態 | コンシューマー |
|---|---|---|---|---|---|
| 設定リファレンス | zeroclaw_config::schema::Config と Configurable の導出 | markdown-schema を介した cargo mdbook refs または cargo mdbook build | docs/book/src/reference/config.md | 無視された派生ファイル | 設定リファレンスの章とスキーマに基づくディレクティブ |
| CLIリファレンス | src/main.rs の Clap コマンドツリー | cargo mdbook refs または cargo mdbook build、markdown-help 経由 | docs/book/src/reference/cli.md | 無視された派生ファイル | CLIリファレンスの章 |
| インストールパス | xtask/src/generate/spec.rs の型付きルートコントラクトと、インストーラーのレンダラーにおける生成された動作本体 | cargo generate installers は xtask/src/generate/docs.rs と xtask/src/generate/install_sh.rs を介して | docs/book/src/_snippets/install.md、README とプラットフォームガイド内の生成された Unix コマンドブロック、install.sh 内の生成された route および picker-helper 領域、そして docs/book/src/setup/windows.md 内の Windows の事前ビルドブロック | 追跡対象の生成サーフェス | README にリンクされた初回セットアップ、実行可能な Unix ルート、Quickstart、プラットフォームのセットアップページ |
| SOP 構文リファレンス | crates/zeroclaw-runtime/src/sop/mod.rs の parse_steps 構文カタログおよび ConditionOp::catalog() | cargo generate sop-syntax は xtask/src/generate/sop_syntax.rs を通じて | docs/book/src/sop/syntax.md 内のパーサーの動作と条件演算子の領域をマークしました | 追跡対象の生成領域 | SOP作成リファレンス |
| Rust API リファレンス | ワークスペース内のクレート全体にわたる公開 Rust アイテム | cargo mdbook refs または cargo mdbook build 内の cargo doc | target/doc/、docs/book/book/api/ にコピーされます | 無視されたビルド出力 | 公開済み API リファレンス |
| 機能マトリックス | チャネル一覧、モデルプロバイダーのスロット、デフォルトツール、および docs/book/feature-matrix-parity.toml | ロケールビルド時の xtask/src/cmd/mdbook/feature_matrix.rs | docs/book/src/_snippets/feature-matrix-*.md | 派生スニペットを無視しました | {{#include}} による機能比較ページ |
| ハードウェアテーブル | ハードウェアボードレジストリとツールカタログ、ジェネレーター内のトランスポートの説明、リリースワークフローのターゲット、および install.sh の低メモリしきい値 | xtask/src/cmd/mdbook/hardware.rs ロケールビルド中 | docs/book/src/_snippets/hardware-*.md | 派生スニペットを無視しました | ハードウェアとリリースターゲットのガイド |
| プラグインのコントラクト値 | WITコントラクト、プラグインガイド、および src/plugin_registry.rs の制限 | xtask/src/cmd/mdbook/plugins.rs のロケールビルド時 | docs/book/src/_snippets/plugin-*.md | 派生スニペットを無視しました | プラグイン作成ガイド |
| zerocode キーテーブル | apps/zerocode/src/keymap/actions.rs 内のデフォルトキーマップ | ロケールビルド中の xtask/src/cmd/mdbook/keymap.rs | docs/book/src/_snippets/zerocode-*-keys.md | 派生スニペットを無視しました | zerocode のキーバインドページ |
| ピアグループブロック | docs/book/peer-groups.toml | xtask/src/cmd/mdbook/peer_groups.rs mdBook プリプロセッサー | 章の内容を拡張しました | ビルド時のみ | peer-group ディレクティブを使用するチャネルページと peer-group ページ |
| テーマの CSS と名前 | web/src/contexts/themes.json | ロケールビルド中のxtask/src/cmd/mdbook/themes.rs | 追跡対象の docs/book/theme/index.hbs 内の、無視されたCSS/名前フラグメントおよび生成されたマーカー領域 | 混在: 派生ファイルは無視されますが、マーカー外のテンプレートは編集可能なまま残ります | mdBookのテーマピッカーとzerocode テーマリファレンス |
| ロケール切り替え | locales.toml と追跡された docs/book/theme/lang-switcher.js.tpl | ロケールビルド中の inject_lang_switcher_locales | docs/book/theme/lang-switcher.js | 無視された派生ファイル | 公開済み言語セレクター |
| 執筆した章 | docs/book/src/**/*.md とトラッキングされたスニペット | mdBook のプリプロセッサとレンダラ | docs/book/book/ 配下のロケール/バージョン HTML | 追跡されたソース、無視された出力 | 公開済みのドキュメントサイト |
| ダッシュボード API タイプ | zeroclaw_gateway::openapi::build_spec() とゲートウェイランタイム型 | cargo web gen-api | target/openapi.json、web/src/lib/api-generated.ts、web/src/lib/api-descriptions.ts、および web/src/lib/api-enums.ts | 派生ファイルを無視しました | TypeScript ダッシュボードのビルド |
このマトリックスは、ビルド中に生成されるすべてのヘルパーファイルではなく、現在の価値の高いサーフェスを説明しています。再利用可能なルールは所有権です。生成された値は、1つの正規の入力と1つの決定的なマテリアライズパスを持つべきです。
mdBook アセンブリ順序
cargo mdbook は .cargo/config.toml で定義された xtask のコマンドインターフェイスです。主なコマンドは、単に mdbook build を直接呼び出すのではなく、パイプラインを構成します。
cargo mdbook refs は実コードから CLI と設定の Markdown を生成し、ワークスペースの rustdoc をビルドして、API 出力をドキュメントのビルドツリーにコピーします。cargo mdbook build は公開時と同じ一連の処理を実行します：
- 現在のコマンドツリーと設定スキーマから
reference/cli.mdとreference/config.mdを生成します。 - ワークスペースの rustdoc をビルドします。
- テーマ、キーマップ、ハードウェア、機能マトリックス、プラグインのスニペットをマテリアライズします。
locales.toml内の各ロケールごとに、docs/book/book.tomlで設定されたプリプロセッサーを使用して mdBook を 1 回実行します。- レンダリングされたプライマリロケール内のリンクを確認します。
- バージョンディレクトリ、ロケールリダイレクト、rustdoc ツリー、および共有テーマアセットを
docs/book/book/以下に組み立てます。
peer-group プリプロセッサは、mdBook が各章を処理する際にディレクティブを展開します。その他の標準的な mdBook プリプロセッサは、リンク、Mermaid ブロック、gettext ローカライゼーションを処理します。したがって、生成されたリファレンスは章のプリプロセッシングより前に存在している必要があり、ディレクティブの展開と翻訳はロケールビルド中に行われます。
ドキュメントのデプロイワークフローは、翻訳サブモジュールを初期化し、必要な mdBook ツールをインストールし、cargo mdbook build を実行し、組み立てられたバージョンを gh-pages ブランチにマージします。デプロイ中に翻訳プロバイダーを呼び出したり、カタログを修復したりすることはありません。
追跡対象出力とビルド専用出力
追跡対象のファイルはレビュー可能な入力またはテンプレートです。作成された Markdown、locales.toml、docs/book/peer-groups.toml、フィーチャーマトリックスのパリティメタデータ、テーマテンプレート、Rust/WIT ソース、ワークフロー定義などが含まれます。docs/book/po パスは、別の翻訳カタログリポジトリへの追跡対象 gitlink であり、その内容とリリースタグは独自のライフサイクルを持ちます。
無視されるファイルは再現可能な生成物です。CLI と設定の参照、生成されたスニペットの大半、rustdoc、レンダリング済み HTML、ロケール切り替え用 JavaScript、生成されたテーマ CSS、そしてダッシュボードの TypeScript API クライアントが含まれます。これらは、ドキュメントのビルド後に、コミットに含めることなく作業ツリーに存在する場合があります。追跡対象のインストール関連ファイルは明示的な例外です。具体的には、docs/book/src/_snippets/install.md、README とプラットフォームガイドにある生成された Unix コマンドブロック、install.sh 内の生成されたルートおよび picker-helper 領域、そして docs/book/src/setup/windows.md 内の Windows prebuilt ブロックです。
docs/book/theme/index.hbs は、注目すべき混在ケースです。これは追跡対象のテンプレートですが、テーマジェネレーターは themes.json から、マークされた theme-list 領域のみを書き換えます。標準の生成コマンドによってその領域が変更された場合は、正規のレジストリまたはジェネレーターが変更されたかどうかを確認してください。生成されたリストを、独立して作成されたコンテンツとして扱わないでください。
ドリフトと検証ゲート
異なるチェックは異なる障害クラスをカバーします：
| 確認 | 証明できること | 何を証明しないか |
|---|---|---|
| ドキュメント品質ゲート | 変更されたMarkdownは散文のemダッシュポリシーとmarkdownlintを通過します | 無視された参照またはスニペットは、現在のコードから再生成されました |
| 追加リンクゲート | 比較した差分内の新しいローカル Markdown リンクが解決される | 既存のリンク、差分外で生成されたリンク、レンダリングされたナビゲーションはすべて正常に機能します。 |
cargo mdbook check | PO カタログは解析でき、generated-response、protected-literal、および local-path の監査に合格する | CLI/config の参照および無視されたスニペットが現在の Rust ソースと一致しています |
cargo mdbook refs | CLI/設定リファレンスの Markdown と rustdoc は、現在のコードから生成できます | すべてのロケールとテーマが、完全なサイトとして組み立てられます |
cargo mdbook build | 完全なリファレンス、スニペット、ロケールビルド、レンダリング済みリンク、サイトアセンブリが完了しました | 無視された出力は通常の PR CI によってコミットまたは比較されます |
| 翻訳のピン留めワークフロー | docs/book/po gitlink は初期化されており、catalog-repository の pin contract を満たしています | カタログのカバレッジが完全であるか、翻訳品質が許容範囲内です |
| ドキュメントのデプロイ | 選択した ref はビルドでき、バージョン管理された gh-pages レイアウトにマージできます | 通常のソースPRはレビュー前に無視されたすべての出力を再生成した |
必須PR CIはドキュメント品質チェックとリンク追加ゲートを実行しますが、すべてのドキュメント変更に対してmdBookのフルビルドを実行するわけではありません。レビュアーは、散文チェックが緑であることが生成された出力が最新であることを証明すると仮定するのではなく、変更されたジェネレーターまたはレンダリング境界をカバーする最小限の追加エビデンスを要求してください。
修正ルール
- 型付きスキーマ、derive、またはスキーマから Markdown を生成するジェネレーターの設定参照エラーを修正します。
- ClапコマンドDefinitionまたはMarkdown-helpジェネレータのCLIリファレンスエラーを修正します。
- 型付きルートコントラクトまたはそのレンダラーで安定したインストール動作を修正してから、
cargo generate installersを実行してください。追跡対象のインストールスニペットを手動で編集しないでください。 - ランタイムパーサーカタログのSOP構文の動作または演算子の説明を修正し、その後
cargo generate sop-syntaxを実行してください。構文リファレンス内のマークされたリストは手動編集しないでください。 - ソースに基づくスニペットのエラーは、所有元のレジストリ、メタデータファイル、コントラクト、またはスニペットジェネレーターで修正してください。
- 手作業で生成されたボタンを編集するのではなく、
themes.jsonまたはマークリージョンジェネレーターでテーマリストのずれを修正してください。 - カタログのライフサイクルを通じて翻訳コンテンツまたはフォールバック動作を修正してください。レンダリングされたロケールのHTMLでは修正しないでください。
docs/book/book/、rustdoc の出力、またはその他の無視対象の生成物を、ローカルビルドが最新に見えるようにするためだけにコミットしてはいけません。- ジェネレーターの動作自体が変更された場合は、ソースの変更と代表的な再生成された出力の両方をレビューし、その出力を使用するチェックを実行してください。
ソースポインタ
- mdBook コマンドの構成:
xtask/src/cmd/mdbook/ - CLIおよび設定のリファレンス:
xtask/src/cmd/mdbook/refs.rs - ロケールのビルドとサイトの構築:
xtask/src/cmd/mdbook/build.rs - mdBookプリプロセッサの設定:
docs/book/book.toml - ロケールレジストリ:
locales.toml - ドキュメント品質とリンクのゲート:
scripts/ci/docs_quality_gate.sh、scripts/ci/docs_links_gate.sh - 翻訳ピンの検証:
.github/workflows/validate-translations-pin.yml - ドキュメントのデプロイ:
.github/workflows/docs-deploy.yml - ダッシュボードの OpenAPI 生成: Web ダッシュボードの構築
- ローカルビルドコマンド: ドキュメントをローカルでビルドする