Canalización de documentación generada
La documentación de ZeroClaw combina Markdown escrito a mano con referencias y fragmentos materializados a partir de tipos de Rust, definiciones de comandos, registros, contratos WIT, archivos de flujo de trabajo y metadatos de UI. El archivo generado no es una segunda fuente de verdad: corrige la fuente propietaria o el generador y, a continuación, reconstruye la documentación.
Usa esta página cuando un cambio afecte a un esquema, una opción de CLI, una característica o inventario de hardware, un contrato de complemento, un mapa de teclas predeterminado, un registro de temas, una directiva de mdBook, una referencia generada, una puerta de documentación o un flujo de trabajo de implementación. Para valores de configuración específicamente, lee también Config lifecycle. Para la salida traducida, continúa con Localization catalog lifecycle.
Mapa de origen a salida
| Superficie | Fuente canónica | Materializador | Salida | Estado del repositorio | Consumidor |
|---|---|---|---|---|---|
| Referencia de configuración | zeroclaw_config::schema::Config más derivaciones de Configurable | cargo mdbook refs o cargo mdbook build, a través de markdown-schema | docs/book/src/reference/config.md | Archivo derivado ignorado | Capítulo de referencia de la configuración y directivas respaldadas por el esquema |
| Referencia de la CLI | Árbol de comandos Clap en src/main.rs | cargo mdbook refs o cargo mdbook build, a través de markdown-help | docs/book/src/reference/cli.md | Archivo derivado ignorado | Capítulo de referencia de la CLI |
| Rutas de instalación | Contratos de rutas tipados en xtask/src/generate/spec.rs y cuerpos de comportamiento generados en los renderizadores del instalador | cargo generate installers, a través de xtask/src/generate/docs.rs y xtask/src/generate/install_sh.rs | docs/book/src/_snippets/install.md, bloques de comandos de Unix generados en README y en las guías de plataforma, regiones generadas de rutas y asistentes de selección en install.sh, y el bloque precompilado de Windows en docs/book/src/setup/windows.md | Superficies generadas con seguimiento | Configuración inicial vinculada desde README, rutas ejecutables de Unix, Quickstart y páginas de configuración de plataformas |
| Referencia de sintaxis de SOP | Catálogo de sintaxis de parse_steps en crates/zeroclaw-runtime/src/sop/mod.rs y ConditionOp::catalog() | cargo generate sop-syntax, mediante xtask/src/generate/sop_syntax.rs | Se marcaron las regiones de comportamiento del analizador y de operadores de condición en docs/book/src/sop/syntax.md | Regiones generadas con seguimiento | Referencia para la creación de SOP |
| Referencia de la API de Rust | Elementos públicos de Rust en los crates del workspace | cargo doc dentro de cargo mdbook refs o cargo mdbook build | target/doc/, copiado a docs/book/book/api/ | Salida de compilación ignorada | Referencia de la API publicada |
| Matriz de características | Inventario de canales, slots de proveedor de modelos, herramientas predeterminadas y docs/book/feature-matrix-parity.toml | xtask/src/cmd/mdbook/feature_matrix.rs durante las compilaciones de configuración regional | docs/book/src/_snippets/feature-matrix-*.md | Fragmentos derivados ignorados | Páginas de comparación de funcionalidades mediante {{#include}} |
| Tablas de hardware | Registro de placas de hardware y catálogo de herramientas, descripciones de transporte en el generador, destinos del flujo de trabajo de lanzamiento y el umbral de poca memoria en install.sh | xtask/src/cmd/mdbook/hardware.rs durante las compilaciones de configuración regional | docs/book/src/_snippets/hardware-*.md | Fragmentos derivados ignorados | Guías de hardware y objetivos de lanzamiento |
| Valores del contrato del complemento | contratos WIT, guías de plugins y límites de src/plugin_registry.rs | xtask/src/cmd/mdbook/plugins.rs durante las compilaciones por idioma | docs/book/src/_snippets/plugin-*.md | Fragmentos derivados ignorados | Guías de autoría de plugins |
| zerocode tablas de claves | Combinación de teclas predeterminada en apps/zerocode/src/keymap/actions.rs | xtask/src/cmd/mdbook/keymap.rs durante las compilaciones de configuración regional | docs/book/src/_snippets/zerocode-*-keys.md | Fragmentos derivados ignorados | zerocode páginas de atajos de teclado |
| Bloques de grupos de pares | docs/book/peer-groups.toml | xtask/src/cmd/mdbook/peer_groups.rs preprocesador de mdBook | Contenido ampliado del capítulo | Solo durante la compilación | Páginas de canal y grupo de pares usando directivas de grupo de pares |
| CSS y nombres de temas | web/src/contexts/themes.json | xtask/src/cmd/mdbook/themes.rs durante las compilaciones de localización | Fragmentos CSS/name ignorados más la región del marcador generado en docs/book/theme/index.hbs rastreado | Mixto: los archivos derivados se ignoran; la plantilla fuera de su marcador sigue estando redactada | Selector de temas de mdBook y referencia del tema zerocode |
| Selector de configuración regional | locales.toml y docs/book/theme/lang-switcher.js.tpl rastreado | inject_lang_switcher_locales durante las compilaciones de configuración regional | docs/book/theme/lang-switcher.js | Archivo derivado ignorado | Selector de idioma publicado |
| Capítulos redactados | docs/book/src/**/*.md y fragmentos rastreados | Preprocesadores y renderizadores de mdBook | HTML de Locale/versión en docs/book/book/ | Fuente rastreada, salida ignorada | Sitio de documentación publicado |
| Tipos de la API del panel | zeroclaw_gateway::openapi::build_spec() y tipos de tiempo de ejecución del gateway | cargo web gen-api | target/openapi.json, web/src/lib/api-generated.ts, web/src/lib/api-descriptions.ts, y web/src/lib/api-enums.ts | Archivos derivados ignorados | Compilación del panel de TypeScript |
Esta matriz describe las superficies de alto valor actuales, no todos los archivos auxiliares producidos durante una compilación. La regla reutilizable es la propiedad: un valor generado debe tener una entrada canónica y una ruta de materialización determinista.
Orden de ensamblaje de mdBook
cargo mdbook es la superficie de comandos xtask definida en .cargo/config.toml. Sus comandos principales componen el pipeline en lugar de invocar directamente un simple mdbook build.
cargo mdbook refs genera el Markdown de la CLI y la configuración a partir del código en vivo, compila el rustdoc del workspace y copia la salida de la API en el árbol de compilación de la documentación. cargo mdbook build ejecuta la secuencia completa con forma de publicación:
- Genera
reference/cli.mdyreference/config.mda partir del árbol de comandos actual y el esquema de configuración. - Construir el espacio de trabajo rustdoc.
- Materializa fragmentos de tema, mapa de teclas, hardware, matriz de características y plugins.
- Ejecuta mdBook una vez para cada configuración regional de
locales.toml, con los preprocesadores configurados mediantedocs/book/book.toml. - Verificar los enlaces en la configuración regional principal renderizada.
- Ensambla el directorio de la versión, la redirección de la configuración regional, el árbol de rustdoc y los recursos compartidos del tema en
docs/book/book/.
El preprocesador peer-group expande sus directivas mientras mdBook procesa cada capítulo. Otros preprocesadores estándar de mdBook gestionan los enlaces, los bloques Mermaid y la localización gettext. Por lo tanto, las referencias generadas deben existir antes del preprocesamiento de capítulos, mientras que la expansión de directivas y la traducción ocurren durante la compilación de la locale.
El flujo de trabajo de despliegue de la documentación inicializa el submódulo de traducción, instala las herramientas de mdBook necesarias, ejecuta cargo mdbook build y fusiona la versión ensamblada en la rama gh-pages. No llama a ningún proveedor de traducción ni repara catálogos durante el despliegue.
Salidas rastreadas y solo de compilación
Los archivos rastreados son entradas o plantillas revisables: Markdown creado, locales.toml, docs/book/peer-groups.toml, metadatos de paridad de la matriz de funciones, plantillas de temas, fuentes de Rust/WIT y definiciones de flujos de trabajo. La ruta docs/book/po es un gitlink rastreado al repositorio independiente de catálogos de traducción; sus contenidos y etiquetas de versión tienen su propio ciclo de vida.
Los archivos ignorados son materializaciones reproducibles: referencias de la CLI y de configuración, la mayoría de los fragmentos generados, rustdoc, HTML renderizado, JavaScript del selector de idioma, CSS del tema generado y el cliente de API de TypeScript del panel. Pueden existir en un árbol de trabajo después de compilar la documentación sin que deban formar parte de un commit. Las superficies de instalación versionadas son excepciones explícitas: docs/book/src/_snippets/install.md, bloques de comandos Unix generados en README y las guías de plataforma, regiones generadas de rutas y auxiliares del selector en install.sh, y el bloque precompilado de Windows en docs/book/src/setup/windows.md.
docs/book/theme/index.hbs es el caso mixto notable. Es una plantilla rastreada, pero el generador de temas solo reescribe la región de lista de temas marcada desde themes.json. Si un comando de generación estándar modifica esa región, inspecciona si el registro canónico o el generador cambiaron; no trates la lista generada como contenido de autoría independiente.
Deriva y controles de validación
Las distintas comprobaciones cubren distintas clases de fallos:
| Comprobar | Lo que demuestra | Lo que no demuestra |
|---|---|---|
| Control de calidad de la documentación | El Markdown modificado cumple la política de rayas en prosa y supera markdownlint | Las referencias o fragmentos ignorados se regeneraron a partir del código actual |
| Control de enlace añadido | Los nuevos enlaces locales de Markdown del diff comparado se resuelven | Los enlaces existentes, los enlaces generados fuera del diff o la navegación renderizada funcionan correctamente |
cargo mdbook check | Los catálogos PO se analizan y superan las auditorías de respuesta generada, literal protegida y ruta local | Las referencias de la CLI/configuración y los fragmentos ignorados coinciden con el código fuente actual de Rust |
cargo mdbook refs | CLI/config referencia Markdown y rustdoc pueden generarse desde el código actual | Cada configuración regional y tema se combinan para formar un sitio completo |
cargo mdbook build | Referencias completas, fragmentos, compilaciones de configuración regional, enlaces renderizados y ensamblado del sitio completados | Las salidas ignoradas se incluyen en commits o se comparan mediante la CI habitual de las PR |
| Flujo de trabajo de anclaje de traducción | El gitlink docs/book/po está inicializado y cumple el contrato de fijación del repositorio de catálogo | La cobertura del catálogo está completa o la calidad de la traducción es aceptable |
| Despliegue de la documentación | La referencia seleccionada se compila y puede fusionarse en el diseño gh-pages versionado | Una PR de código fuente normal volvió a generar todos los archivos de salida ignorados antes de la revisión |
El CI de PR obligatorio ejecuta las comprobaciones de calidad de la documentación y de los enlaces añadidos, pero no ejecuta la compilación completa de mdBook para cada cambio en la documentación. Los revisores deben solicitar la evidencia adicional más acotada que cubra el generador modificado o el límite de renderizado, en lugar de asumir que las comprobaciones de prosa en verde demuestran que la salida generada está actualizada.
Reglas de corrección
- Corregir errores de referencia de configuración en el esquema tipado, las derivaciones o el generador de esquema a Markdown.
- Corrige los errores de referencia de la CLI en la definición del comando Clap o en el generador de ayuda de Markdown.
- Corrige el comportamiento de la instalación estable en el contrato de rutas tipado o en su renderizador y, a continuación, ejecuta
cargo generate installers; no edites manualmente el fragmento de instalación versionado. - Corrige el comportamiento de la sintaxis SOP o las descripciones de los operadores en el catálogo del analizador en tiempo de ejecución y, a continuación, ejecuta
cargo generate sop-syntax; no edites manualmente las listas marcadas en la referencia de sintaxis. - Corrige los errores de los fragmentos respaldados por el código fuente en el registro responsable, el archivo de metadatos, el contrato o el generador de fragmentos.
- Corrige el desfase de la lista de temas en
themes.jsono en el generador de regiones marcadas, no editando manualmente los botones generados. - Corrige el contenido traducido o el comportamiento de reserva a través del ciclo de vida del catálogo, no en el HTML de la configuración regional renderizada.
- Nunca hagas commit de
docs/book/book/, de la salida de rustdoc ni de ninguna otra materialización ignorada solo para que una compilación local parezca actualizada. - Cuando el comportamiento del generador cambia, revisa tanto el cambio en el código fuente como una salida regenerada representativa, luego ejecuta la comprobación que consume esa salida.
Punteros de origen
- Composición de comandos mdBook:
xtask/src/cmd/mdbook/ - Referencias de CLI y configuración:
xtask/src/cmd/mdbook/refs.rs - Construcciones locales y ensamblaje del sitio:
xtask/src/cmd/mdbook/build.rs - Configuración del preprocesador de mdBook:
docs/book/book.toml - Registro de configuraciones regionales:
locales.toml - Compuertas de calidad y enlaces de documentación:
scripts/ci/docs_quality_gate.sh,scripts/ci/docs_links_gate.sh - Validación de anclaje de traducción:
.github/workflows/validate-translations-pin.yml - Despliegue de documentación:
.github/workflows/docs-deploy.yml - Generación de OpenAPI del dashboard: Compilación del dashboard web
- Comandos de compilación local: Compilar la documentación localmente