Debian Codegraph @

site/content/docgen/rest.md

raw
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 ```