1# Generating Markdown Docs For Your Own cobra.Command 2 3Generating man pages from a cobra command is incredibly easy. An example is as follows: 4 5```go 6package main 7 8import ( 9 "log" 10 11 "github.com/spf13/cobra" 12 "github.com/spf13/cobra/doc" 13) 14 15func main() { 16 cmd := &cobra.Command{ 17 Use: "test", 18 Short: "my test program", 19 } 20 err := doc.GenMarkdownTree(cmd, "/tmp") 21 if err != nil { 22 log.Fatal(err) 23 } 24} 25``` 26 27That will get you a Markdown document `/tmp/test.md` 28 29## Generate markdown docs for the entire command tree 30 31This program can actually generate docs for the kubectl command in the kubernetes project 32 33```go 34package main 35 36import ( 37 "log" 38 "io/ioutil" 39 "os" 40 41 "k8s.io/kubernetes/pkg/kubectl/cmd" 42 cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util" 43 44 "github.com/spf13/cobra/doc" 45) 46 47func main() { 48 kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard) 49 err := doc.GenMarkdownTree(kubectl, "./") 50 if err != nil { 51 log.Fatal(err) 52 } 53} 54``` 55 56This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./") 57 58## Generate markdown docs for a single command 59 60You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to `GenMarkdown` instead of `GenMarkdownTree` 61 62```go 63 out := new(bytes.Buffer) 64 err := doc.GenMarkdown(cmd, out) 65 if err != nil { 66 log.Fatal(err) 67 } 68``` 69 70This will write the markdown doc for ONLY "cmd" into the out, buffer. 71 72## Customize the output 73 74Both `GenMarkdown` and `GenMarkdownTree` have alternate versions with callbacks to get some control of the output: 75 76```go 77func GenMarkdownTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error { 78 //... 79} 80``` 81 82```go 83func GenMarkdownCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error { 84 //... 85} 86``` 87 88The `filePrepender` will prepend the return value given the full filepath to the rendered Markdown file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/): 89 90```go 91const fmTemplate = `--- 92date: %s 93title: "%s" 94slug: %s 95url: %s 96--- 97` 98 99filePrepender := func(filename string) string { 100 now := time.Now().Format(time.RFC3339) 101 name := filepath.Base(filename) 102 base := strings.TrimSuffix(name, path.Ext(name)) 103 url := "/commands/" + strings.ToLower(base) + "/" 104 return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url) 105} 106``` 107 108The `linkHandler` can be used to customize the rendered internal links to the commands, given a filename: 109 110```go 111linkHandler := func(name string) string { 112 base := strings.TrimSuffix(name, path.Ext(name)) 113 return "/commands/" + strings.ToLower(base) + "/" 114} 115``` 116