DOC-2407: add selfHostedOnly overrides for cloud-unavailable rpk commands - #1838
Conversation
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThe override guide now documents Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
1131083 to
a8cf35b
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs-data/RPK_OVERRIDES_GUIDE.adoc (1)
365-365: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse an empty xref label when no alternate text is required.
If the generated page title is the intended label, replace the hard-coded
rpk new-commandlabel with empty brackets. This keeps the label synchronized with the target page.Based on learnings, AsciiDoc links should use empty brackets when no alternate display text is required.
Proposed refactor
- "replacement": "xref:reference:rpk/rpk-new-command.adoc[rpk new-command]" + "replacement": "xref:reference:rpk/rpk-new-command.adoc[]"🤖 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 `@docs-data/RPK_OVERRIDES_GUIDE.adoc` at line 365, Update the replacement xref in the relevant RPK override configuration to use an empty label, preserving the target reference while allowing the generated page title to provide the display text instead of hard-coded “rpk new-command”.Source: Learnings
🤖 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.
Nitpick comments:
In `@docs-data/RPK_OVERRIDES_GUIDE.adoc`:
- Line 365: Update the replacement xref in the relevant RPK override
configuration to use an empty label, preserving the target reference while
allowing the generated page title to provide the display text instead of
hard-coded “rpk new-command”.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: f0b193be-e57b-4018-b6a5-591c415a18bc
📒 Files selected for processing (2)
docs-data/RPK_OVERRIDES_GUIDE.adocdocs-data/rpk-overrides.json
JakeSCahill
changed the title
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
Approving. This is the split-down version I asked for on the earlier revision, and the data does what it claims.
Merged onto current main and regenerated with the published 5.3.1: the 22 selfHostedOnly entries produce 69 gated rows across 42 pages, wrapped as ifndef::env-cloud[] with the directives on their own lines. Spot-checked rpk-cluster.adoc, where brokers, health, license, loggers, and maintenance are all correctly gated.
Override validation reports zero errors with this merged in, so none of the 22 entries collide with an existing cloudOnly (the mutual-exclusion check from #239 would have caught that).
Going from +42390/-2486 to +74/-15 makes this genuinely reviewable, which matters for a data change that reshapes 42 published pages.
One coordination note: three other open PRs also edit rpk-overrides.json. I test-merged all four pairwise. This one is clean against #1860 and #1865 in either order; only #1862 conflicts. Details on #1863 where I wrote up the full ordering.
Marks the 22 commands whose pages exist only in the self-managed docs so the generator (docs-extensions-and-macros feat/rpk-subcommand-env-gating) reproduces the env-cloud row gating on regeneration instead of reverting it. Documents the new command-level cloud availability keys in the overrides guide.
a8cf35b to
5162add
Compare
…aves Resolves the rpk-overrides.json conflict by semantic reconstruction: main's last valid state plus the #1838 selfHostedOnly gating (22 commands, re-asserted for the two whose entries this PR empties) plus this PR's 55 content deltas, each set verified programmatically. This also repairs the invalid JSON that the #1838 squash-merge left on main (three unresolved conflict hunks), superseding the standalone hotfix in #1874.
2 participants
Follow-up to #1837, which fixed 25 broken-xref build errors by hand-editing autogenerated rpk pages. Those edits would be reverted by the next rpk regeneration because the generator had no way to express them.
This PR encodes the intent in
rpk-overrides.jsonso regeneration reproduces the fixes:selfHostedOnly: trueto the 22 commands whose reference pages exist only in the self-managed docs (cluster brokers/health/license/loggers/maintenance/partitions/self-test/upgrade, cluster config edit/export/force-reset/import/lint, cluster storage restore, transform pause/resume, topic analyze/describe-storage, shadow config, profile validate, generate license/prometheus-config).cloudOnly/selfHostedOnlykeys in a new "Cloud availability" section of the overrides guide, and fixes a module-prefix lint warning in an existing guide example.Requires the generator support in redpanda-data/docs-extensions-and-macros PR "feat(rpk-docs): gate subcommand table rows by cloud availability". Verified by running that generator build against
rpk-v26.2.1-rc2.jsonwith these overrides: the regenerated pages are byte-identical to the pages fixed in #1837. The overrides are inert until a regeneration runs with the new generator, so merge order does not matter.Jira
Fixes DOC-2407: the 22
selfHostedOnlyentries here match the ticket's 22 broken cloud-docs xref targets exactly (verified 2026-08-02). Once this merges and the rpk pages regenerate, the parent pages' rows for these commands render insideifndef::env-cloud[]and the cloud-docs builds stop emitting the broken links.