vendor/github.com/spf13/cobra/doc/rest_docs.md

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