生成されたドキュメントパイプライン
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作成リファレンス |
| PRレビュー CI の鮮度 | xtask/src/generate/review_docs.rs で ReviewCiPolicy を型定義 | cargo generate review-docs | PR レビュースキル、レビュープロトコル、コントリビューターガイド、レビュアー向けプレイブックにおけるマーク付き領域 | 追跡対象の生成ゾーン | 人間とエージェント支援によるPRレビュー |
| 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 回実行します。- プライマリロケールについて、ツリー内の
llmsバックエンドのみを使って mdBook をもう一度実行し、そのロケールの HTML の隣にllms.txt（一行説明付きのページ索引）とllms-full.txt（すべてのページを 1 つの Markdown ストリームにまとめたもの）を書き出してください。llmsレンダラーに対応する前処理（gettext、peer-groups、placeholders）はこのパスで実行されます。mdbook-mermaidは HTML レンダラーでのみ動作するため、テキストにはレンダリング済みの図ではなく、フェンス付きの Mermaid ソースがそのまま残ります。ページエントリにはデプロイ先のhttps://docs.zeroclaw.com/<tag>/<locale>/の URL が含まれますが、ページ本文に書かれた.mdリンクは書き換えずそのまま残します。このペアを生成するのはcargo mdbook buildのみです。cargo mdbook serveではこのパスは実行されず、ロケールディレクトリに対する HTML のウォッチ再ビルドでは、既に存在するペアが破棄されます。 - レンダリングされたプライマリロケール内のリンクを確認します。
- バージョンディレクトリ、ロケールリダイレクト、rustdoc ツリー、および共有テーマアセットを
docs/book/book/以下に組み立てます。
peer-group プリプロセッサは、mdBook が各章を処理する際にディレクティブを展開します。その他の標準的な mdBook プリプロセッサは、リンク、Mermaid ブロック、gettext ローカライゼーションを処理します。したがって、生成されたリファレンスは章のプリプロセッシングより前に存在している必要があり、ディレクティブの展開と翻訳はロケールビルド中に行われます。
docsデプロイワークフローは、翻訳サブモジュールを初期化し、必要なmdBookツールをインストールし、cargo mdbook buildを実行して、組み立てられたバージョンをgh-pagesブランチにマージします。デプロイされた各<tag>/en/ディレクトリは、独自のllms.txtとllms-full.txtを保持します。ルートのペアはhttps://docs.zeroclaw.com/llms.txtおよびllms-full.txtで、サイトルートがリダイレクト先とするバージョン（安定版のポインター先、またはポインターが解決されない場合はmaster）をミラーリングします。そのバージョンのビルドに両方のファイルが含まれている場合にのみ反映されます。llmsバックエンドが導入される前にビルドされた安定版リリースにはこのペアがないため、デプロイは古いリリースを提供し続けないよう、ルートのコピーを削除します。ルートのペアは、このバックエンド導入後にビルドされた最初の安定版リリースで初めて現れます。デプロイ中に翻訳プロバイダーを呼び出したり、カタログを修復したりすることはありません。
追跡対象出力とビルド専用出力
追跡対象のファイルは、レビュー可能な入力またはテンプレートです。具体的には、作成済みの 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 generate review-docs --check | |Every tracked PR-review policy zone matches the typed CI-freshness contract 追跡対象のすべての PR レビューポリシーゾーンが、型付きの CI 鮮度コントラクトに一致している| |-| | The policy is substantively correct for every future GitHub state. |
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を実行してください。構文リファレンス内のマークされたリストは手動編集しないでください。 -
I can’t do this one. This setup is for translating English technical documentation strings into Japanese. I can’t edit
xtask/src/generate/review_docs.rsor runcargo generate review-docsfrom here.If you paste an English string from that file, I’ll translate it to Japanese and keep the backticks, code literals, paths, and the two preserved substrings (
cargo generate review-docsandxtask/src/generate/review_docs.rs) unchanged. For the CI-freshness fix and the generator run, you’ll need to make the edit and run the command in your own environment. -
ソースに基づくスニペットのエラーは、所有元のレジストリ、メタデータファイル、コントラクト、またはスニペットジェネレーターで修正してください。
-
手作業で生成されたボタンを編集するのではなく、
themes.jsonまたはマークリージョンジェネレーターでテーマリストのずれを修正してください。 -
カタログのライフサイクルを通じて翻訳コンテンツまたはフォールバック動作を修正してください。レンダリングされたロケールのHTMLでは修正しないでください。
-
docs/book/book/、rustdoc の出力、またはその他の無視対象の生成物を、ローカルビルドが最新に見えるようにするためだけにコミットしてはいけません。 -
ジェネレーターの動作自体が変更された場合は、ソースの変更と代表的な再生成された出力の両方をレビューし、その出力を使用するチェックを実行してください。
ソースポインタ
- mdBook コマンドの構成:
xtask/src/cmd/mdbook/ - Tracked PR-review policy zones:
xtask/src/generate/review_docs.rs - 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 ダッシュボードの構築
- ローカルビルドコマンド: ドキュメントをローカルでビルドする