cobraman

README

Generating Documentation For Your cobra.Command

This is a replacement for the man generator used by spf13/cobra. The code in spf13/cobra/doc has different generators that hard-code what gets output for man pages, markdown, etc. It also calls a lot of other 3rd party libraries. This package uses the Go template facility to generate documentation. It is much more powerful and flexible thus giving a lot more control over the format and style of documentation you would like to generate.

Here is a simple example to get you started:

package main

import (
	"log"

	"github.com/spf13/cobra"
	"github.com/rjohnson/cobraman"
)

func main() {
	cmd := &cobra.Command{
		Use:   "dofoo",
		Short: "my dofoo program",
	}
	manOpts := &man.CobraManOptions{
		LeftFooter:  "Dofoo " + version,
		Author:      "Foo Bar <foo@bar.com>",
		Directory:   "/tmp",
		Bugs:        `Bugs related to cobra-man can be filed at https://github.com/rjohnson/cobraman`,
	}
	err := man.GenerateManPages(cmd.Root(), manOpts)
	if err != nil {
		log.Fatal(err)
	}
}

That will get you a man page /tmp/dofoo.1

GoDoc has the full API documentation here. Be sure to checkout the documentation for CobraManOptions as it provides many options to control the output.

There is also an example directory with a simple dummy application that shows some of the features of this package. See the README.

Annotations

This library uses the Annotations fields cobra.Cmd and pFlag to give some hints for the generation of the documentation.

The following annotations on the cobra.Command object provides a way to provide content for additional sections in the man page. The first three override the global Options in case you want some of these sections only on some command man pages.

• man-files-section
• man-bugs-section
• man-environment-section
• man-examples-section

The man-examples-section is a way to override the content of the cmd.Examples field. This is paticularly useful if you want to provide raw Troff code to make it look a bit better.

Here is an example of how you can set the annotations on the command:

	annotations := make(map[string]string)
	annotations["man-files-section"] = "We use lots of files!"
	cmd.Annotations = annotations

In addition, there is an annotation you can put on individual flags:

• man-arg-hints

This provides a way to give a short description to the value expected by an flag. This is used by the built-in template in the OPTIONS section. For example, setting the annotation like this:

	annotation := []string{"path"}
	flags.SetAnnotation("file", "man-arg-hints", annotation)

Will generate a option description like this:

-f, --file = <path>

Templates

Cobra Man uses Go templates to generate the documentation. You can replace the template used by setting the TemplateName variable in CobraManOptions. A couple of templates are defined that can be used out of the box. They include:

• "troff" - which generates a man page with basic troff macros
• "mdoc" - which generates a man page using the mdoc macro package
• "markdown" - which generates a page using Markdown

But, of course, you can provide your own template if you like for maximum power!

See Writing your own template for more information.

Documentation

Overview

Package cobraman is a library for generating documentation out of a command line structure created by the github.com/spf13/cobra library.

Index

• Variables
• func AddTemplateFunc(name string, tmplFunc interface{})
• func AddTemplateFuncs(tmplFuncs template.FuncMap)
• func GenerateDocs(cmd *cobra.Command, opts *Options, directory string, templateName string) (err error)
• func GenerateOnePage(cmd *cobra.Command, opts *Options, templateName string, w io.Writer) error
• func RegisterTemplate(name string, separator string, extension string, templateString string)
• type DocGenTool
  • func CreateDocGenCmdLineTool(appCmd *cobra.Command) *DocGenTool
  • func (dg *DocGenTool) AddBashCompletionGenerator(fileName string) *DocGenTool
  • func (dg *DocGenTool) AddDocGenerator(opts *Options, templateName string) *DocGenTool
  • func (dg *DocGenTool) Execute() error
• type Options

Variables

var ErrMissingCommandName = errors.New("you need a command name to have a man page")

ErrMissingCommandName is returned with no command is provided.

Functions

func AddTemplateFunc

func AddTemplateFunc(name string, tmplFunc interface{})

AddTemplateFunc adds a template function that's available to doc templates.

func AddTemplateFuncs

func AddTemplateFuncs(tmplFuncs template.FuncMap)

AddTemplateFuncs adds multiple template functions that are available to doc templates.

func GenerateDocs

func GenerateDocs(cmd *cobra.Command, opts *Options, directory string, templateName string) (err error)

GenerateDocs - build man pages for the passed in cobra.Command and all of its children.

func GenerateOnePage

func GenerateOnePage(cmd *cobra.Command, opts *Options, templateName string, w io.Writer) error

GenerateOnePage will generate one documentation page and output the result to w TODO: document use of this function in README.

func RegisterTemplate

func RegisterTemplate(name string, separator string, extension string, templateString string)

RegisterTemplate takes a template string creates a template for use with CobraMan. It also takes a separator and file extension to be used when generating the file names for the generated files.

Types

type DocGenTool

type DocGenTool struct {
	// contains filtered or unexported fields
}

DocGenTool is an opaque type created by CreateDocGenCmdLineTool.

func CreateDocGenCmdLineTool

func CreateDocGenCmdLineTool(appCmd *cobra.Command) *DocGenTool

CreateDocGenCmdLineTool creates a command line parser that can be used in a utility tool to generate documentation for a companion application.

func (*DocGenTool) AddBashCompletionGenerator

func (dg *DocGenTool) AddBashCompletionGenerator(fileName string) *DocGenTool

AddBashCompletionGenerator will create a subcommand for the utility tool that will generate a Bash Completion file for the companion app. It will support a --directory flag and use the fileName passed into this function.

func (*DocGenTool) AddDocGenerator

func (dg *DocGenTool) AddDocGenerator(opts *Options, templateName string) *DocGenTool

AddDocGenerator will create a subcommand for the utility tool that will generate documentation with the passed in Options and templateName. It supports a --directory flag for where to place the generated files. The subcommand will be named generate-<templateName> where templateName is the same as the template used to generate the documentation.

func (*DocGenTool) Execute

func (dg *DocGenTool) Execute() error

Execute will parse args and execute the command line.

type Options

type Options struct {
	// What section to generate the pages 4 (1 is the default if not set)
	Section string

	// CenterFooter used across all pages (defaults to current month and year)
	// If you just want to set the date used in the center footer use Date
	CenterFooter string

	// If you just want to set the date used in the center footer use Date
	// Will default to Now
	Date *time.Time

	// LeftFooter used across all pages
	LeftFooter string

	// CenterHeader used across all pages
	CenterHeader string

	// Files if set with content will create a FILES section for all
	// pages.  If you want this section only for a single command add
	// it as an annotation: cmd.Annotations["man-files-section"]
	// The field will be sanitized for troff output. However, if
	// it starts with a '.' we assume it is valid troff and pass it through.
	Files string

	// Bugs if set with content will create a BUGS section for all
	// pages.  If you want this section only for a single command add
	// it as an annotation: cmd.Annotations["man-bugs-section"]
	// The field will be sanitized for troff output. However, if
	// it starts with a '.' we assume it is valid troff and pass it through.
	Bugs string

	// Environment if set with content will create a ENVIRONMENT section for all
	// pages.  If you want this section only for a single command add
	// it as an annotation: cmd.Annotations["man-environment-section"]
	// The field will be sanitized for troff output. However, if
	// it starts with a '.' we assume it is valid troff and pass it through.
	Environment string

	// Author if set will create a Author section with this content.
	Author string

	// CustomData allows passing custom data into the template
	CustomData map[string]interface{}
	// contains filtered or unexported fields
}

Options is used configure how GenerateManPages will do its job.