feat: CLI docs auto-generation with bd help --doc/--list/--all#2527
Closed
maphew wants to merge 5 commits intogastownhall:mainfrom
Closed
feat: CLI docs auto-generation with bd help --doc/--list/--all#2527maphew wants to merge 5 commits intogastownhall:mainfrom
maphew wants to merge 5 commits intogastownhall:mainfrom
Conversation
Add three new flags to the help command: - bd help --list: lists all available commands (one per line) - bd help --doc <command>: generates individual markdown with Docusaurus frontmatter - bd help --all: combined reference document Infrastructure: - scripts/generate-cli-docs.sh: automates doc generation for all commands - CI job check-cli-docs-freshness: validates generated docs match live CLI - Pre-commit hook: warns if CLI docs may be stale Fixes gofmt alignment in sidebarPositionMap. Fixes broken CI xargs redirect (replaced with while-read loop). Amp-Thread-ID: https://ampcode.com/threads/T-019cde93-fbf9-7229-931c-805d79001f80 Co-authored-by: Amp <amp@ampcode.com>
Generated by ./scripts/generate-cli-docs.sh using bd help --doc. - 95 individual command docs in website/docs/cli-reference/ - Combined reference in docs/CLI_REFERENCE.md - Deleted 6 stale docs for removed commands (dependencies, essential, index, issues, labels, sync) Amp-Thread-ID: https://ampcode.com/threads/T-019cde93-fbf9-7229-931c-805d79001f80 Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019cde55-544a-701a-a0e2-c06dee329d6a Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019cde7b-9f7b-7327-8322-119d0d89d026 Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019cdf39-de43-7743-a475-ab0c26327596 Co-authored-by: Amp <amp@ampcode.com>
Collaborator
|
Thanks for tackling doc drift -- it is a real problem and your PR #2526 (which we just merged) addresses the cleanup side well. For this PR, we are cherry-picking the bd help --list/--doc/--all Go code -- those flags are useful for scripting and doc generation. We are leaving behind the 95 committed generated docs and the CI freshness checking though. Generated output belongs in a build pipeline, not committed to the repo. Committing it means every help-text change requires regenerating and committing docs, which is ongoing maintenance burden. We will get the Go code landed separately with attribution. Thanks for the thorough work on both PRs! |
steveyegge
added a commit
that referenced
this pull request
Mar 12, 2026
…H#2527) Cherry-pick Go code from community PR #2527 (maphew): adds --list flag to enumerate all commands, --doc flag to generate per-command Docusaurus markdown, and sidebar position mapping. Also includes lazy getGitContext() in hooks dir resolution and test skip improvements for missing Dolt server. Co-authored-by: matt wilkie <maphew@users.noreply.github.com> Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds three new flags to
bd helpthat generate documentation directly from the live Cobra command tree, eliminating documentation drift at the source.New Flags
bd help --list— Lists all 95 available commands (one per line), used by scriptsbd help --doc <command>— Generates individual markdown with Docusaurus frontmatterbd help --all— Combined reference document for all commandsInfrastructure
scripts/generate-cli-docs.sh— Automates doc generation for all commandscheck-cli-docs-freshness— Validates generated docs match live CLI output on every PRFixes from Review
sidebarPositionMap(tab → space normalization)xargs -I{} ... > /tmp/cli-docs/{}.mdwrote everything to literal{}.md). Replaced with proper while-read loop.Commit Structure
feat: add CLI docs auto-generation— Go code, scripts, CI configdocs: regenerate CLI reference— Generated markdown output (95 command docs + combined reference)Related
check-doc-flags.sh(PR fix(docs): purge stale command/flag refs + add CI doc validation (GH#2522) #2526) which validates against known-removed commands/flags