mirror of
https://github.com/spf13/cobra
synced 2024-07-03 00:51:39 +00:00
eb5040e69e
This code was already using io.Writer, but was completely ignoring write errors. The most worrying part is how GenMarkdownTreeCustom used an unnecessary buffer to then dump all of its contents on a file, and instead of returning an error on file creation/writing, it would just exit the entire program.
82 lines
2.2 KiB
Markdown
82 lines
2.2 KiB
Markdown
# Generating Markdown Docs For Your Own cobra.Command
|
|
|
|
## Generate markdown docs for the entire command tree
|
|
|
|
This program can actually generate docs for the kubectl command in the kubernetes project
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"io/ioutil"
|
|
"os"
|
|
|
|
"github.com/GoogleCloudPlatform/kubernetes/pkg/kubectl/cmd"
|
|
"github.com/spf13/cobra/cobra"
|
|
)
|
|
|
|
func main() {
|
|
kubectl := cmd.NewFactory(nil).NewKubectlCommand(os.Stdin, ioutil.Discard, ioutil.Discard)
|
|
doc.GenMarkdownTree(kubectl, "./")
|
|
}
|
|
```
|
|
|
|
This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")
|
|
|
|
## Generate markdown docs for a single command
|
|
|
|
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 `GenMarkdown` instead of `GenMarkdownTree`
|
|
|
|
```go
|
|
out := new(bytes.Buffer)
|
|
doc.GenMarkdown(cmd, out)
|
|
```
|
|
|
|
This will write the markdown doc for ONLY "cmd" into the out, buffer.
|
|
|
|
## Customize the output
|
|
|
|
Both `GenMarkdown` and `GenMarkdownTree` have alternate versions with callbacks to get some control of the output:
|
|
|
|
```go
|
|
func GenMarkdownTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error {
|
|
//...
|
|
}
|
|
```
|
|
|
|
```go
|
|
func GenMarkdownCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error {
|
|
//...
|
|
}
|
|
```
|
|
|
|
The `filePrepender` will prepend the return value given the full filepath to the rendered Markdown file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/):
|
|
|
|
```go
|
|
const fmTemplate = `---
|
|
date: %s
|
|
title: "%s"
|
|
slug: %s
|
|
url: %s
|
|
---
|
|
`
|
|
|
|
filePrepender := func(filename string) string {
|
|
now := time.Now().Format(time.RFC3339)
|
|
name := filepath.Base(filename)
|
|
base := strings.TrimSuffix(name, path.Ext(name))
|
|
url := "/commands/" + strings.ToLower(base) + "/"
|
|
return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url)
|
|
}
|
|
```
|
|
|
|
The `linkHandler` can be used to customize the rendered internal links to the commands, given a filename:
|
|
|
|
```go
|
|
linkHandler := func(name string) string {
|
|
base := strings.TrimSuffix(name, path.Ext(name))
|
|
return "/commands/" + strings.ToLower(base) + "/"
|
|
}
|
|
```
|
|
|