...

Text file src/github.com/spf13/cobra/site/content/docgen/yaml.md

Documentation: github.com/spf13/cobra/site/content/docgen

     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](https://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```

View as plain text