Fix rpai in inline code spans and half-backticked command paths - #241
Conversation
Two published-content defects from micheleRP's docs#1860 review: 1. Rules flagged applyToCode never reached inline code spans, so the internal binary name survived in published spans like `rpai auth token` (six occurrences across three rpk ai partials). Inline-code restoration now applies applyToCode rules the same way the early code-block restore does. 2. The command formatter only ever matched 'rpk <word>', so prose like 'rpk ai run codex' got `rpk` wrapped alone, splitting the command in half (16 occurrences on the rpk ai run codex/claude pages). A new pass wraps the longest multi-word path that exists in the command tree being generated, registered from flattenCommands, so prose that merely resembles a command is never wrapped.
✅ Deploy Preview for docs-extensions-and-macros 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 documentation generator now registers flattened command paths before formatting descriptions. It wraps the longest matching registered multi-word command path and leaves unregistered command-like text to existing heuristics. Inline code restoration now applies transformations marked safe for code content. Tests cover command-path matching, unregistered paths, and selective inline-code transformation. Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant generateRpkDocs
participant registerKnownCommandPaths
participant descriptionFormatter
participant inlineCodeRestoration
generateRpkDocs->>registerKnownCommandPaths: register flattened command paths
registerKnownCommandPaths->>descriptionFormatter: provide known paths
descriptionFormatter->>descriptionFormatter: wrap longest matching command path
descriptionFormatter->>inlineCodeRestoration: restore protected spans
inlineCodeRestoration->>inlineCodeRestoration: apply code-safe transformations
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@tools/rpk-docs/generate-rpk-docs.js`:
- Around line 1630-1638: The known-path replacement in
tools/rpk-docs/generate-rpk-docs.js within the result formatter must skip a
registered prefix when trailing tokens are classified as prose, allowing the
existing context-aware formatter to format only rpk; update
__tests__/tools/rpk-docs/text-transformations.test.js to assert the complete
fallback output, such as “Manage `rpk` cloud authentications for details.”
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: c9315a13-10d7-4df3-a0ce-c90d7dc368aa
📒 Files selected for processing (2)
__tests__/tools/rpk-docs/text-transformations.test.jstools/rpk-docs/generate-rpk-docs.js
… breaks
Two more published-content defects in the same chain, found on the
rerendered rpk transform logs and rpk generate license pages:
1. The sentence matcher in capToTwoSentences could not match a sentence
containing a mid-token period (_redpanda.transform_logs, URLs like
redpanda.com/contact). It silently dropped everything up to the
period and emitted the tail as a sentence, publishing summaries like
'View logs for a transform. transform_logs.' Mid-token periods (no
whitespace after) are now protected like decimals.
2. Cobra short descriptions often end without punctuation ('Generate a
trial license\n\nThis command...'). Flattening newlines glued the
paragraphs into a run-on first sentence, so summaries both read
wrong and effectively capped at three sentences. A paragraph break
now terminates a sentence, adding the period when missing.
Also backtick internal topic names (_redpanda.*) in descriptions: the
leading underscore doubles as an AsciiDoc italics delimiter, and topic
names belong in inline code.
cloudOnly/selfHostedOnly wrapped the entire page, doctitle included, in ifdef/ifndef::env-cloud. That wrapper is dead code: single-sourcing consumers only extract the tag=single-source region (which the wrapper sits outside), and the docs component never builds with env-cloud set. Any build that did consume it would publish an empty, untitled page. The gating that matters is unchanged: subcommand rows, flags, and content items inside the tag region, plus cloud-docs not generating stubs for unavailable commands.
Review suggestion: the test asserted only the absence of a fully wrapped phrase. It now pins the complete heuristic-formatter fallback, documenting that a registered single-token prefix never matches the known-path pass (two-token floor).
A plugin splice stamps commands that are new relative to the previous snapshot, but 'new since the snapshot' is not 'new in this release' when the snapshot skipped plugin releases. The first production splice labeled 30 rpk ai commands 'introduced in 0.2.32' when they shipped in 0.2.26 and 0.2.28 (verified against released binaries). Plugin-owned entries are now stamped only when the baseline snapshot recorded the plugin's version AND that version is the release immediately before the new one in the plugin manifest. Anything else is skipped with a warning telling the operator to attribute manually against released binaries. Core rpk entries are unaffected: release regens diff against the actual previous release snapshot.
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
Approving. Verified empirically rather than by reading, and the strongest evidence is the reproduction test.
Byte-for-byte reproduction of main. On a verified-clean checkout of current docs main (fixture provenance checked first), a full --from-json regeneration with this branch's build produced zero changes across all pages — this generator reproduces exactly what #1875 committed, which validates all five fixes at once and confirms the rerender pipeline goes quiet after this releases.
The revert danger is real, not theoretical. The same regeneration with published 5.3.2 changes 57 files, starting with re-adding the page-level ifndef::env-cloud wrappers. Closing the 5.3.2-built rerender auto-PR was right, and docs#1860 must wait for this to release.
Implementation notes from the code read:
- The multi-word wrap list is registered from the real command tree at generation time (
registerKnownCommandPaths(commands.map(c => c.path))), so wrapping can only match genuine command paths, not arbitrary "rpk something" prose. Right design. - The stamper guard is backward-compatible: callers that omit
attributablePluginskeep legacy stamp-everything behavior, and plugin entries are only stamped when the caller vouches the baseline is manifest-adjacent. The skipped-count tracking makes the suppression visible rather than silent. - The inline-span
applyToCodecontainment is tested in both directions: rules with the flag reach spans, rules without it provably never do.
932 tests green as claimed. One caveat for the record: the corrected introduced-in stamps that #1875 committed (policy at 0.2.26, llm-provider/mcp-server/oauth-client at 0.2.28) rest on your verification against released rpai binaries — my reproduction test confirms this generator reproduces those stamps, not independently that they are true.
Release note: this branch sits at 5.3.2, which is already published, and publish-to-npm no-ops on an unchanged version. So this and #240 (which merges cleanly on top, combined suite 933 green) ship nothing until a bump to 5.3.3 lands. Happy to carry that as the release step.
|
Merged, with #240 on top per your tested order. Taking you up on carrying the 5.3.3 release step — once it publishes, the remaining sequence is: merge docs#1860 (its auto-rerender picks up the fixed generator and heals the rpai spans and code blocks), verify the cloud-inclusive build, close DOC-2407/DOC-2408. Thanks for the reproduction-test review, the byte-for-byte check against main is exactly the confidence this needed. |
- Fixture 'to' values use /connect/... (what pub.url emits for name: connect), not the legacy /redpanda-connect/ redirect slug - The dedup keeps the first occurrence so the current page's own entry survives, now stated at the check (the old object-keyed build let later rows overwrite earlier ones) - Dropped the empty retrigger commit - Bumped to 5.3.3: this PR merges last behind #223 and #224, so the publish ships all three plus the already-merged #240 and #241
- Fixture 'to' values use /connect/... (what pub.url emits for name: connect), not the legacy /redpanda-connect/ redirect slug - The dedup keeps the first occurrence so the current page's own entry survives, now stated at the check (the old object-keyed build let later rows overwrite earlier ones) - Dropped the empty retrigger commit - Bumped to 5.3.3: this PR merges last behind #223 and #224, so the publish ships all three plus the already-merged #240 and #241
…ough (#230) * fix(connect): emit context-switcher as array and pass URL entries through buildContextSwitcher returned a type-keyed object, but process-context-switcher requires an array — every multi-type connector page (aws_dynamodb, memory, mongodb, ...) logged 'Invalid context-switcher format: expected array' and the Type dropdown never got processed. The entries carry root-relative pub URLs, which the UI's resolve-resource helper passes through, so the processor now skips them instead of trying to resolve them as resource IDs (which would have traded the format warning for a target-not-found warning). * Address review: production-shape fixture, first-wins comment, 5.3.3 bump - Fixture 'to' values use /connect/... (what pub.url emits for name: connect), not the legacy /redpanda-connect/ redirect slug - The dedup keeps the first occurrence so the current page's own entry survives, now stated at the check (the old object-keyed build let later rows overwrite earlier ones) - Dropped the empty retrigger commit - Bumped to 5.3.3: this PR merges last behind #223 and #224, so the publish ships all three plus the already-merged #240 and #241
2 participants
What
Fixes five published-content defects in the
formatDescription/capToTwoSentenceschain. The first two are @micheleRP's follow-ups from redpanda-data/docs#1860; the second two surfaced on the rerendered pages in redpanda-data/docs#1875.1.
applyToCoderules now reach inline code spansInline spans are protected placeholders during formatting and were restored verbatim, so the
rpai→rpk airewrite never reached them. Published result:rpai auth tokenon the run claude/codex pages andrpai agent a2a task get|watch|cancelon the a2a send page — six occurrences across three partials telling readers to run the internal plugin binary name. The inline-code restore now appliesapplyToCode-flagged rules, mirroring the early code-block restore. Rules without the flag still never touch spans.2. Multi-word command paths wrap as a unit
The heuristic command formatter only ever matches
rpk <word>, so prose likerpk ai run codexgotrpkwrapped alone, leaving backticks around half the command — 16 occurrences on the published run codex/claude pages. New pass before the heuristics:generateRpkDocsregisters every real command path fromflattenCommands, and the formatter wraps the longest registered multi-word path found in prose. Ground truth from the tree means prose that merely resembles a command ("rpk cloud authentications") is never wrapped, and the pass is inert when nothing is registered.3. Mid-token periods no longer eat sentences in summaries
The sentence matcher in
capToTwoSentencescannot match a sentence containing a period with no whitespace after it (_redpanda.transform_logs,redpanda.com/contact). It silently dropped everything up to that period and emitted the tail fragment as a "sentence", publishing summaries likeView logs for a transform. transform_logs.(rpk transform logs) and...Enterprise Edition. com/contact The license is saved...(rpk generate license). Mid-token periods are now protected the same way decimals already were.4. Paragraph breaks terminate sentences in summaries
Cobra short descriptions often end without punctuation (
Generate a trial license\n\nThis command...). Flattening newlines glued the paragraphs into a run-on first sentence, so dozens of published summaries read like "Disable partitions of a topic You may disable..." and effectively capped at three sentences instead of two. A paragraph break now ends a sentence, adding the missing period.Also backticks internal topic names (
_redpanda.*) in descriptions: the leading underscore doubles as an AsciiDoc italics delimiter, and topic names belong in inline code.5. Fabricated introduced-in versions can no longer be stamped
The plugin splice stamps commands that are new relative to the previous snapshot as "introduced in version X". When the snapshot is several plugin releases stale, that fabricates history: the first production splice labeled 30
rpk aicommands "introduced in 0.2.32" when they actually shipped in 0.2.26 (policy family) and 0.2.28 (llm-provider, mcp-server, oauth-client) — verified against released binaries from the plugins manifest. Plugin-owned entries are now stamped only when the baseline snapshot's recorded plugin version is the release immediately before the new one in the manifest. Anything else is skipped with a warning to attribute manually. Core rpk stamps are unchanged (release regens diff against the actual previous release, which is sound) — the 14 core v26.2.1 command stamps and 23 flag stamps all verified correct against the rpk 26.1.12 tree.Validation
rpk transform logssummary:View logs for a transform. Data transform's STDOUT and STDERR are captured during runtime and written to an internally managed topic+"_redpanda.transform_logs"+.Sequencing note
redpanda-data/docs#1860 should merge after this releases, so its auto-rerender picks up these fixes rather than re-publishing the garbled summaries.
Version
No bump included — happy for the coordinator to fold this into whichever release goes out next.
Related