* docs: generate CLI reference from live help * docs(cli): move bd version stamp from per-command pages to index only Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on every per-command CLI reference page (writeSingleCommandDoc) and the docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now lives only on the index page emitted by scripts/generate-cli-docs.sh: - Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md): labelled "Latest" - Versioned snapshots (website/versioned_docs/version-X.Y.Z/...): labelled with the explicit semver tag parsed from the directory name This eliminates the 100+-file no-signal diff a release version bump otherwise produces, restoring the "regen as a separate small commit" workflow PR #3704 enables. After this change a version bump alone yields zero diff on the dev tree; only the new versioned snapshot created at release-cut time carries the new tag. No datestamps are introduced anywhere — scripts/generate-cli-docs.sh --check remains deterministic across CI runs. Refs: mybd-afb, PR #3704 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: CI Bot <ci@beads.test> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
374 lines
9.8 KiB
Go
374 lines
9.8 KiB
Go
package main
|
|
|
|
import (
|
|
"errors"
|
|
"fmt"
|
|
"io"
|
|
"os"
|
|
"sort"
|
|
"strings"
|
|
"unicode"
|
|
|
|
"github.com/spf13/cobra"
|
|
)
|
|
|
|
// helpAllFlag is the --all flag for the help command
|
|
var helpAllFlag bool
|
|
|
|
// helpDocFlag is the --doc flag for generating single command docs
|
|
var helpDocFlag string
|
|
|
|
// helpListFlag is the --list flag for listing available commands
|
|
var helpListFlag bool
|
|
|
|
// registerHelpAllFlag adds the --all, --doc, and --list flags to Cobra's auto-generated help command.
|
|
// Must be called after rootCmd.InitDefaultHelpCmd() has run (i.e., after first Execute
|
|
// or explicit init). We hook it in init() after all subcommands are registered.
|
|
func registerHelpAllFlag() {
|
|
// Cobra lazily creates the help command. We need to find it.
|
|
for _, cmd := range rootCmd.Commands() {
|
|
if cmd.Name() == "help" {
|
|
if cmd.Flags().Lookup("all") != nil {
|
|
return
|
|
}
|
|
cmd.Flags().BoolVar(&helpAllFlag, "all", false, "Show help for all commands in a single document")
|
|
cmd.Flags().StringVar(&helpDocFlag, "doc", "", "Generate markdown docs for a single command")
|
|
cmd.Flags().BoolVar(&helpListFlag, "list", false, "List all available commands")
|
|
|
|
// Wrap the existing Run to check --all, --doc, and --list first
|
|
originalRun := cmd.Run
|
|
cmd.Run = func(cmd *cobra.Command, args []string) {
|
|
if helpListFlag {
|
|
// Handle --list flag: list all available commands
|
|
listAllCommands(os.Stdout, rootCmd)
|
|
return
|
|
}
|
|
if helpDocFlag != "" {
|
|
// Handle --doc flag: generate single command docs
|
|
cmdPath := helpDocFlag
|
|
if len(args) > 0 {
|
|
cmdPath = strings.Join(append([]string{helpDocFlag}, args...), " ")
|
|
}
|
|
if err := writeSingleCommandDoc(os.Stdout, rootCmd, cmdPath); err != nil {
|
|
fmt.Fprintln(os.Stderr, err)
|
|
fmt.Fprintf(os.Stderr, "Available commands: %s\n", strings.Join(availableCommandNames(rootCmd), " "))
|
|
os.Exit(1)
|
|
}
|
|
return
|
|
}
|
|
if helpAllFlag {
|
|
writeAllHelp(os.Stdout, rootCmd)
|
|
return
|
|
}
|
|
if originalRun != nil {
|
|
originalRun(cmd, args)
|
|
}
|
|
}
|
|
return
|
|
}
|
|
}
|
|
}
|
|
|
|
// writeAllHelp writes a complete markdown reference for all commands,
|
|
// generated from the live Cobra command tree.
|
|
func writeAllHelp(w io.Writer, root *cobra.Command) {
|
|
fmt.Fprintf(w, "# bd — Complete Command Reference\n\n")
|
|
fmt.Fprintf(w, "Reference for bd Latest. Generated from `bd help --all`.\n\n")
|
|
|
|
// Collect commands grouped by their GroupID
|
|
type group struct {
|
|
title string
|
|
commands []*cobra.Command
|
|
}
|
|
|
|
// Build ordered group list from root's groups
|
|
groups := root.Groups()
|
|
groupMap := make(map[string]*group, len(groups))
|
|
var orderedGroups []*group
|
|
for _, g := range groups {
|
|
grp := &group{title: g.Title}
|
|
groupMap[g.ID] = grp
|
|
orderedGroups = append(orderedGroups, grp)
|
|
}
|
|
|
|
// Ungrouped commands (if any)
|
|
var ungrouped []*group
|
|
|
|
for _, cmd := range root.Commands() {
|
|
if !cmd.IsAvailableCommand() && cmd.Name() != "help" {
|
|
continue
|
|
}
|
|
if gid := cmd.GroupID; gid != "" {
|
|
if grp, ok := groupMap[gid]; ok {
|
|
grp.commands = append(grp.commands, cmd)
|
|
}
|
|
} else {
|
|
// Ungrouped
|
|
if len(ungrouped) == 0 {
|
|
ungrouped = append(ungrouped, &group{title: "Other Commands:"})
|
|
}
|
|
ungrouped[0].commands = append(ungrouped[0].commands, cmd)
|
|
}
|
|
}
|
|
|
|
// Table of contents
|
|
fmt.Fprintf(w, "## Table of Contents\n\n")
|
|
allGroups := append(orderedGroups, ungrouped...)
|
|
for _, grp := range allGroups {
|
|
if len(grp.commands) == 0 {
|
|
continue
|
|
}
|
|
fmt.Fprintf(w, "### %s\n\n", grp.title)
|
|
for _, cmd := range grp.commands {
|
|
anchor := "bd-" + strings.ReplaceAll(cmd.Name(), "-", "-")
|
|
fmt.Fprintf(w, "- [bd %s](#%s) — %s\n", cmd.Name(), anchor, escapeMDXText(cmd.Short))
|
|
// Include subcommands in TOC
|
|
for _, sub := range cmd.Commands() {
|
|
if !sub.IsAvailableCommand() {
|
|
continue
|
|
}
|
|
subAnchor := "bd-" + cmd.Name() + "-" + strings.ReplaceAll(sub.Name(), "-", "-")
|
|
fmt.Fprintf(w, " - [bd %s %s](#%s) — %s\n", cmd.Name(), sub.Name(), subAnchor, escapeMDXText(sub.Short))
|
|
}
|
|
}
|
|
fmt.Fprintf(w, "\n")
|
|
}
|
|
|
|
// Global flags (once)
|
|
fmt.Fprintf(w, "---\n\n## Global Flags\n\n")
|
|
fmt.Fprintf(w, "These flags apply to all commands:\n\n")
|
|
fmt.Fprintf(w, "```\n")
|
|
fmt.Fprintf(w, "%s", root.PersistentFlags().FlagUsages())
|
|
fmt.Fprintf(w, "```\n\n")
|
|
|
|
// Command details
|
|
fmt.Fprintf(w, "---\n\n")
|
|
for _, grp := range allGroups {
|
|
if len(grp.commands) == 0 {
|
|
continue
|
|
}
|
|
fmt.Fprintf(w, "## %s\n\n", grp.title)
|
|
for _, cmd := range grp.commands {
|
|
writeCommandHelp(w, cmd, "bd", 3)
|
|
}
|
|
}
|
|
}
|
|
|
|
// writeCommandHelp writes markdown help for a single command and its subcommands.
|
|
func writeCommandHelp(w io.Writer, cmd *cobra.Command, parentPath string, depth int) {
|
|
fullPath := parentPath + " " + cmd.Name()
|
|
heading := strings.Repeat("#", depth)
|
|
|
|
fmt.Fprintf(w, "%s %s\n\n", heading, fullPath)
|
|
|
|
// Description
|
|
if cmd.Long != "" {
|
|
fmt.Fprintf(w, "%s\n\n", escapeMDXText(cmd.Long))
|
|
} else if cmd.Short != "" {
|
|
fmt.Fprintf(w, "%s\n\n", escapeMDXText(cmd.Short))
|
|
}
|
|
|
|
// Usage
|
|
fmt.Fprintf(w, "```\n%s\n```\n\n", strings.TrimRight(cmd.UseLine(), " "))
|
|
|
|
// Aliases
|
|
if len(cmd.Aliases) > 0 {
|
|
fmt.Fprintf(w, "**Aliases:** %s\n\n", strings.Join(cmd.Aliases, ", "))
|
|
}
|
|
|
|
// Examples
|
|
if cmd.Example != "" {
|
|
fmt.Fprintf(w, "**Examples:**\n\n```bash\n%s\n```\n\n", cmd.Example)
|
|
}
|
|
|
|
// Local flags (not inherited/global)
|
|
localFlags := cmd.NonInheritedFlags()
|
|
if localFlags.HasFlags() {
|
|
fmt.Fprintf(w, "**Flags:**\n\n```\n%s```\n\n", localFlags.FlagUsages())
|
|
}
|
|
|
|
// Subcommands
|
|
subCmds := cmd.Commands()
|
|
hasVisibleSubs := false
|
|
for _, sub := range subCmds {
|
|
if sub.IsAvailableCommand() {
|
|
hasVisibleSubs = true
|
|
break
|
|
}
|
|
}
|
|
|
|
if hasVisibleSubs {
|
|
for _, sub := range subCmds {
|
|
if !sub.IsAvailableCommand() {
|
|
continue
|
|
}
|
|
writeCommandHelp(w, sub, fullPath, depth+1)
|
|
}
|
|
}
|
|
}
|
|
|
|
// sidebarPositionMap maps command names to their Docusaurus sidebar position
|
|
// This controls the ordering of commands in the website sidebar.
|
|
var sidebarPositionMap = map[string]int{
|
|
"create": 10,
|
|
"list": 20,
|
|
"ready": 30,
|
|
"show": 40,
|
|
"update": 50,
|
|
"close": 60,
|
|
"delete": 70,
|
|
"reopen": 80,
|
|
"dep": 100,
|
|
"label": 110,
|
|
"state": 120,
|
|
"sync": 200,
|
|
"import": 210,
|
|
"export": 220,
|
|
"mol": 300,
|
|
"formula": 310,
|
|
"init": 400,
|
|
"setup": 410,
|
|
"config": 420,
|
|
"prime": 500,
|
|
"doctor": 600,
|
|
"admin": 610,
|
|
"migrate": 620,
|
|
}
|
|
|
|
// writeSingleCommandDoc generates markdown documentation for a single command
|
|
// with Docusaurus frontmatter for website integration.
|
|
func writeSingleCommandDoc(w io.Writer, root *cobra.Command, cmdName string) error {
|
|
// Find the command (handle nested commands like "mol pour")
|
|
cmd := findCommand(root, cmdName)
|
|
if cmd == nil {
|
|
return fmt.Errorf("Error: command not found: %s", cmdName)
|
|
}
|
|
|
|
docCommand := strings.TrimSpace(strings.TrimPrefix(commandPath(cmd), root.Name()))
|
|
docCommand = strings.TrimSpace(docCommand)
|
|
if docCommand == "" {
|
|
return errors.New("Error: cannot generate docs for root command")
|
|
}
|
|
docID := commandDocID(docCommand)
|
|
|
|
// Get sidebar position (default to 999 if not in map)
|
|
position := 999
|
|
if pos, ok := sidebarPositionMap[docCommand]; ok {
|
|
position = pos
|
|
}
|
|
|
|
// Generate Docusaurus frontmatter
|
|
fmt.Fprintf(w, "---\n")
|
|
fmt.Fprintf(w, "id: %s\n", docID)
|
|
fmt.Fprintf(w, "title: bd %s\n", docCommand)
|
|
fmt.Fprintf(w, "slug: /cli-reference/%s\n", docID)
|
|
fmt.Fprintf(w, "sidebar_position: %d\n", position)
|
|
fmt.Fprintf(w, "---\n")
|
|
fmt.Fprintf(w, "\n")
|
|
fmt.Fprintf(w, "<!-- AUTO-GENERATED: do not edit manually -->\n")
|
|
fmt.Fprintf(w, "Generated from `bd help --doc %s`\n\n", docCommand)
|
|
|
|
// Generate the command help (using h2 for single command)
|
|
parentPath := strings.TrimSuffix(commandPath(cmd), " "+cmd.Name())
|
|
writeCommandHelp(w, cmd, parentPath, 2)
|
|
return nil
|
|
}
|
|
|
|
// findCommand finds a command by name in the command tree.
|
|
// Supports nested commands like "mol pour" by splitting on space.
|
|
func findCommand(root *cobra.Command, name string) *cobra.Command {
|
|
// Handle nested commands (e.g., "mol pour")
|
|
parts := strings.Split(name, " ")
|
|
|
|
var current *cobra.Command
|
|
for i, part := range parts {
|
|
if i == 0 {
|
|
// Start from root's direct commands
|
|
current = findDirectCommand(root, part)
|
|
} else {
|
|
// Look in subcommands of current
|
|
if current != nil {
|
|
current = findDirectCommand(current, part)
|
|
}
|
|
}
|
|
if current == nil {
|
|
return nil
|
|
}
|
|
}
|
|
return current
|
|
}
|
|
|
|
// findDirectCommand finds a direct child command by name.
|
|
func findDirectCommand(parent *cobra.Command, name string) *cobra.Command {
|
|
for _, cmd := range parent.Commands() {
|
|
if cmd.Name() == name {
|
|
return cmd
|
|
}
|
|
// Also check aliases
|
|
for _, alias := range cmd.Aliases {
|
|
if alias == name {
|
|
return cmd
|
|
}
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// listAllCommands prints all available commands, one per line.
|
|
// Used by the generate-cli-docs.sh script.
|
|
func listAllCommands(w io.Writer, root *cobra.Command) {
|
|
for _, name := range availableCommandNames(root) {
|
|
fmt.Fprintln(w, name)
|
|
}
|
|
}
|
|
|
|
func availableCommandNames(root *cobra.Command) []string {
|
|
names := make([]string, 0, len(root.Commands()))
|
|
for _, cmd := range root.Commands() {
|
|
if cmd.IsAvailableCommand() {
|
|
names = append(names, cmd.Name())
|
|
}
|
|
}
|
|
sort.Strings(names)
|
|
return names
|
|
}
|
|
|
|
func commandPath(cmd *cobra.Command) string {
|
|
path := cmd.CommandPath()
|
|
if path == "" {
|
|
return cmd.Name()
|
|
}
|
|
return path
|
|
}
|
|
|
|
func commandDocID(commandPath string) string {
|
|
var b strings.Builder
|
|
lastDash := false
|
|
for _, r := range strings.ToLower(commandPath) {
|
|
if unicode.IsLetter(r) || unicode.IsDigit(r) {
|
|
b.WriteRune(r)
|
|
lastDash = false
|
|
continue
|
|
}
|
|
if !lastDash {
|
|
b.WriteByte('-')
|
|
lastDash = true
|
|
}
|
|
}
|
|
id := strings.Trim(b.String(), "-")
|
|
if id == "" {
|
|
return "command"
|
|
}
|
|
return id
|
|
}
|
|
|
|
func escapeMDXText(s string) string {
|
|
replacer := strings.NewReplacer(
|
|
"&", "&",
|
|
"<", "<",
|
|
">", ">",
|
|
"{", "{",
|
|
"}", "}",
|
|
)
|
|
return replacer.Replace(s)
|
|
}
|