[doc] Add support for taking in `text/template`s for generating docs
jamietanna opened this issue · 1 comments
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 #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!
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 ishtml/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.