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

@ -72,7 +72,6 @@ fi
GEN_PATHSPECS=(
"docs/CLI_REFERENCE.md"
"website/docs/cli-reference"
":(glob)website/versioned_docs/*/cli-reference/**"
"website/static/llms-full.txt"
)
@ -114,12 +113,8 @@ surface_fingerprint() {
cat "$f"
fi
done
local dirs=()
for d in website/docs/cli-reference website/versioned_docs/*/cli-reference; do
[ -d "$d" ] && dirs+=("$d")
done
if [ "${#dirs[@]}" -gt 0 ]; then
find "${dirs[@]}" -type f -name '*.md' | sort | while IFS= read -r f; do
if [ -d website/docs/cli-reference ]; then
find website/docs/cli-reference -type f -name '*.md' | sort | while IFS= read -r f; do
printf '== %s\n' "$f"
cat "$f"
done

View file

@ -133,12 +133,6 @@ if [ -f "$CLI_REF" ]; then
fi
WEBSITE_DIRS=("$PROJECT_ROOT/website/docs/cli-reference")
if [ -d "$PROJECT_ROOT/website/versioned_docs" ]; then
for vdir in "$PROJECT_ROOT"/website/versioned_docs/version-*; do
[ -d "$vdir" ] || continue
WEBSITE_DIRS+=("$vdir/cli-reference")
done
fi
for dir in "${WEBSITE_DIRS[@]}"; do
if [ ! -d "$dir" ]; then
continue

View file

@ -106,7 +106,7 @@ if [ "$MISMATCH" -ne 0 ]; then
echo " npx docusaurus docs:version $CANONICAL"
echo " cd .."
echo " # Ensure website/docusaurus.config.ts lastVersion is '$CANONICAL'"
echo " ./scripts/generate-cli-docs.sh ./bd"
echo " ./scripts/generate-cli-docs.sh --versioned $CANONICAL ./bd"
echo " ./scripts/generate-llms-full.sh"
echo " BEADS_REQUIRE_RELEASE_DOCS=1 ./scripts/check-docs-version.sh"
;;

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

View file

@ -8,15 +8,43 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
CHECK_MODE=0
if [ "${1:-}" = "--check" ]; then
CHECK_MODE=1
shift
fi
BD_ARG="${1:-}"
VERSIONED_VERSION=""
BD_ARG=""
TMP_BUILD_DIR=""
TMP_OUTPUT_DIR=""
while [ "$#" -gt 0 ]; do
case "$1" in
--check)
CHECK_MODE=1
shift
;;
--versioned)
[ "$#" -ge 2 ] || { echo "Error: --versioned needs a version" >&2; exit 2; }
VERSIONED_VERSION="$2"
shift 2
;;
-h|--help)
cat <<'EOF'
Usage: scripts/generate-cli-docs.sh [--check] [--versioned VERSION] [path-to-bd]
Generate live CLI docs from one bd process. Historical Docusaurus snapshots are
left untouched unless --versioned VERSION is supplied by the release snapshot
workflow.
EOF
exit 0
;;
*)
if [ -n "$BD_ARG" ]; then
echo "Error: multiple bd binaries supplied: $BD_ARG and $1" >&2
exit 2
fi
BD_ARG="$1"
shift
;;
esac
done
cleanup() {
if [ -n "$TMP_BUILD_DIR" ]; then
rm -rf "$TMP_BUILD_DIR"
@ -38,107 +66,31 @@ else
(cd "$PROJECT_ROOT" && CGO_ENABLED=0 go build -tags gms_pure_go -o "$BD" ./cmd/bd/)
fi
# Guard against a CGO-enabled bd: it exposes `bd federation` subcommands that CI never
# produces (scripts/ci/pr-policy.sh build_docs_binary uses env CGO_ENABLED=0 go build).
# If the resolved binary does not print the pure-go stub, rebuild pure-go internally.
if [ -x "$BD" ] && ! "$BD" federation --help 2>&1 | grep -q "Federation commands require CGO"; then
echo "CGO-enabled bd detected at $BD; rebuilding pure-go binary for CI-consistent docs..."
if [ -z "$TMP_BUILD_DIR" ]; then
TMP_BUILD_DIR="$(mktemp -d)"
fi
BD="$TMP_BUILD_DIR/bd-pure"
(cd "$PROJECT_ROOT" && CGO_ENABLED=0 go build -tags gms_pure_go -o "$BD" ./cmd/bd/)
fi
if [ ! -x "$BD" ]; then
echo "Error: bd binary not found or not executable: $BD" >&2
echo "Usage: $0 [--check] [path-to-bd]" >&2
echo "Usage: $0 [--check] [--versioned VERSION] [path-to-bd]" >&2
exit 1
fi
command_doc_id() {
printf '%s' "$1" \
| tr '[:upper:] ' '[:lower:]-' \
| sed -E 's/[^a-z0-9-]+/-/g; s/-+/-/g; s/^-//; s/-$//'
}
trim_trailing_blank_lines() {
perl -0pi -e 's/\n+\z/\n/' "$1"
}
generate_index() {
local out_dir="$1"
local commands_file="$2"
local version_label="$3"
local count
count="$(wc -l < "$commands_file" | tr -d ' ')"
cat > "$out_dir/index.md" << EOF
---
id: index
title: CLI Reference
sidebar_position: 0
---
# CLI Reference
<!-- AUTO-GENERATED: do not edit manually -->
Reference for bd ${version_label}. Generated from \`bd help --list\` and \`bd help --doc <command>\`.
This reference covers all ${count} live top-level \`bd\` commands. Regenerate it with:
\`\`\`bash
./scripts/generate-cli-docs.sh
\`\`\`
## Commands
EOF
while IFS= read -r cmd; do
cmd="${cmd%$'\r'}"
local doc_id
doc_id="$(command_doc_id "$cmd")"
printf -- "- [\`bd %s\`](./%s.md)\n" "$cmd" "$doc_id" >> "$out_dir/index.md"
done < "$commands_file"
}
generate_cli_dir() {
local out_dir="$1"
local commands_file="$2"
local version_label="$3"
mkdir -p "$out_dir"
rm -f "$out_dir"/*.md
generate_index "$out_dir" "$commands_file" "$version_label"
while IFS= read -r cmd; do
cmd="${cmd%$'\r'}"
local doc_id
doc_id="$(command_doc_id "$cmd")"
"$BD" help --doc "$cmd" < /dev/null > "$out_dir/$doc_id.md"
trim_trailing_blank_lines "$out_dir/$doc_id.md"
done < "$commands_file"
}
generate_all() {
local root="$1"
local commands_file="$root/.cli-commands.txt"
mkdir -p "$root/docs"
"$BD" help --list > "$commands_file"
"$BD" help --all > "$root/docs/CLI_REFERENCE.md"
trim_trailing_blank_lines "$root/docs/CLI_REFERENCE.md"
generate_cli_dir "$root/website/docs/cli-reference" "$commands_file" "Latest"
# Versioned snapshots: parse the semver tag from the directory name
# (e.g. "version-1.0.0" -> "v1.0.0") so a release bump alone produces
# zero diff on the dev tree.
local versioned_parent="$PROJECT_ROOT/website/versioned_docs"
if [ -d "$versioned_parent" ]; then
local versioned_dir
for versioned_dir in "$versioned_parent"/version-*; do
[ -d "$versioned_dir" ] || continue
local dir_name
dir_name="$(basename "$versioned_dir")"
local version_tag="v${dir_name#version-}"
generate_cli_dir \
"$root/website/versioned_docs/$dir_name/cli-reference" \
"$commands_file" \
"$version_tag"
done
local args=(help --docs-root "$root")
if [ -n "$VERSIONED_VERSION" ]; then
args+=(--docs-version "$VERSIONED_VERSION")
fi
rm -f "$commands_file"
"$BD" "${args[@]}"
}
if [ "$CHECK_MODE" -eq 1 ]; then
@ -164,11 +116,8 @@ if [ "$CHECK_MODE" -eq 1 ]; then
fi
check_dirs=("website/docs/cli-reference")
if [ -d "$PROJECT_ROOT/website/versioned_docs" ]; then
for vdir in "$PROJECT_ROOT/website/versioned_docs"/version-*; do
[ -d "$vdir" ] || continue
check_dirs+=("website/versioned_docs/$(basename "$vdir")/cli-reference")
done
if [ -n "$VERSIONED_VERSION" ]; then
check_dirs+=("website/versioned_docs/version-$VERSIONED_VERSION/cli-reference")
fi
for rel in "${check_dirs[@]}"; do
@ -188,5 +137,9 @@ if [ "$CHECK_MODE" -eq 1 ]; then
else
generate_all "$PROJECT_ROOT"
echo "Generated CLI docs from: $($BD version 2>/dev/null | head -1 || echo "$BD")"
echo "Updated docs/CLI_REFERENCE.md and website CLI reference pages"
if [ -n "$VERSIONED_VERSION" ]; then
echo "Updated docs/CLI_REFERENCE.md, website CLI reference pages, and version-$VERSIONED_VERSION CLI snapshot"
else
echo "Updated docs/CLI_REFERENCE.md and live website CLI reference pages"
fi
fi

View file

@ -79,7 +79,7 @@ trap 'rm -f "$BD_DOCS"' EXIT
CGO_ENABLED=0 go build -tags gms_pure_go -o "$BD_DOCS" ./cmd/bd/
echo " • generate-cli-docs.sh"
./scripts/generate-cli-docs.sh "$BD_DOCS"
./scripts/generate-cli-docs.sh --versioned "$VERSION" "$BD_DOCS"
echo " • generate-llms-full.sh"
./scripts/generate-llms-full.sh