1# Generating Yaml Docs For Your Own cobra.Command 2 3Generating yaml files 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.GenYamlTree(cmd, "/tmp") 21 if err != nil { 22 log.Fatal(err) 23 } 24} 25``` 26 27That will get you a Yaml document `/tmp/test.yaml` 28 29## Generate yaml 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 "io/ioutil" 38 "log" 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.GenYamlTree(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 yaml 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 `GenYaml` instead of `GenYamlTree` 61 62```go 63 out := new(bytes.Buffer) 64 doc.GenYaml(cmd, out) 65``` 66 67This will write the yaml doc for ONLY "cmd" into the out, buffer. 68 69## Customize the output 70 71Both `GenYaml` and `GenYamlTree` have alternate versions with callbacks to get some control of the output: 72 73```go 74func GenYamlTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error { 75 //... 76} 77``` 78 79```go 80func GenYamlCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error { 81 //... 82} 83``` 84 85The `filePrepender` will prepend the return value given the full filepath to the rendered Yaml file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/): 86 87```go 88const fmTemplate = `--- 89date: %s 90title: "%s" 91slug: %s 92url: %s 93--- 94` 95 96filePrepender := func(filename string) string { 97 now := time.Now().Format(time.RFC3339) 98 name := filepath.Base(filename) 99 base := strings.TrimSuffix(name, path.Ext(name)) 100 url := "/commands/" + strings.ToLower(base) + "/" 101 return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url) 102} 103``` 104 105The `linkHandler` can be used to customize the rendered internal links to the commands, given a filename: 106 107```go 108linkHandler := func(name string) string { 109 base := strings.TrimSuffix(name, path.Ext(name)) 110 return "/commands/" + strings.ToLower(base) + "/" 111} 112``` 113