Update CLI reference docs for v2.3.0#1097
Conversation
Use the new `crossplane generate-docs` command to generate CLI reference docs from the built-in CLI help. Update both `master` and `v2.3`, since they're the same for now. Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
✅ Deploy Preview for crossplane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
jbw976
left a comment
jbw976
left a comment
There was a problem hiding this comment.
there are a couple funny headings that are rendering odd, e.g. https://deploy-preview-1097--crossplane.netlify.app/v2.3/cli/command-reference/#read-the-xrd-from-stdin
are those at the right level? are they supposed to be headings? 🤔
Good catch - we missed properly converting the help for |
I've updated the CLI's docs generator locally to fix as many vale issues as possible and re-generated the docs using it. There are still a few issues we can't fix because of how our docs generation works: - The abbreviation `config` in the `crossplane config` command. - The abbreviation `k8s` in the flag help for `crossplane dependency add`. - The abbreviation `admin` in `cluster-admin` in the help for `crossplane project run`. Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
|
I've fixed as many vale issues as possible while still auto-generating docs. See crossplane/cli#30 for details. |
|
amazing @adamwg, great work at tackling most all of the vale issues! do you think it would be possible (or reasonable) to include exclusions in the CLI docs templates where needed for the specifically failing Vale styles, e.g. |
I thought about doing this, but since the remaining issues are in text that comes from the kong command/argument tags rather than markdown-formatted text, I think we would have to add these exclusions for the entire document, rather than scoped around the specific instances we want to ignore. I also looked at whether we could ignore only specific matches, but couldn't make it work - not sure if our version of vale doesn't support that, or if the checks/styles we're using don't support it. If we could ignore I'm inclined to accept the existing issues, since they should only get flagged when we update the CLI docs. But, I would definitely prefer to have vale return a clean status if we can figure out a way to do it. |
Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
With the latest version of vale, we can specify ignores with arbitrary specificity, e.g., ignoring a single word from a list of forbidden words. This lets us add some targeted ignores to our CLI reference where we can't easily avoid breaking certain rules (e.g., because the command name is a forbidden word). Update the version of vale we use in CI and add targeted ignores output by the latest iteration of the CLI's `generate-docs` command. Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
|
I put some more time into this today and figured out how to ignore specific matches (does require a newer vale version). I've updated this PR with the output, and crossplane/cli#30 to include (a) the ability to disable a specific check for a specific command, and (b) a CI job that generates docs and runs vale with the config from this repo, so that we ensure no new issues creep in. |
2 participants
Use the new
crossplane generate-docscommand to generate CLI reference docs from the built-in CLI help. Update bothmasterandv2.3, since they're the same for now.Toward #1092