Automate CLI / func docs generation

[abrennan89]

Describe the change you'd like to see
The options for kn and func CLI commands are constantly being expanded and updated.
It is not reasonable for docs to be manually updated frequently enough to keep up with the changes.
I would like to see folks on the eng team provide some method of implementation for auto-generating docs reference pages for the CLI tools that can be published on the website.

Additional context
Previously discussed with @rhuss for kn and with @lance for func implementation after KubeCon (Oct 2022).

[psschwei]

Also some discussion in #4430

[abrennan89]

Thanks @psschwei - it looks like some work was done on this but the previous issue was marked closed without it being really implemented; any idea why?

[psschwei]

Looks we decided on a WG call to just go with a link to the client repo. I vaguely recall running into some issues trying to automate moving the docs over here, but don't remember exactly what they were.

[abrennan89]

I think the biggest issue with just having a link is that it doesn't allow us to retain different versions of the docs for different versions of kn or func, which is something that I'd like to see, but maybe adds additional complications here since I don't think the versions were considered in previous discussions.

[lance]

I do like being able to refer to documentation by version, but using github doesn't prevent that. The docs are published with each change on main and with release branches, we can point to the docs per release by just linking to the branch. E.g. https://github.com/knative/func/blob/release-1.7/docs/reference/func.md for 1.7

[abrennan89]

@lance presumably we'd have to have some sort of script in the docs then to keep that link updated for each release though, or manually update it (IMO not an option, we already have issues with maintaining stuff like this accurately).

[abrennan89]

The other issue IMHO is that using Github for docs isn't a very nice UX experience, but I guess that's not as urgent, especially while our sample docs still live there. I'd just prefer if long term we had a view to introduce more consistency in the docs experience, e.g. API ref docs are generated and included in the site, so why can't CLI, samples, etc be the same?