--- title: "Generate Documentation from the Runtime Model" description: "Generate Documentation from the Runtime Model Why this note exists Reference documentation for an executable interface is prone to drift when command names, flags, inheritance, examples, and child lin…" doc_version: 1 last_updated: 2026-10-15 canonical_url: "http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/cobra/08-generate-documentation-from-the-runtime-model" --- # Generate Documentation from the Runtime Model Generate Documentation from the Runtime Model Why this note exists Reference documentation for an executable interface is prone to drift when command names, flags, inheritance, examples, and child lin… ## Tags - `architecture-garden` - `cobra` - `documentation` - `code-generation` - `command-tree` ## Content # Generate Documentation from the Runtime Model ## Why this note exists Reference documentation for an executable interface is prone to drift when command names, flags, inheritance, examples, and child links are copied into prose by hand. Cobra's `doc` package generates Markdown, man pages, and reStructuredText from the assembled command graph itself. > [!summary] > **Pattern:** derive reference documentation from the executable semantic model instead of maintaining a second schema. > > **Law:** facts that are already authoritative in the runtime model — command path, usage, flags, inheritance, children — should be rendered, not recopied. ## Concrete shape `GenMarkdownCustom` receives a `*cobra.Command`, initializes default help structures, and renders: - command path and short/long descriptions; - runtime `UseLine()` syntax; - examples; - non-inherited options; - inherited parent options; - parent and child `SEE ALSO` links; - an optional autogenerated timestamp. `GenMarkdownTreeCustom` recursively visits available child commands and writes one file per command. It uses `CommandPath()` to derive filenames and a link-handler callback so callers can adapt links to their publishing environment. The generator therefore does not parse source files or maintain an independent command catalog. It asks the live model the same questions that help output asks. ## Why it works The pattern distinguishes **reference facts** from **explanatory design prose**. Reference facts are best generated because they already exist in machine-readable form. Design rationale and failure semantics still require authored documentation. This gives a useful division of responsibility: ```text runtime model -> exact interface reference human-authored study -> why, tradeoffs, failure modes, operational law ``` Generated documentation complements a design Garden; it does not replace it. ## Behavioral contract ### Guarantees - generated docs use the actual command hierarchy supplied to the generator; - local and inherited flags are rendered from the same flag-set views used by runtime help; - unavailable/additional-help-topic commands are filtered by runtime availability methods; - parent/child relationships drive `SEE ALSO` navigation; - callers can customize link transformation and file prepending. ### Non-guarantees - The output documents the **assembled graph at generation time**. Commands added only under runtime configuration or environment-dependent startup may be absent unless generation assembles the same topology. - Generated reference cannot explain which operations are dangerous, transactional, idempotent, or authorized unless those semantics are also encoded in the model. - `GenMarkdownTree` documents a concrete filename-collision limitation: command names containing hyphens can collide with nested command paths after spaces are replaced with underscores/hyphen-like flattened names, leaving output undefined for that case. - The autogenerated date makes byte-for-byte reproducibility time-dependent unless the tag is disabled or normalized by the caller. ## Failure modes and tricky details ### Generating from the wrong phase If defaults, plugins, or dynamic commands are added after the documentation graph is assembled, the reference is stale despite being generated. “Generated” is not synonymous with “correct”; the build must instantiate the same semantic model intended for users. ### Flattened filenames lose structure Turning a hierarchical path into a flat filename needs an injective encoding. Cobra's own warning around hyphenated command names is a concrete example of a general rule: generated artifact names need collision analysis. ### Model fields can still lie A command's `Short`, `Long`, `Example`, or flag usage string is authored metadata. Generation prevents structural drift but cannot make descriptions truthful. Tests or review still need to protect semantic quality. ## Applicability Reuse this pattern for CLIs, HTTP/OpenAPI routers, RPC schemas, plugin registries, configuration schemas, event catalogs, and other interfaces whose runtime model already contains stable reference data. Do not attempt to generate architectural rationale, incident history, security assumptions, or non-guarantees solely from the runtime model unless those concepts are explicitly represented as structured metadata. ## Candidate ecosystem guidance > **Generate reference facts from executable schemas and author rationale separately. Ensure the documentation build assembles the same model phase as production, and make artifact naming collision-free.** ## Evidence and references - `doc/md_docs.go`: Markdown generation from command paths, runtime usage, local/inherited flags, examples and parent/child traversal. - `command.go`: methods consumed by generated docs, including `UseLine`, `Commands`, `CommandPath`, availability and flag provenance. ## Wiki Links - Research/Software Architecture Garden/cobra/README - Research/Software Architecture Garden/cobra/01 - Command Graph as Semantic Authority - Research/Software Architecture Garden/cobra/02 - Hierarchical Policy Inheritance with Local Shadowing ## Backlinks - [research/software-architecture-garden/cobra/index-of-design-patterns](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/cobra/index-of-design-patterns) - [research/software-architecture-garden/cobra/readme](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/cobra/readme) - [research/software-architecture-garden/cobra/01-command-graph-as-semantic-authority](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/cobra/01-command-graph-as-semantic-authority) ## Sitemap - [Home](http://parc.yolo.scapegoat.dev/) - [Home markdown mirror](http://parc.yolo.scapegoat.dev/index.md) - [Markdown sitemap](http://parc.yolo.scapegoat.dev/sitemap.md)