fix(docgen): generate CLI docs in one process (#4474)

Add a bulk help docs writer that emits the root CLI reference and website command pages from a single Cobra walk. Update the shell generator to call that mode, preserve the pure-Go docs binary guard, and refresh historical versioned CLI docs only when release snapshotting requests a specific version.

Agent-Signature: codex-gpt-5.5-medium on behalf of matt wilkie
This commit is contained in:
matt wilkie 2026-06-22 18:25:58 -07:00 • committed by GitHub
commit dfa8ea4813
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
64 changed files with 356 additions and 244 deletions

View file

@ -18,6 +18,9 @@ Generates maintained CLI reference docs from the live Cobra command tree exposed
# Regenerate checked-in CLI docs using a temporary no-cgo build
./scripts/generate-cli-docs.sh
# Regenerate the live docs and one release snapshot
./scripts/generate-cli-docs.sh --versioned 1.0.5
# Regenerate/check against an existing binary
./scripts/generate-cli-docs.sh ./bd
./scripts/generate-cli-docs.sh --check ./bd
@ -25,12 +28,12 @@ Generates maintained CLI reference docs from the live Cobra command tree exposed
### Outputs
- `docs/CLI_REFERENCE.md` from `bd help --all`
- `website/docs/cli-reference/*.md` from `bd help --list` and `bd help --doc <command>`
- `website/versioned_docs/version-*/cli-reference/*.md` so published versioned docs and the llms artifact source stay in sync
- `docs/CLI_REFERENCE.md` from the live Cobra command tree
- `website/docs/cli-reference/*.md` from the live Cobra command tree
- `website/versioned_docs/version-X.Y.Z/cli-reference/*.md` only when `--versioned X.Y.Z` is supplied by the release snapshot workflow
- `website/static/llms-full.txt` freshness is checked from the same generated website docs tree
`scripts/check-doc-flags.sh` runs the `--check` mode in CI and fails when live top-level commands are missing from generated docs or `llms-full.txt` is stale.
`scripts/check-doc-flags.sh` runs the `--check` mode in CI and fails when live top-level commands are missing from live generated docs or `llms-full.txt` is stale. Historical Docusaurus CLI snapshots are release artifacts; ordinary PR checks do not rewrite them to match unreleased commands.
## check-docs-version.sh