Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Automate CLI / func docs generation #5285

Open
abrennan89 opened this issue Oct 19, 2022 · 7 comments
Open

Automate CLI / func docs generation #5285

abrennan89 opened this issue Oct 19, 2022 · 7 comments
Assignees
Labels
kind/cli kind/functions kind/site-improvements lifecycle/frozen Indicates that an issue or PR should not be auto-closed due to staleness. priority/critical triage/needs-eng-implementation triage/needs-eng-input Engineering input is requested

Comments

@abrennan89
Copy link
Contributor

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).

@abrennan89 abrennan89 added triage/needs-eng-input Engineering input is requested priority/critical kind/cli lifecycle/frozen Indicates that an issue or PR should not be auto-closed due to staleness. kind/functions triage/needs-eng-implementation kind/site-improvements labels Oct 19, 2022
@abrennan89 abrennan89 moved this to Backlog in Client Planning Oct 19, 2022
@abrennan89 abrennan89 moved this to In design in Docs WG Roadmap Oct 19, 2022
@abrennan89 abrennan89 moved this from In design to Ready to work in Docs WG Roadmap Oct 19, 2022
@psschwei
Copy link
Contributor

Also some discussion in #4430

@abrennan89
Copy link
Contributor Author

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
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Member

lance commented Oct 25, 2022

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
Copy link
Contributor Author

@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
Copy link
Contributor Author

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?

@psschwei psschwei removed their assignment Dec 12, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind/cli kind/functions kind/site-improvements lifecycle/frozen Indicates that an issue or PR should not be auto-closed due to staleness. priority/critical triage/needs-eng-implementation triage/needs-eng-input Engineering input is requested
Projects
Status: Backlog
Status: Ready to work
Development

No branches or pull requests

4 participants