Format detailed help using markdown and auto-generate reference docs#14
Open
adamwg wants to merge 2 commits into
Open
Format detailed help using markdown and auto-generate reference docs#14adamwg wants to merge 2 commits into
adamwg wants to merge 2 commits into
Conversation
Use the glamour library to render detailed help text using markdown. This makes it more ergonomic to write extensive help text and gives us lots of flexibility in how it's formatted. Define custom light and dark stylesheets based on glamour's defaults, using Crossplane brand colors for common elements. Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
Add `crossplane generate-docs`, which generates a markdown file following the format of the existing CLI reference page in crossplane/docs. The generated file includes full help (summary, details, flags, etc.) for all commands. Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
📝 WalkthroughWalkthroughThis PR externalizes hard-coded command help text into embedded Markdown files and implements a custom Kong help printer with terminal-aware styling. A hidden docs generator subcommand produces a command-reference.md from the command tree. ChangesHelp Text Externalization and Markdown Rendering
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 6✅ Passed checks (6 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
cmd/crossplane/xpkg/help/xpkg.md (1)
12-12:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove or clarify the stray "12" on line 12.
Line 12 contains only the text "12", which appears to be a stray artifact or line number. This should either be removed or replaced with valid content if something is missing.
📝 Proposed fix
See [the Crossplane packages documentation](https://docs.crossplane.io/latest/concepts/packages) for more information. -12As per coding guidelines: Ensure Markdown files follow proper structure and are helpful for users.
🤖 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/xpkg/help/xpkg.md` at line 12, Remove the stray "12" text found on line 12 of xpkg.md (the orphaned numeric artifact) — either delete that line entirely or replace it with the intended heading/content if something was accidentally removed; ensure the resulting Markdown has valid structure and reads correctly for the xpkg help page.
🧹 Nitpick comments (2)
cmd/crossplane/trace/help/trace.md (1)
42-42: 💤 Low valueConsider wrapping this shell command to comply with the 100-column guideline.
This line exceeds 100 characters. As per coding guidelines, Markdown files should wrap at 100 columns (longer lines are only allowed for links to improve readability).
You could wrap it with a backslash continuation:
crossplane resource trace cluster.aws.platformref.upbound.io \ platform-ref-aws -o dot | dot -Tpng -o graph.pngHowever, I recognize there's a trade-off here — single-line shell commands are easier to copy-paste. If you feel the copy-paste convenience outweighs strict guideline compliance for this example, that's understandable. What's your preference?
🤖 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` at line 42, The example shell command in the trace.md code block exceeds the 100-column guideline; update the code block to wrap the long command (the line containing "crossplane resource trace cluster.aws.platformref.upbound.io platform-ref-aws -o dot | dot -Tpng -o graph.png") using a shell continuation (backslash) or by breaking before the pipe into two indented lines so the rendered Markdown stays within 100 columns while preserving exact command semantics for copy-paste.cmd/crossplane/render/op/help/render.md (1)
1-12: ⚡ Quick winCould we confirm top-level heading behavior for this help page?
Really nice intro section. Quick check: does the help renderer inject the command title automatically? If not,
adding an H1 would make heading structure clearer for direct Markdown consumption.As per coding guidelines, "Check for proper heading structure, clear language, and that documentation is
helpful for users."🤖 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/render/op/help/render.md` around lines 1 - 12, Confirm whether the help renderer auto-injects the command title for the "operation render" help page; if it does not, add a top-level H1 (e.g., "operation render" or "Operation Render") at the start of cmd/crossplane/render/op/help/render.md so the document has a clear heading hierarchy; update the file header and run the help renderer locally to verify the final rendered output includes a single top-level heading and that downstream tooling still formats the page correctly.
🤖 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/convert/compositionenvironment/help/composition-environment.md`:
- Around line 16-17: Update the example command invocations that incorrectly
include an extra "composition" token: replace every occurrence of the string
"crossplane composition convert composition-environment" with the correct
"crossplane convert composition-environment" in the composition-environment.md
examples (the three examples that show piping, stdout and
--function-environment-configs-ref usage); ensure the changed command appears
consistently in the examples that currently read "cat composition.yaml |
crossplane composition convert composition-environment" and in the two multiline
examples that begin with "crossplane composition convert composition-environment
composition.yaml \".
- Around line 1-2: The description text currently uses the incorrect command
name "composition convert composition-environment"; update that phrase to the
correct command name "crossplane convert composition-environment" (or simply
"convert composition-environment" in context) wherever it appears in the README
text to accurately reflect the CLI invocation for converting a Composition to
use function-environment-configs.
In `@cmd/crossplane/convert/help/convert.md`:
- Around line 1-2: Update the description to correctly reference the command
name and avoid confusion: change the sentence that currently says "The
`composition convert` command" so it either says "The `crossplane convert`
command converts a Crossplane composition..." or "The `convert` command converts
a Crossplane composition..." (keeping "composition" as the object, not part of
the command name). Edit the sentence in convert.md so the command identifier is
`crossplane convert` or `convert` and the rest of the sentence clarifies it
operates on compositions.
In `@cmd/crossplane/help.go`:
- Around line 244-248: newHelpWriter currently ignores the error returned by
term.GetSize which can yield wrapWidth==0 and break wrapping; modify the call in
newHelpWriter to capture the error from term.GetSize and provide a sensible
fallback (e.g., 80) when GetSize returns an error or width==0, then apply
min(wrapWidth, 120) as before so downstream calls like doc.ToText receive a
valid positive width.
In `@cmd/crossplane/render/op/help/render.md`:
- Around line 19-25: The table rows for annotation keys (e.g.,
render.crossplane.io/runtime, render.crossplane.io/runtime-development-target,
render.crossplane.io/runtime-docker-cleanup,
render.crossplane.io/runtime-docker-name,
render.crossplane.io/runtime-docker-pull-policy,
render.crossplane.io/runtime-docker-publish-address,
render.crossplane.io/runtime-docker-target) exceed 100 columns; reflow those
entries so no source line is longer than 100 chars by either converting each
table row to wrapped bullet points or splitting long cell content into multiple
shorter sentences/lines, ensuring each annotation key stays present and its
description is wrapped to <=100 columns while preserving the meaning and
examples (like localhost:9443, dns:///example.org:7443, 0.0.0.0,
Always/Never/IfNotPresent).
In `@cmd/crossplane/xpkg/help/install.md`:
- Around line 49-53: The long shell command in the install example exceeds 100
columns; update the example in install.md so the command is split with a
backslash continuation: put "crossplane xpkg install provider" on the first line
and break the package identifier onto the next indented line with the backslash
(preserving the "--wait=1m" flag at the end), matching the proposed fix style so
the block stays within the 100-column guideline.
In `@internal/style/style.go`:
- Around line 33-36: RenderMarkdown currently calls term.GetSize and passes
wrapWidth directly to glamour.WithWordWrap, but if term.GetSize fails wrapWidth
can be 0 which breaks wrapping; update RenderMarkdown to check the returned
wrapWidth from term.GetSize (in function RenderMarkdown) and if it's <= 0 or an
error occurred, set a sensible fallback (e.g. 80 or 120) before calling
glamour.WithWordWrap so word wrapping never receives 0.
---
Outside diff comments:
In `@cmd/crossplane/xpkg/help/xpkg.md`:
- Line 12: Remove the stray "12" text found on line 12 of xpkg.md (the orphaned
numeric artifact) — either delete that line entirely or replace it with the
intended heading/content if something was accidentally removed; ensure the
resulting Markdown has valid structure and reads correctly for the xpkg help
page.
---
Nitpick comments:
In `@cmd/crossplane/render/op/help/render.md`:
- Around line 1-12: Confirm whether the help renderer auto-injects the command
title for the "operation render" help page; if it does not, add a top-level H1
(e.g., "operation render" or "Operation Render") at the start of
cmd/crossplane/render/op/help/render.md so the document has a clear heading
hierarchy; update the file header and run the help renderer locally to verify
the final rendered output includes a single top-level heading and that
downstream tooling still formats the page correctly.
In `@cmd/crossplane/trace/help/trace.md`:
- Line 42: The example shell command in the trace.md code block exceeds the
100-column guideline; update the code block to wrap the long command (the line
containing "crossplane resource trace cluster.aws.platformref.upbound.io
platform-ref-aws -o dot | dot -Tpng -o graph.png") using a shell continuation
(backslash) or by breaking before the pipe into two indented lines so the
rendered Markdown stays within 100 columns while preserving exact command
semantics for copy-paste.
🪄 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: 9c355fe3-594b-47db-95b1-77b409a66889
⛔ Files ignored due to path filters (6)
cmd/crossplane/docs-templates/command-reference.md.tmplis excluded by none and included by nonego.modis excluded by none and included by nonego.sumis excluded by!**/*.sumand included by nonegomod2nix.tomlis excluded by none and included by noneinternal/style/dark.jsonis excluded by none and included by noneinternal/style/light.jsonis excluded by none and included by none
📒 Files selected for processing (33)
cmd/crossplane/config/config.gocmd/crossplane/config/help/config.mdcmd/crossplane/convert/compositionenvironment/cmd.gocmd/crossplane/convert/compositionenvironment/help/composition-environment.mdcmd/crossplane/convert/convert.gocmd/crossplane/convert/help/convert.mdcmd/crossplane/docs.gocmd/crossplane/help.gocmd/crossplane/help.mdcmd/crossplane/main.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/top/top.gocmd/crossplane/trace/help/trace.mdcmd/crossplane/trace/trace.gocmd/crossplane/validate/cmd.gocmd/crossplane/validate/help/validate.mdcmd/crossplane/xpkg/build.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/push.gocmd/crossplane/xpkg/update.gocmd/crossplane/xpkg/xpkg.gointernal/style/style.go
haarchri
approved these changes
May 16, 2026
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
2 participants
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
Use the glamour library to render detailed help text using markdown. This makes it more ergonomic to write extensive help text and gives us lots of flexibility in how it's formatted. Define custom light and dark stylesheets based on glamour's defaults, using Crossplane brand colors for common elements.
With markdown-formatted help in place, we can add
crossplane generate-docs, which generates a markdown file following the format of the existing CLI reference page in crossplane/docs. The generated file includes full help (summary, details, flags, etc.) for all commands. This will let us keep the reference docs up-to-date without manual toil.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.- [ ] Addedbackport release-x.ylabels to auto-backport this PR.