Improve generation of reference docs#30
Open
adamwg wants to merge 2 commits into
Open
Conversation
Format our maturity level banners using markdown so that they look better in rendered help and generated docs. Omit the feature enablement notice in the top-level help when we generate docs, since it's not interesting on the docs website. Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
The crossplane/docs repository uses the vale tool to lint prose. It's a little overzealous sometimes, but overall helpful, and currently complains about a ton of issues in our help text. Fix as many issues as possible. Use a special spell check (to be introduced in the docs repo) to avoid complaints about lower-case `crossplane`, since it's the command name. The remaining issues we can't fix are: - 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>
📝 WalkthroughWalkthroughThis PR systematically refines CLI help text and documentation across 30+ commands, improves help generation to handle feature flags and Hugo formatting correctly, and switches feature-flag messaging to Markdown blockquotes. All changes are documentation and metadata focused; no behavioral logic is modified. ChangesCLI Help Text and Documentation Refinement
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 6✅ Passed checks (6 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (2)
cmd/crossplane/xrd/generate.go (1)
53-53: ⚡ Quick winClarify what
--pathis relative toCould we keep a bit more context in the help text here?
On Line 53,Output path.is pretty terse and doesn’t tell users this is within the project APIs layout.Suggested wording
- Path string `help:"Output path." optional:""` + Path string `help:"Output path within the project's APIs directory." optional:""`As per coding guidelines: "
**/cmd/**: Review CLI commands for proper flag handling, help text, and error messages. Ensure commands follow Crossplane CLI conventions."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@cmd/crossplane/xrd/generate.go` at line 53, The help text for the Path flag (struct field Path in generate.go) is too terse; update its `help` string to clearly state that the provided output path is relative to the project root and should point into the APIs layout (e.g., under the project's api/ or apis/ directory), e.g. "Output path relative to project root (destination within project APIs layout, e.g. api/ or apis/)." Ensure you only change the `help:"..."` value for the Path field.cmd/crossplane/function/help/generate.md (1)
2-3: 💤 Low valueConsider whether "idempotently" is clear for all users.
The term "idempotently" is technically precise but may not be familiar to all CLI users. Since this help text falls under
cmd/**, the coding guidelines emphasize user-friendliness and avoiding internal technical details.Would simpler phrasing like "adds the new function to the end of a Composition's pipeline (if not already present)" or "safely adds the new function" be clearer while still conveying the behavior?
That said, if "idempotently" is intentional and aligns with Crossplane terminology conventions, it's fine to keep—just wanted to check!
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@cmd/crossplane/function/help/generate.md` around lines 2 - 3, The help text uses the term "idempotently" which may be unclear to some users; replace that word in the generate help text where it says "idempotently adds the new function to end of a Composition's pipeline" with clearer wording such as "adds the new function to the end of a Composition's pipeline (if not already present)" or "safely adds the new function to the end of a Composition's pipeline" so the behavior is explicit and user-friendly.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@cmd/crossplane/docs.go`:
- Around line 237-242: The code currently closes the "hint" shortcode at EOF
using the bq flag but forgets to close an open table shortcode; update the EOF
handling in the same function that builds sb (where bq is used) to also check
the table-open flag (e.g., bt) and, if true, append the table close token "{{<
/table >}}\n" to sb before returning strings.TrimSpace(sb.String()), so any
trailing table row is properly terminated.
In `@cmd/crossplane/function/help/generate.md`:
- Line 3: Edit the sentence "adds the new function to end of a Composition's
pipeline when given a" to insert the missing article so it reads "adds the new
function to the end of a Composition's pipeline when given a" to correct the
grammar.
In `@cmd/crossplane/project/help/build.md`:
- Line 8: The Markdown text contains an extra space inside the inline code
backticks for the build command; locate the literal token "`build `" in the help
text (the sentence starting "The `build `command constructs...") and remove the
trailing space so it reads "`build`" (i.e., replace "`build `" with "`build`")
to fix the formatting.
- Line 5: Fix the typo in the project help text: replace the misspelled word
"packges" with "packages" in the sentence that mentions the `project push`
command (the line containing "The `project push` command can consume packges
from the"). Ensure only the spelling is corrected and punctuation/formatting
remains unchanged.
In `@cmd/crossplane/project/help/stop.md`:
- Line 8: Replace the incorrect command references 'up project run' and 'up
project stop' in the stop.md content with the correct commands 'crossplane
project run' and 'crossplane project stop' so the README/documentation
accurately reflects the CLI; locate the offending strings (e.g., "passed
`--registry-dir` to `up project run`, pass it to `up project stop` as") and
update them to use "crossplane project run" and "crossplane project stop".
In `@cmd/crossplane/trace/help/trace.md`:
- Around line 35-37: Fix the typo in the help text: change the phrase
"graph.Pipe to `dot` to" so there is a space after the period (i.e., "graph.
Pipe to `dot` to") in the string containing "Use `--output=dot` to print a
textual [Graphviz dot](https://graphviz.org/docs/layouts/dot/) graph.Pipe to
`dot` to render an image"; update that literal so the sentence separation is
correct.
---
Nitpick comments:
In `@cmd/crossplane/function/help/generate.md`:
- Around line 2-3: The help text uses the term "idempotently" which may be
unclear to some users; replace that word in the generate help text where it says
"idempotently adds the new function to end of a Composition's pipeline" with
clearer wording such as "adds the new function to the end of a Composition's
pipeline (if not already present)" or "safely adds the new function to the end
of a Composition's pipeline" so the behavior is explicit and user-friendly.
In `@cmd/crossplane/xrd/generate.go`:
- Line 53: The help text for the Path flag (struct field Path in generate.go) is
too terse; update its `help` string to clearly state that the provided output
path is relative to the project root and should point into the APIs layout
(e.g., under the project's api/ or apis/ directory), e.g. "Output path relative
to project root (destination within project APIs layout, e.g. api/ or apis/)."
Ensure you only change the `help:"..."` value for the Path field.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 397ae2e7-ea18-4121-bbb4-d3881e7e4f95
⛔ Files ignored due to path filters (1)
cmd/crossplane/docs-templates/command-reference.md.tmplis excluded by none and included by none
📒 Files selected for processing (48)
cmd/crossplane/composition/generate.gocmd/crossplane/composition/help/generate.mdcmd/crossplane/config/config.gocmd/crossplane/config/help/config.mdcmd/crossplane/config/set.gocmd/crossplane/convert/compositionenvironment/cmd.gocmd/crossplane/convert/compositionenvironment/help/composition-environment.mdcmd/crossplane/convert/help/convert.mdcmd/crossplane/dependency/add.gocmd/crossplane/dependency/help/add.mdcmd/crossplane/dependency/help/update-cache.mdcmd/crossplane/docs.gocmd/crossplane/function/help/generate.mdcmd/crossplane/main.gocmd/crossplane/project/help/build.mdcmd/crossplane/project/help/init.mdcmd/crossplane/project/help/push.mdcmd/crossplane/project/help/run.mdcmd/crossplane/project/help/stop.mdcmd/crossplane/project/push.gocmd/crossplane/project/run.gocmd/crossplane/render/engine.gocmd/crossplane/render/op/cmd.gocmd/crossplane/render/op/help/render.mdcmd/crossplane/render/xr/cmd.gocmd/crossplane/render/xr/help/render.mdcmd/crossplane/top/help/top.mdcmd/crossplane/trace/help/trace.mdcmd/crossplane/trace/trace.gocmd/crossplane/validate/cmd.gocmd/crossplane/validate/help/validate.mdcmd/crossplane/xpkg/batch.gocmd/crossplane/xpkg/build.gocmd/crossplane/xpkg/extract.gocmd/crossplane/xpkg/help/build.mdcmd/crossplane/xpkg/help/init.mdcmd/crossplane/xpkg/help/install.mdcmd/crossplane/xpkg/help/push.mdcmd/crossplane/xpkg/help/update.mdcmd/crossplane/xpkg/help/xpkg.mdcmd/crossplane/xpkg/init.gocmd/crossplane/xpkg/install.gocmd/crossplane/xpkg/update.gocmd/crossplane/xrd/convert.gocmd/crossplane/xrd/generate.gocmd/crossplane/xrd/help/convert.mdcmd/crossplane/xrd/help/generate.mdinternal/maturity/maturity.go
Comment on lines
+237
to
242
| // Close the "hint" box if it appeared at the very end of the detail. | ||
| if bq { | ||
| sb.WriteString("{{< /hint >}}\n") | ||
| } | ||
|
|
||
| return strings.TrimSpace(sb.String()) |
There was a problem hiding this comment.
Close table shortcode when detail ends with a table
Nice catch adding the EOF hint close. Could we also close the table shortcode at EOF?
Right now, if the last content line is a table row, the {{< /table >}} close tag is never emitted.
Proposed fix
// Close the "hint" box if it appeared at the very end of the detail.
if bq {
sb.WriteString("{{< /hint >}}\n")
}
+ // Close the table shortcode if detail ended with a table.
+ if table {
+ sb.WriteString("{{< /table >}}\n")
+ }
return strings.TrimSpace(sb.String())
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| // Close the "hint" box if it appeared at the very end of the detail. | |
| if bq { | |
| sb.WriteString("{{< /hint >}}\n") | |
| } | |
| return strings.TrimSpace(sb.String()) | |
| // Close the "hint" box if it appeared at the very end of the detail. | |
| if bq { | |
| sb.WriteString("{{< /hint >}}\n") | |
| } | |
| // Close the table shortcode if detail ended with a table. | |
| if table { | |
| sb.WriteString("{{< /table >}}\n") | |
| } | |
| return strings.TrimSpace(sb.String()) |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@cmd/crossplane/docs.go` around lines 237 - 242, The code currently closes the
"hint" shortcode at EOF using the bq flag but forgets to close an open table
shortcode; update the EOF handling in the same function that builds sb (where bq
is used) to also check the table-open flag (e.g., bt) and, if true, append the
table close token "{{< /table >}}\n" to sb before returning
strings.TrimSpace(sb.String()), so any trailing table row is properly
terminated.
| file is supplied, the new function is also idempotently added as a step to the | ||
| end of the Composition's pipeline. | ||
| language under the project's `functions/` directory. It optionally idempotently | ||
| adds the new function to end of a Composition's pipeline when given a |
There was a problem hiding this comment.
Add missing article for grammatical correctness.
Line 3 should read "to the end of a Composition's pipeline" rather than "to end of a Composition's pipeline."
✏️ Suggested fix
-adds the new function to end of a Composition's pipeline when given a
+adds the new function to the end of a Composition's pipeline when given a📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| adds the new function to end of a Composition's pipeline when given a | |
| adds the new function to the end of a Composition's pipeline when given a |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@cmd/crossplane/function/help/generate.md` at line 3, Edit the sentence "adds
the new function to end of a Composition's pipeline when given a" to insert the
missing article so it reads "adds the new function to the end of a Composition's
pipeline when given a" to correct the grammar.
| > specified when building and pushing a project. | ||
| ties everything together. The output of the build is a special `.xpkg` file | ||
| containing all the built packages, placed in the project's output directory | ||
| (`_output/` by default). The `project push` command can consume packges from the |
There was a problem hiding this comment.
Fix the typo: "packges" → "packages".
Line 5 contains a typo that was also flagged by the spell checker.
📝 Proposed fix
-(`_output/` by default). The `project push` command can consume packges from the
+(`_output/` by default). The `project push` command can consume packages from the📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| (`_output/` by default). The `project push` command can consume packges from the | |
| (`_output/` by default). The `project push` command can consume packages from the |
🧰 Tools
🪛 LanguageTool
[grammar] ~5-~5: Ensure spelling is correct
Context: ... The project push command can consume packges from the output file and push them to a...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@cmd/crossplane/project/help/build.md` at line 5, Fix the typo in the project
help text: replace the misspelled word "packges" with "packages" in the sentence
that mentions the `project push` command (the line containing "The `project
push` command can consume packges from the"). Ensure only the spelling is
corrected and punctuation/formatting remains unchanged.
| (`_output/` by default). The `project push` command can consume packges from the | ||
| output file and push them to an OCI registry. | ||
|
|
||
| The `build `command constructs the repository for the built Configuration from |
There was a problem hiding this comment.
Remove the extra space in the backtick formatting.
Line 8 has an extra space between "build" and the closing backtick: `build ` should be `build`.
📝 Proposed fix
-The `build `command constructs the repository for the built Configuration from
+The `build` command constructs the repository for the built Configuration from📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| The `build `command constructs the repository for the built Configuration from | |
| The `build` command constructs the repository for the built Configuration from |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@cmd/crossplane/project/help/build.md` at line 8, The Markdown text contains
an extra space inside the inline code backticks for the build command; locate
the literal token "`build `" in the help text (the sentence starting "The `build
`command constructs...") and remove the trailing space so it reads "`build`"
(i.e., replace "`build `" with "`build`") to fix the formatting.
| When run from a project directory, the `stop` command tears down the control | ||
| plane whose name matches the project name. When run outside a project directory, | ||
| pass `--control-plane-name` to identify the control plane to tear down. If you | ||
| passed `--registry-dir` to `up project run`, pass it to `up project stop` as |
There was a problem hiding this comment.
Correct the command references: "up project" → "crossplane project".
Line 8 references up project run and up project stop, but the correct command names are crossplane project run and crossplane project stop. This would confuse users trying to follow the documentation.
📝 Proposed fix
-passed `--registry-dir` to `up project run`, pass it to `up project stop` as
+passed `--registry-dir` to `crossplane project run`, pass it to `crossplane project stop` as📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| passed `--registry-dir` to `up project run`, pass it to `up project stop` as | |
| passed `--registry-dir` to `crossplane project run`, pass it to `crossplane project stop` as |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@cmd/crossplane/project/help/stop.md` at line 8, Replace the incorrect command
references 'up project run' and 'up project stop' in the stop.md content with
the correct commands 'crossplane project run' and 'crossplane project stop' so
the README/documentation accurately reflects the CLI; locate the offending
strings (e.g., "passed `--registry-dir` to `up project run`, pass it to `up
project stop` as") and update them to use "crossplane project run" and
"crossplane project stop".
Comment on lines
+35
to
+37
| Use `--output=dot` to print a textual | ||
| [Graphviz dot](https://graphviz.org/docs/layouts/dot/) graph.Pipe to `dot` to | ||
| render an image: |
There was a problem hiding this comment.
Missing space after period.
There's a typo on line 36: "graph.Pipe to" should be "graph. Pipe to" (space after the period).
✏️ Proposed fix
Use `--output=dot` to print a textual
-[Graphviz dot](https://graphviz.org/docs/layouts/dot/) graph.Pipe to `dot` to
+[Graphviz dot](https://graphviz.org/docs/layouts/dot/) graph. Pipe to `dot` to
render an image:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@cmd/crossplane/trace/help/trace.md` around lines 35 - 37, Fix the typo in the
help text: change the phrase "graph.Pipe to `dot` to" so there is a space after
the period (i.e., "graph. Pipe to `dot` to") in the string containing "Use
`--output=dot` to print a textual [Graphviz
dot](https://graphviz.org/docs/layouts/dot/) graph.Pipe to `dot` to render an
image"; update that literal so the sentence separation is correct.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description of your changes
The crossplane/docs repository uses the vale tool to lint prose. It's a overzealous sometimes, but overall helpful, and currently complains about a ton of issues in our help text.
Fix as many issues as possible. Use a special spell check (to be introduced in the docs repo) to avoid complaints about lower-case
crossplane, since it's the command name.The remaining issues we can't fix are:
configin thecrossplane configcommand.k8sin the flag help forcrossplane dependency add.adminincluster-adminin the help forcrossplane project run.To address some of the vale issues, and make the output look better, format our maturity level banners using markdown. Omit the feature enablement notice in the top-level help when we generate docs, since it's not interesting on the docs website.
I have:
./nix.sh flake checkto ensure this PR is ready for review.- [ ] Added or updated unit tests.- [ ] Linked a PR or a docs tracking issue to document this change.backport release-x.ylabels to auto-backport this PR.