feat(cli-docs): auto-generate CLI reference from schema JSON

[Mpdreamz]

What is this?

This PR adds automatic CLI reference documentation generation to docs-builder. Point it at a JSON schema file describing a CLI's command tree and it generates a full, navigable reference — one page per command, one page per namespace — wired directly into the docs site's table of contents.

docs-builder's own CLI reference (/cli/) is now generated this way.

cursorful-video-1777577780994.mp4

Why PR #3202 is a prerequisite

This PR consumes a schema JSON file that describes a CLI's full command tree — every namespace, command, and parameter — with names, types, required/optional, descriptions, default values, and enum choices. The schema format is straightforward and any CLI from any ecosystem can emit it.

docs-builder inherits schema generation from Nullean.Argh, which is what PR #3202 migrates to. Nullean.Argh 0.13.0 introduced a built-in --emit-schema / __schema command that outputs exactly this JSON. That's the convenient on-ramp — but a Go CLI, a Python CLI, or anything else that can write the same JSON structure can use this system just as well.

Configuring it

One new key in docset.yml:

toc:
  - cli: cli/schema.json      # path to the schema JSON
    folder: cli               # virtual URL root and supplemental docs folder
    children:                 # optional: hand-written pages that appear first
      - file: installation.md
      - file: configuration.md

That's it. docs-builder discovers the full command tree from the schema and generates the rest. The children list is for narrative pages (installation guides, config walkthroughs) that sit alongside the reference.

To serve a CLI repo's docs standalone:

docs-builder serve --path /path/to/cli-repo/docs

(This PR also fixes a scoped-filesystem bug that prevented --path from pointing outside the docs-builder repo.)

What gets generated

Namespace index pages

Every namespace (elastic stack, elastic cloud hosted, …) gets an index page with:

• A cli namespace badge right-aligned in the <h1>
• A binary namespace --help usage codeblock
• Clickable page cards for every sub-namespace and command — full-width bordered rows with a title, description, and right-pointing chevron

┌────────────────────────────────────────────────────────────┐
│  put-view                                                → │
│  Create or update an ES|QL view.                           │
└────────────────────────────────────────────────────────────┘

The {page-card} directive

The page cards on namespace indexes are powered by a new general-purpose {page-card} directive, available in any hand-written Markdown page:

:::{page-card} [Installation](./installation.md)
Get the CLI installed and linked in under a minute.
:::

:::{page-card} [Elasticsearch overview](elasticsearch://docs/get-started.md)
Cross-link to another docs set using the standard crosslink scheme.
:::

The argument must be a Markdown link — [Title](url). The URL is restricted to local relative paths (.md files) or crosslink scheme URIs (e.g. elasticsearch://…). Absolute http:// / https:// URLs are rejected at build time with a clear error, keeping page cards as in-docs navigation rather than external links. The body (description line) is optional.

Command pages

Every command gets a page with:

• A cli command badge right-aligned in the <h1> (amber, matching the sidebar pill)
• A usage line — always present, always copy-paste ready
• Separate Arguments and Options sections rendered as definition lists

Usage lines that are actually useful

When the schema provides an explicit usage string it's used as-is (with automatic wrapping at 80 characters into multiline bash-continuation style). When there's no explicit usage — which is common — docs-builder generates one from the schema itself:

elastic stack es esql put-view --name <name> --query <query> [options]

Required named flags appear individually with their placeholder (--flag <flag>). Positional arguments are listed with angle brackets. Optional flags collapse to [options]. The result is a line you can copy, fill in the blanks, and run — not a generic [options] mystery.

Parameter anchors

Every flag and option has a fragment anchor (#flag-name). Hover any parameter term to reveal a # link; clicking it updates the URL so you can share a direct link to a specific flag.

Full-path page titles and sidebar pills

Pages carry their full command path as the title (assembler bloom-filter, not just bloom-filter) so they're unambiguous in search and browser history. The sidebar shows colour-coded pills — purple for namespaces, amber for commands — matching the badge colours in the heading.

Injecting custom content (supplemental docs)

The generated content is great for reference, but sometimes you need context, examples, or warnings that don't belong in the schema. The supplemental docs system handles this without touching the generator.

Folder layout (using folder: cli as the virtual root):

docs/cli/
├── index.md              # overrides the root CLI page body
├── installation.md       # extra hand-written page (listed in children:)
├── configuration.md      # extra hand-written page
├── assembler/
│   └── index.md          # overrides the `assembler` namespace body
└── cmd-serve.md          # overrides the `serve` command body (flat style)

Alternative flat naming also works: ns-assembler.md, cmd-assembler-bloom-filter.md.

Supplemental content replaces only the description section. The schema-driven heading, usage codeblock, parameter tables, and navigation cards still render — supplemental adds human context on top of machine precision.

Keeping docs in sync with the CLI

Generated docs are only valuable if they stay accurate. A CI step enforces this — it re-runs docs-builder __schema, diffs the output against the committed docs/cli-schema.json, and fails the build if they differ:

- name: Check CLI schema is up to date
  run: |
    dotnet run --project src/tooling/docs-builder -- __schema > docs/cli-schema.json.tmp
    diff docs/cli-schema.json docs/cli-schema.json.tmp || \
      (echo "docs/cli-schema.json is out of date — run: docs-builder __schema > docs/cli-schema.json" && exit 1)

Add a command, rename a flag, change a description — CI tells you to regenerate the schema before merging. The docs can never silently lag behind the CLI.

Test plan

• docs-builder serve --path docs → /cli/ renders docs-builder's own CLI reference
• docs-builder serve --path <external-cli-repo>/docs → CLI reference renders with correct binary name in usage lines
• Namespace pages show page cards that navigate correctly on click
• Command pages without a schema usage field show a generated usage line with required flags explicit
• Parameter terms have fragment anchors; clicking one updates the browser URL
• {page-card} directive works in a hand-authored .md page
• Sidebar shows elastic CLI / docs-builder CLI root titles with correct colour pills

🤖 Generated with Claude Code