Kong Go CLI manual pages
I’m using Kong the CLI argument parser to create manual pages from the arguments and help described in the Kong structure that tells your CLI how to parse its command line.
With a lot of use from the reflect
package (this was before I discovered kong actually has an API
you can use), I’m creating manual pages from the kong CLI definition, while having great fun with
parsing enum
, default
and other tags to make the manual page really readable.
I.e. I’ve got something like this:
List x.List `cmd:"" aliases:"ls" help:"ListX - list X details" description:"List details about x."
This gets parsed and help is used in the Name
section, description is used for the …
description. Synopsis too.
NAME
ListX - list X details
SYNOPSIS
ListX [OPTION] XX
DESCRIPTION
List details about x.
The options are also parsed like this and everything is put in a Go template that outputs markdown, this also means you can use markdown syntax in the help string.
{{name -}}
{{synopsis -}}
{{description -}}
{{arguments -}}
{{options -}}
Which gets then converted to a manual page using mmark:
p := parser.NewWithExtensions(parser.FencedCode | parser.DefinitionLists)
p.Opts = parser.Options{
ParserHook: func(data []byte) (ast.Node, []byte, int) { return mparser.Hook(data) },
Flags: parser.FlagsNone,
}
doc := markdown.Parse(b.Bytes(), p)
renderer := man.NewRenderer(man.RendererOptions{})
x := markdown.Render(doc, renderer)
return string(x)
It’s amazingly liberating to just write you option parsing and get all this sutff for free!
I’m also generation completions from this in the same way and making bash completion using https://github.com/miekg/gompletely.
I might even productionize this and use Kong’s proper API and publish a kong-man and kong-completion package.