flagforge

flagforge allows you to automatically generate Go flag code, as well as the associated Markdown and HTML documentation for those flags, all using a single configuration file. This means you only have to define your command-line options once in a TOML file, and flagforge will do the rest.

Running flagforge

Clone the repo and execute go build. Pass -h to flagforge to learn how to use it.

flagforge -f go|markdown|html <TOML file>

Pass -p <file> to copy the contents of a file to the output before the generated content. This is how a generated documentation page keeps hand-written material -- front matter, an introduction -- that would otherwise be lost every time the page is regenerated.

Grouping flags into sections

Give a flag an optional section key and the generated Markdown and HTML documentation will group flags under a heading of that name:

[[flags]]
name = "HTTPAddr"
cli = "http-addr"
type = "string"
default = "localhost:4001"
short_help = "HTTP server bind address"
section = "HTTP API"

Sections appear in the order they first appear in the TOML file, and a flag joins a section that has already appeared rather than opening a new one, so flags belonging to the same section need not be adjacent. If any flag declares a section then every flag must; a partially sectioned file is an error, since otherwise each newly added flag would silently collect in an unnamed group.

section affects documentation only -- the generated Go code is unchanged by it.

The HTML output is a fragment rather than a complete document, so that it can be embedded in a page that supplies its own styling. Each table carries the class rq-flags, and section headings are emitted as Markdown ## headings so that a static site generator gives them anchors and a table-of-contents entry.

Example usage

rqlite uses flagforge to generate the code and documentation for its extensive set of command-line flags:

• rqlite TOML file
• Generated Go code for command-line flag parsing, and then calling the generated code from rqlite.
• Example of automatically generated HTML documentation for the flags deployed to production site. You can review the generated HTML here.