[doc] Add support for taking in text/templates for generating docs

[jamietanna]

As well as the excellent support we've got built-in for rendering documentation, it'd be handy to be able to further customise the output.

For instance, I'd quite like to add additional metadata to the pages, or i.e. use it in a .mdx file that can have other more complex setup around it, in a way that isn't as straightforward within the built-in means.

Although I could hand-roll this, it'd be quite convenient to have it as a first-class citizen for upstream consumption, but if you feel it's not worthwhile, that's cool too.

I've hacked together a repository in https://gitlab.com/tanna.dev/cobra-doc-template which has somewhat reverse-engineered the way that the existing Markdown docs work.

I have also created https://gist.github.com/jamietanna/020c15bbe5e6b258391fa3ded9861e38 which shows:

• the relevant main.go
• and a given template

This then produces a tree of Markdown-formatted docs, which are (effectively) identical to those rendered by Cobra's doc.GenMarkdownTreeCustom.

Note a few key differences:

• This takes efforts to work around Deprecated commands do not have documentation generated #2032, as it'd be handy to generate docs for deprecated
• This generates docs + a notice for commands that are deprecated
• Some slight whitespace inconsistencies in the rendered output (not a big deal!)

The code is Apache-2.0 licensed - as with Cobra - and I'd be happy to work to get this contributed upstream if you're interested!

[indrora]

I was just going to begin implementing this myself, but from the point of turning the Yaml docs into "Just another output":

• Half the work has already been done in Yaml docs
• text/template is a good option, as is html/template for those who don't mind.
• Moving the man page generation to this would also be good
• Making the backing structure behind the yaml output visible means more people can do more things with it.
• Having json or similar output would be nice, too.