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.
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.
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.
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.