Repository navigation
Automate CLI / func docs generation #5285
Description
Activity
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?
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
knorfunc, 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.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
mainand 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@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).
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?
Metadata
Metadata
Labels
Type
Projects
- Status
- Status
Describe the change you'd like to see
The options for
knandfuncCLI 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
knand with @lance forfuncimplementation after KubeCon (Oct 2022).