| 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" |
| 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, io.Discard, io.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](https://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 |
``` |