All you need to know about cobra commands. Generate documentation in a variety of formats, similar to what's available in Cobra but with some simplifications and fixes.
- Documentation output for Markdown, YAML, JSON, reStructuredText
- Customizable YAML and JSON marshaling
- User-defined templating for Markdown and reStructuredText
- Manpage support
go get -u github.com/jimschubert/venom
Venom can be used either to add a documentation command as a child to another command, or to perform ad hoc writes of documentation directly.
The options, constructed via venom.NewOptions()
, are the same for both use cases. These options follow the builder pattern to make available options easily discoverable.
All defined formats will be generated into the output directory, which defaults to docs
and is configurable.
First, initialize venom.NewOptions()
.
Next, initialize venom by passing your root command the above options. For example:
func init() {
opts := venom.NewOptions().
WithFormats(venom.Yaml | venom.Json | venom.Markdown).
WithShowHiddenCommands()
cobra.CheckErr(venom.Initialize(rootCmd, opts))
}
Here is a full example of generating only markdown:
package main
import (
"github.com/jimschubert/venom"
"github.com/spf13/cobra"
)
var rootCmd = &cobra.Command{
Use: "example",
Short: "root command",
RunE: func(cmd *cobra.Command, args []string) error {
return cmd.Help()
},
}
func init() {
rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
opts := venom.NewOptions().WithFormats(venom.Markdown)
cobra.CheckErr(venom.Initialize(rootCmd, opts))
}
func main() {
rootCmd.Execute()
}
If you compile and run this application, you won't see a docs
command because it's hidden. Invoke the hidden command (e.g. example docs
) to output the documentation.
The docs
subcommand which venom creates will allow the user to specify a subset of the allowed formats, to define a new output directory, and to show all hidden commands.
Usage:
example docs [flags]
Flags:
--formats strings A comma-separated list of formats to output. Allowed: [yaml,markdown] (default [yaml,markdown])
-h, --help help for docs
--out-dir string The target output directory (default "docs")
--show-hidden Also show hidden commands
Suppose you want to wire this functionality up into an existing documentation command, or maybe you want to generate on
build via a go generator utility command. You can do this by invoking the Write
command directly.
For example:
docs := venom.NewDocumentation(rootCmd, venom.NewOptions().WithFormats(venom.Markdown))
if err := venom.Write(docs)); err != nil {
// do something with err
}
You can provide your own templates if the built-in templates don't suit your needs. The built-in templates are intended to match as closely as possible with those output by Cobra's built-in command. But, there are cases where these aren't desirable. For instance:
- markdown-driven doc sites like Docusaurus generate first-level headers if missing in markdown
- you want front-matter for an extended markdown system like Jekyll
- you want to do something unexpected like output Asciidoc by tweaking the Markdown templates
- you simply don't like the formatting
To provide custom templates, you just need to make sure your files are named exactly the same as they are under ./templates in this repository.
Then, pass an implementation of fs.FS
to our options. You can use go embed to read an entire directory called your_directory
like this:
//go:embed your_directory/*.tmpl
var templates embed.FS
func init() {
opts := venom.NewOptions().WithCustomTemplates(templates)
cobra.CheckErr(venom.Initialize(rootCmd, opts))
}
And as long as you have both markdown_command.tmpl
and markdown_index.tmpl
defined under your_directory
, you're all set!
The types definitions which are bound to these templates can be found in ./types.go.
Command templates will be bound to a data structure matching:
struct {
Command
Doc Documentation
}
The embedded Command
allows you to interact with the command's fields directly at the top level of the template. The Doc
field is the full documentation, providing you access to the root command and all child commands.
Index templates will be bound to the Documentation
structure directly.
NOTE Not all output formats are template driven. Be sure to review ./templates.
go test -v -race -cover ./...
This project is licensed under Apache 2.0.