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
145 lines
4.7 KiB
Bash
Executable file
145 lines
4.7 KiB
Bash
Executable file
#!/bin/bash
|
|
# generate-cli-docs.sh — Generate CLI reference docs from the live bd command tree.
|
|
|
|
set -euo pipefail
|
|
export LC_ALL=C
|
|
|
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
|
|
|
|
CHECK_MODE=0
|
|
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"
|
|
fi
|
|
if [ -n "$TMP_OUTPUT_DIR" ]; then
|
|
rm -rf "$TMP_OUTPUT_DIR"
|
|
fi
|
|
}
|
|
trap cleanup EXIT
|
|
|
|
if [ -n "$BD_ARG" ]; then
|
|
BD="$BD_ARG"
|
|
elif [ -x "$PROJECT_ROOT/bd" ]; then
|
|
BD="$PROJECT_ROOT/bd"
|
|
else
|
|
TMP_BUILD_DIR="$(mktemp -d)"
|
|
BD="$TMP_BUILD_DIR/bd"
|
|
echo "Building temporary bd for docs generation..."
|
|
(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] [--versioned VERSION] [path-to-bd]" >&2
|
|
exit 1
|
|
fi
|
|
|
|
generate_all() {
|
|
local root="$1"
|
|
local args=(help --docs-root "$root")
|
|
if [ -n "$VERSIONED_VERSION" ]; then
|
|
args+=(--docs-version "$VERSIONED_VERSION")
|
|
fi
|
|
"$BD" "${args[@]}"
|
|
}
|
|
|
|
if [ "$CHECK_MODE" -eq 1 ]; then
|
|
TMP_OUTPUT_DIR="$(mktemp -d)"
|
|
mkdir -p "$TMP_OUTPUT_DIR/website"
|
|
cp -Rf "$PROJECT_ROOT/website/docs" "$TMP_OUTPUT_DIR/website/docs"
|
|
if [ -d "$PROJECT_ROOT/website/versioned_docs" ]; then
|
|
cp -Rf "$PROJECT_ROOT/website/versioned_docs" "$TMP_OUTPUT_DIR/website/versioned_docs"
|
|
fi
|
|
if [ -f "$PROJECT_ROOT/website/versions.json" ]; then
|
|
cp -f "$PROJECT_ROOT/website/versions.json" "$TMP_OUTPUT_DIR/website/versions.json"
|
|
fi
|
|
|
|
generate_all "$TMP_OUTPUT_DIR"
|
|
|
|
if ! diff -qr \
|
|
"$PROJECT_ROOT/docs/CLI_REFERENCE.md" \
|
|
"$TMP_OUTPUT_DIR/docs/CLI_REFERENCE.md" >/dev/null; then
|
|
echo "FAIL: docs/CLI_REFERENCE.md is out of sync with live CLI help."
|
|
echo "Run: ./scripts/generate-cli-docs.sh ${BD_ARG:-}"
|
|
diff -u "$PROJECT_ROOT/docs/CLI_REFERENCE.md" "$TMP_OUTPUT_DIR/docs/CLI_REFERENCE.md" | sed -n '1,120p' || true
|
|
exit 1
|
|
fi
|
|
|
|
check_dirs=("website/docs/cli-reference")
|
|
if [ -n "$VERSIONED_VERSION" ]; then
|
|
check_dirs+=("website/versioned_docs/version-$VERSIONED_VERSION/cli-reference")
|
|
fi
|
|
|
|
for rel in "${check_dirs[@]}"; do
|
|
if [ -d "$PROJECT_ROOT/$rel" ]; then
|
|
if ! diff -qr "$PROJECT_ROOT/$rel" "$TMP_OUTPUT_DIR/$rel" >/dev/null; then
|
|
echo "FAIL: $rel is out of sync with live CLI help."
|
|
echo "Run: ./scripts/generate-cli-docs.sh ${BD_ARG:-}"
|
|
diff -ur "$PROJECT_ROOT/$rel" "$TMP_OUTPUT_DIR/$rel" | sed -n '1,160p' || true
|
|
exit 1
|
|
fi
|
|
fi
|
|
done
|
|
|
|
"$PROJECT_ROOT/scripts/generate-llms-full.sh" --check --source-root "$TMP_OUTPUT_DIR"
|
|
|
|
echo "PASS: generated CLI docs are fresh"
|
|
else
|
|
generate_all "$PROJECT_ROOT"
|
|
echo "Generated CLI docs from: $($BD version 2>/dev/null | head -1 || echo "$BD")"
|
|
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
|