SWI-11010 Add Cobra Doc Gen

.github/workflows/release.yml

@@ -61,6 +61,27 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  dispatch-docsite:
+    needs: [release]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Mint app token for api-specs
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ secrets.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          owner: Bandwidth
+          repositories: api-specs
+
+      - name: Trigger docsite CLI reference update
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          gh api repos/Bandwidth/api-specs/dispatches \
+            -f event_type=cli-docs-update \
+            -F client_payload[version]="${{ github.ref_name }}"
+
   bump-formula:
     needs: [release]
     runs-on: ubuntu-latest

.goreleaser.yml

@@ -1,5 +1,10 @@
 version: 2
 
+before:
+  hooks:
+    - go run ./internal/tools/docgen -out ./dist-docs
+    - tar -czf cli-docs.tar.gz -C ./dist-docs .
+
 builds:
   - main: ./cmd/band
     binary: band
@@ -25,6 +30,11 @@ archives:
 checksum:
   name_template: "checksums.txt"
 
+release:
+  # Attach docs to the GitHub release
+  extra_files:
+    - glob: ./cli-docs.tar.gz
+
 dockers:
   - image_templates:
       - "ghcr.io/bandwidth/cli:{{ .Version }}-amd64"

cmd/band/main.go

@@ -1,3 +1,18 @@
+// Command band is the official Bandwidth CLI for managing voice, messaging,
+// numbers, and more from the command line.
+//
+// It lets you build and debug voice applications, send messages, manage phone
+// numbers, and control calls without leaving your terminal. Global flags like
+// --plain give flat JSON output, create commands support --if-not-exists for
+// safe retries, and long-running operations support --wait, so it works equally
+// well interactively and from scripts or AI agents.
+//
+// Install with Homebrew (brew install Bandwidth/tap/band) or go install
+// (go install github.com/Bandwidth/cli/cmd/band@latest), then run "band --help"
+// to get started.
+//
+// For the full command reference and guides, see https://dev.bandwidth.com and
+// the project README at https://github.com/Bandwidth/cli.
 package main
 
 import (

cmd/root.go

@@ -1,3 +1,5 @@
+// Package cmd defines the band CLI's cobra command tree: the root command and
+// every subcommand for voice, messaging, numbers, sub-accounts, and more.
 package cmd
 
 import (
@@ -118,6 +120,10 @@ var versionCmd = &cobra.Command{
 	},
 }
 
+func Root() *cobra.Command {
+	return rootCmd
+}
+
 func Execute() error {
 	api.Version = version
 	return rootCmd.Execute()

go.mod

@@ -13,6 +13,7 @@ require (
 
 require (
 	github.com/alessio/shellescape v1.4.1 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect
 	github.com/danieljoos/wincred v1.2.0 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/godbus/dbus/v5 v5.1.0 // indirect
@@ -21,7 +22,9 @@ require (
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-runewidth v0.0.9 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/stretchr/testify v1.9.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -2,6 +2,7 @@ github.com/alessio/shellescape v1.4.1 h1:V7yhSDDn8LP4lc4jS8pFkt0zCnzVJlG5JXy9BVK
 github.com/alessio/shellescape v1.4.1/go.mod h1:PZAiSCk0LJaZkiCSkPv8qIobYglO3FPpyFjDCtHLS30=
 github.com/briandowns/spinner v1.23.2 h1:Zc6ecUnI+YzLmJniCfDNaMbW0Wid1d5+qcTq4L2FW8w=
 github.com/briandowns/spinner v1.23.2/go.mod h1:LaZeM4wm2Ywy6vO571mvhQNRcWfRUnXOs0RcKV0wYKM=
+github.com/cpuguy83/go-md2man/v2 v2.0.4 h1:wfIWP927BUkWJb2NmU/kNDYIBTh/ziUX91+lVfRxZq4=
 github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/danieljoos/wincred v1.2.0 h1:ozqKHaLK0W/ii4KVbbvluM91W2H3Sh0BncbUNPS7jLE=
 github.com/danieljoos/wincred v1.2.0/go.mod h1:FzQLLMKBFdvu+osBrnFODiv32YGwCfx0SkRa/eYHgec=
@@ -23,6 +24,7 @@ github.com/olekukonko/tablewriter v0.0.5 h1:P2Ga83D34wi1o9J6Wh1mRuqd4mF/x/lgBS7N
 github.com/olekukonko/tablewriter v0.0.5/go.mod h1:hPp6KlRPjbx+hW8ykQs1w3UBbZlj6HuIJcUGPhkA7kY=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM=
 github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y=
@@ -39,6 +41,7 @@ golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
 golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
 golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/tools/docgen/main.go

@@ -0,0 +1,58 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/Bandwidth/cli/cmd"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	out := flag.String("out", "./docs/cli", "output directory")
+	format := flag.String("format", "markdown", "markdown|man|rest")
+	front := flag.Bool("frontmatter", false, "prepend simple YAML front matter to markdown")
+	flag.Parse()
+
+	if err := os.MkdirAll(*out, 0o755); err != nil {
+		log.Fatal(err)
+	}
+
+	root := cmd.Root()
+	root.DisableAutoGenTag = true // stable, reproducible files (no timestamp footer)
+
+	switch *format {
+	case "markdown":
+		if *front {
+			prep := func(filename string) string {
+				base := filepath.Base(filename)
+				name := strings.TrimSuffix(base, filepath.Ext(base))
+				title := strings.ReplaceAll(name, "_", " ")
+				return fmt.Sprintf("---\ntitle: %q\nslug: %q\ndescription: \"CLI reference for %s\"\n---\n\n", title, name, title)
+			}
+			link := func(name string) string { return strings.ToLower(name) }
+			if err := doc.GenMarkdownTreeCustom(root, *out, prep, link); err != nil {
+				log.Fatal(err)
+			}
+		} else {
+			if err := doc.GenMarkdownTree(root, *out); err != nil {
+				log.Fatal(err)
+			}
+		}
+	case "man":
+		hdr := &doc.GenManHeader{Title: strings.ToUpper(root.Name()), Section: "1"}
+		if err := doc.GenManTree(root, hdr, *out); err != nil {
+			log.Fatal(err)
+		}
+	case "rest":
+		if err := doc.GenReSTTree(root, *out); err != nil {
+			log.Fatal(err)
+		}
+	default:
+		log.Fatalf("unknown format: %s", *format)
+	}
+}