cobradoc

README

cobradoc

Alternative documentation generator for golang Cobra.

Highlights

• Supports markdown and manpage (troff) formats
• Supports command groups
• Generates single page for the whole command tree

Reference

API reference is available on pkg.go.dev.

Example

_example directory demonstrates usage of this package.

It contains:

• example cobra tool
• generated manual page
• generated markdown

Usage

Generate markdown page:

import "github.com/gavv/cobradoc"

err := cobradoc.WriteDocument(os.Stdout, rootCmd, cobradoc.Markdown, cobradoc.Options{
	Name:             "my-tool",
	Header:           "My page header",
	ShortDescription: "My tool description",
})
if err != nil {
	panic(err)
}

Generate manual page:

import "github.com/gavv/cobradoc"

err := cobradoc.WriteDocument(os.Stdout, rootCmd, cobradoc.Troff, cobradoc.Options{
	Name:             "my-tool",
	Header:           "My page header",
	ShortDescription: "My tool description",
	ExtraSections: []cobradoc.ExtraSection{
		{
   			Title: cobradoc.BUGS,
			Text:  "Please report bugs via GitHub",
		},
	},
})
if err != nil {
    panic(err)
}

Credits

This package is inspired by cobraman by Ray Johnson, but uses single-page approach and adds support for command groups.

Authors

See here.

License

MIT

Documentation

Overview

Package cobradoc implements alternative documentation generator for cobra.

Index

• Constants
• func GetDocument(cmd *cobra.Command, fmt Format, opts Options) (string, error)
• func WriteDocument(w io.Writer, cmd *cobra.Command, fmt Format, opts Options) error
• type ExtraSection
• type Format
• type Options

Constants

const (
	EXAMPLES    = "Examples"
	FILES       = "Files"
	ENVIRONMENT = "Environment"
	BUGS        = "Reporting Bugs"
	AUTHORS     = "Authors"
	COPYRIGHT   = "Copyright"
	LICENSE     = "License"
	HISTORY     = "History"
	SEEALSO     = "See Also"
	NOTES       = "Notes"
)

Common titles for extra sections Section title can be any string, however these ones are used frequently

Functions

func GetDocument

func GetDocument(cmd *cobra.Command, fmt Format, opts Options) (string, error)

Generate single documentation page for given command tree

func WriteDocument

func WriteDocument(w io.Writer, cmd *cobra.Command, fmt Format, opts Options) error

Generate single documentation page for given command tree

Types

type ExtraSection

type ExtraSection struct {
	// Section title
	Title string

	// Section text
	Text string
}

Extra section contents

type Format

type Format int

Output format

const (
	// Troff format (for manual page)
	Troff Format = iota

	// Markdown format
	Markdown Format = iota
)

type Options

type Options struct {
	// Page section number (defaults to "1")
	// In man page, defines manual page section number
	// In markdown, ignored
	SectionNumber string

	// Name of the tool (defaults to cmd.Name())
	// Used in numerous places
	Name string

	// Creation date (defaults to current month and year)
	// In man page, located at the center of the bottom line
	// In markdown, ignored
	Date string

	// BCP 47 language for converting the tool name to title case (defaults to "en")
	Language string

	// Page header (defaults to "{Name} Manual")
	// In man page, located at the center of the top line
	// In markdown, defines page header
	Header string

	// Page footer (defaults to "{Name} Manual")
	// In man page, located at the left corner of the bottom line
	// In markdown, ignored
	Footer string

	// Short description of the tool (defaults to cmd.Short)
	// In man page, located in NAME section
	// In markdown, located in the first section, used if LongDescription is unset
	ShortDescription string

	// Long description of the tool (defaults to cmd.Long)
	// In man page, located in DESCRIPTION section
	// In markdown, located in the first section
	LongDescription string

	// Array of additional sections (optional)
	// Sections are added to the end of the document
	ExtraSections []ExtraSection
}

Generation options All fields have reasonable defaults