Add :description: to single-source stubs and lint for coverage - #664
Open
micheleRP wants to merge 2 commits into
Open
Add :description: to single-source stubs and lint for coverage#664micheleRP wants to merge 2 commits into
micheleRP wants to merge 2 commits into
Conversation
…ption Stub pages inherit nothing from their single-source includes: Antora resolves page metadata with a header-only parse, so all of these pages shipped the generic site-wide meta description. This copies each stub's description verbatim from its upstream counterpart (145 rpk stubs from the docs repo, 46 connect stubs from rp-connect-docs) into the stub header, where Antora picks it up. The 234 connect stubs whose upstream has no description yet are unchanged; they are tracked in the CI allowlist added in the next commit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds hand-written descriptions for the three remaining non-stub pages (glossary and two index pages). The lint fails any page missing a :description: unless it is listed in .github/description-allowlist.txt, which tracks the 234 connect stubs whose rp-connect-docs upstream has no description yet; a non-blocking hygiene step flags allowlist entries that gain one. Over-155-char descriptions warn on changed files only. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important Review skippedToo many files! This PR contains 196 files, which is 46 over the limit of 150. To get a review, reduce the PR to 150 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to Pro+ to raise the limit. This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry. ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (196)
You can disable this status message by setting the Comment |
Contributor
|
One note for the 145 rpk backfills: these copy descriptions that regeneration rewrites (doc-tools 5.3.3 alone rewrote ~36 rpk descriptions), and unlike adp-docs there's no sync workflow here, so the copied headers will drift over time — the lint checks presence, not freshness. docs-extensions-and-macros#246 prototypes the dynamic alternative (stubs inherit the description from the included partial at build time, verified against an Antora build with the production UI bundle) and composes with this PR: backfills stay correct now, and stubs that later adopt the two-include shape stop needing them. Doesn't affect this PR's merge-readiness or the Connect allowlist. |
Contributor
|
Update on the 234-entry allowlist: it turns out the Connect situation is much smaller than scoped. The connector source data carries a summary for ~97% of components — the pages just predate the template emitting :description: and, as one-time first drafts, were never rewritten. rp-connect-docs#478 backfills 274 page headers mechanically from the source summaries (no prose authored), taking that repo from 101/411 to 375/411 coverage, and the tool behind it ships in docs-extensions-and-macros#246 so future generations self-heal. Once #478 merges, most of this allowlist becomes clearable — the true editorial backlog is seven components with no source summary at all (the slack family, inproc in/out, cypher). |
Contributor
|
Correction to my earlier comment: I claimed the meta include would win over a coexisting literal description. @micheleRP tested it and the precedence is the opposite — the LATER header entry wins, so a literal below the include defeats it. Re-verified in the Antora test build. Consequence for the future conversion (DOC-2414, updated): it inserts the include AND strips the backfilled literal, scoped to generated reference stubs only — the ~262 prose stubs here keep their own descriptions and get no include. None of this changes anything about this PR: the backfills land as-is and are what these pages ship until the conversion. |
JakeSCahill
approved these changes
Aug 5, 2026
JakeSCahill
left a comment
JakeSCahill
left a comment
Contributor
There was a problem hiding this comment.
Verified: sampled Connect backfills match their rp-connect-docs upstreams byte-for-byte (aws_cloudwatch_logs, jira), rpk samples match the docs-repo partials, and the allowlist mechanics are genuinely self-shrinking — the stale-entry and has-a-description-now warnings mean the list can only trend down, which is the right shape for tracked debt.
Same two lint findings as adp-docs#189, both non-blocking here:
- The presence check matches
:description:anywhere in the file, but only a header attribute (above the first blank line) reaches page metadata — the k-connect-helm-spec case in rp-connect-docs shows this class in the wild. Header-scoped awk closes it. - Once the two-include stub shape lands (DOC-2414), converted reference stubs will carry
include::...[tag=meta]and no literal — the lint should accept either form in the header, or it will block the conversion PR.
One happy update for the allowlist: rp-connect-docs#478 gives every upstream page a description (274 mechanical + 7 authored via overrides + 29 hand-maintained pages), so after it merges, all 234 entries here become clearable per the shrink protocol — the warnings this lint emits will tell you exactly when.
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.
What this does
Brings
:description:coverage from 476/904 pages to 670/904 — every page that can have one today — and adds a CI lint with an allowlist ratchet so coverage only improves.Why stubs were missing descriptions
Single-source stub pages inherit nothing from their
include::...[tag=single-source]directives: Antora resolves page metadata with a header-only parse that stops at the stub's first blank line, so the include is never evaluated for attributes. Every affected stub ships the generic site-wide meta description (check anyrpk clusterpage's<meta name="description">on the live site). The single-sourcing standard already calls for stubs to carry their ownTitle + :description: + include— this PR brings 191 stubs into that shape.Changes
page$, andpartial$include families.reference/glossary,develop/connect/cookbooks/index,develop/connect/guides/index..github/workflows/lint-metadata.yml: fails any PR that leaves a page without:description:unless the page is listed in.github/description-allowlist.txt; warns (non-blocking) when an allowlisted page gains a description (remove the entry) and when a changed page's description exceeds the 155-char style-guide recommendation..github/description-allowlist.txt: the 234 connect stubs whose rp-connect-docs upstream has no description yet. The fix path is upstream (docs-data/overrides.jsonin rp-connect-docs); as descriptions land there, re-copy into these stub headers and shrink the list.Notes
:description:on newly created stubs).🤖 Generated with Claude Code
Preview pages
194 pages updated (one
:description:header line each; no visible body changes — check<meta name="description">in page source). Representative samples: