From 7a6a7f58da142dcf647bcdc3817d033514f098f2 Mon Sep 17 00:00:00 2001 From: ckoegel Date: Wed, 24 Jun 2026 14:19:50 -0400 Subject: [PATCH] SWI-11010 Add Cobra Doc Gen --- cmd/root.go | 4 +++ go.mod | 3 ++ go.sum | 3 ++ internal/tools/docgen/main.go | 58 +++++++++++++++++++++++++++++++++++ 4 files changed, 68 insertions(+) create mode 100644 internal/tools/docgen/main.go diff --git a/cmd/root.go b/cmd/root.go index 1ca0552..791a8ab 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -118,6 +118,10 @@ var versionCmd = &cobra.Command{ }, } +func Root() *cobra.Command { + return rootCmd +} + func Execute() error { api.Version = version return rootCmd.Execute() diff --git a/go.mod b/go.mod index aec1cd3..bd0cd0b 100644 --- a/go.mod +++ b/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 ) diff --git a/go.sum b/go.sum index e858449..32fcd5c 100644 --- a/go.sum +++ b/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= diff --git a/internal/tools/docgen/main.go b/internal/tools/docgen/main.go new file mode 100644 index 0000000..3629cfe --- /dev/null +++ b/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) + } +}