Generating ReStructured Text Docs For Your Own cobra.Command

从 cobra 命令生成 rest 手册非常容易。下面一个例子: 

  1. package main
  3. import (
  4.     "log"
  6.     "github.com/spf13/cobra"
  7.     "github.com/spf13/cobra/doc"
  8. )
  10. func main() {
  11.     cmd := &cobra.Command{
  12.         Use:   "test",
  13.         Short: "my test program",
  14.     }
  15.     err := doc.GenReSTTree(cmd, "/tmp")
  16.     if err != nil {
  17.         log.Fatal(err)
  18.     }
  19. }

这将为你提供一个 rest 手册 /tmp/test.rst

Generate ReST docs for the entire command tree

该程序实际上可以为kubernetes项目中的kubectl命令生成文档

  1. package main
  3. import (
  4.     "log"
  5.     "io/ioutil"
  6.     "os"
  8.     "k8s.io/kubernetes/pkg/kubectl/cmd"
  9.     cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
  11.     "github.com/spf13/cobra/doc"
  12. )
  14. func main() {
  15.     kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
  16.     err := doc.GenReSTTree(kubectl, "./")
  17.     if err != nil {
  18.         log.Fatal(err)
  19.     }
  20. }

这将生成一系列文件，一个用于树中的每个命令，在指定的目录中（在本例中为./）

Generate ReST docs for a single command

你可能希望更多地控制输出，或仅生成单个命令，而不是整个命令树。如果是这种情况，你可能更喜欢GenReST而不是GenReSTTree

  1.     out := new(bytes.Buffer)
  2.     err := doc.GenReST(cmd, out)
  3.     if err != nil {
  4.         log.Fatal(err)
  5.     }

这会将只有cmd的ReST文档写入输出缓冲区。

Customize the output

GenReST和GenReSTTree都有备用版本，带有回调以控制输出:

  1. func GenReSTTreeCustom(cmd *Command, dir string, filePrepender func(string) string, linkHandler func(string, string) string) error {
  2.     //...
  3. }
  1. func GenReSTCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string, string) string) error {
  2.     //...
  3. }

filePrepender将在给定完整文件路径的情况下将返回值添加到呈现的 ReST 文件中。一个常见的用例是添加前端内容，使用Hugo生成的文档:

  1. const fmTemplate = `---
  2. date: %s
  3. title: "%s"
  4. slug: %s
  5. url: %s
  6. ---
  7. `
  8. filePrepender := func(filename string) string {
  9.     now := time.Now().Format(time.RFC3339)
  10.     name := filepath.Base(filename)
  11.     base := strings.TrimSuffix(name, path.Ext(name))
  12.     url := "/commands/" + strings.ToLower(base) + "/"
  13.     return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url)
  14. }

在给定命令名和参考的情况下，linkHandler可用于自定义命令的呈现链接。这在将rst转换为html或使用Sphinx等工具生成文档时非常有用，其中使用了:ref::

  1. // Sphinx cross-referencing format
  2. linkHandler := func(name, ref string) string {
  3.     return fmt.Sprintf(":ref:`%s <%s>`", name, ref)
  4. }