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