@redpanda-data/docs-extensions-and-macros 5.41.0 → 5.44.0

package/bin/doc-tools.js

@@ -1476,6 +1476,9 @@ automation
  * parsing `-X list` text for rpk versions that predate it. Hidden -X options
  * appear in neither source, so they are excluded automatically.
  *
+ * The table is sectioned by the API group rpk reports for each option, and is
+ * a single flat table on rpk versions that report no groups.
+ *
  * The main rpk-docs pipeline also writes this partial from the tree it
  * already holds; this standalone command is for targeted refreshes without
  * a full generation run.
@@ -1492,7 +1495,7 @@ automation
  */
 automation
   .command('rpk-env-partial')
-  .description('Generate the -X -> RPK_* env var mapping partial from rpk -X list output.')
+  .description('Generate the -X -> RPK_* env var mapping partial from rpk itself.')
   .option('-r, --ref <ref>', 'Git branch or tag to build rpk from (e.g., dev, v26.2.1). Clones from GitHub.')
   .option('--from-source <path>', 'Path to local rpk source (src/go/rpk directory)')
   .option('--rpk-bin <path>', 'Path to an existing rpk binary (skips clone and build)')

package/macros/DOCUMENTING_UNRELEASED_FEATURES.adoc

@@ -47,16 +47,16 @@ The build validates the name against the RC data. A typo gets a warning naming t
 
 === If you forget the property data
 
-You get told, once per component version, with the command to run:
+You get told, once per component version, with the command to run. Every excerpt below is what actually lands in the build log, through Antora's own logger rather than the macro printing its own text -- `HH:MM:SS.mmm` stands in for the real timestamp, which varies on every build:
 
 [literal]
 ----
-prop macro: streaming@26.3 publishes no redpanda-properties-v26.3.*.json attachment
-in its reference module (found for other series: v26.2.1). prop: targets on 26.3
-pages are therefore not validated and their tooltips carry no data, rather than
-being checked against another release's properties. Generate it with
-'npx doc-tools generate property-docs --tag v26.3.<patch>' on that branch, or
-leave prop: out of 26.3 content.
+[HH:MM:SS.mmm] WARN (prop-macro): prop macro: streaming@26.3 publishes no
+redpanda-properties-v26.3.*.json attachment in its reference module (found for
+other series: v26.2.1). prop: targets on 26.3 pages are therefore not validated
+and their tooltips carry no data, rather than being checked against another
+release's properties. Generate it with 'npx doc-tools generate property-docs
+--tag v26.3.<patch>' on that branch, or leave prop: out of 26.3 content.
 ----
 
 Mentions render as plain code with no tooltip until the file exists. That is deliberate: validating 26.3 content against 26.2 data would accept properties that release never had and flag removed ones as typos.
@@ -116,6 +116,34 @@ Enterprise features are declared in the registry (`enterprise-features.yml` in t
 
 Add `status-tooltip` to override the hover text on an `unreleased` badge, or `beta-tooltip` on a `beta` badge.
 
+=== A shipped feature that only exists as of a version: `since`
+
+`status` answers "is this public yet," which is a question about a *branch* (prerelease or not). A different question comes up once a feature has fully shipped: an ordinarily-GA feature -- no `status` key at all -- still has a *first* version, and older released versions predate it. Without a check, a feature that ships in 26.3 would render as fully available on a 24.1 page that predates it by two years, because `status` alone has nothing to say about that.
+
+`since` closes that gap:
+
+[,yaml]
+----
+- name: My Shipped Feature
+  scope: redpanda
+  since: '26.3'
+  description: What it does.
+  expiration: What happens when the licence expires.
+----
+
+The check is against the *page's own version*, not the newest release: a mention on a 26.3 (or later) page renders normally, with no badge, because as of that page's version the feature has shipped. The identical mention on a 26.2 page renders as plain text with no styling, tooltip, or link, and a warning -- the same failure mode as an unreleased feature, but for a version reason rather than a branch reason:
+
+[literal]
+----
+[HH:MM:SS.mmm] WARN (enterprise-macro): enterprise:My Shipped Feature[] in
+modules/manage/pages/example.adoc: 'My Shipped Feature' is marked since: 26.3 in
+the enterprise features registry, but this page is version 26.2, which predates
+it. Move the mention to a page whose version is at or after the since version, or
+remove since if the feature covers this version too.
+----
+
+`since` and `status: unreleased` are independent and can combine: a feature still in an RC carries `status: unreleased` while it is not public at all, then drops that key once it ships and (optionally) gains `since` set to the version it shipped in, so older released versions stop claiming it. Most shipped features need neither key.
+
 === Writing the mention
 
 Unchanged:
@@ -129,12 +157,12 @@ On the prerelease branch this renders with the `unreleased` badge. On released d
 
 [literal]
 ----
-enterprise:My Upcoming Feature[] in modules/manage/pages/example.adoc:
-'My Upcoming Feature' is marked status: unreleased in the enterprise features
-registry, so it is only documented for an upcoming release. This page belongs to
-a released version, so the mention renders as plain text with no enterprise
-styling, tooltip, or link. Move the mention to the prerelease (beta) branch, or
-change the status once the feature ships.
+[HH:MM:SS.mmm] WARN (enterprise-macro): enterprise:My Upcoming Feature[] in
+modules/manage/pages/example.adoc: 'My Upcoming Feature' is marked status:
+unreleased in the enterprise features registry, so it is only documented for an
+upcoming release. This page belongs to a released version, so the mention renders
+as plain text with no enterprise styling, tooltip, or link. Move the mention to
+the prerelease (beta) branch, or change the status once the feature ships.
 ----
 
 The `unreleased` badge cannot be suppressed with `enterprise-beta-badge=false`. "Not in a release yet" is information a reader needs, not decoration.
@@ -167,19 +195,22 @@ Before opening a PR that documents something unreleased:
 * [ ] The mention is on the prerelease branch, not on `main` or a released `v/*` branch.
 * [ ] For a property: the RC property JSON is committed on that branch, generated from the RC tag.
 * [ ] For an enterprise feature: the registry entry has `status: unreleased`, not `beta: true`, unless it is genuinely a public beta.
+* [ ] For a shipped feature gated to a specific version: the registry entry has `since` set to the version it ships in, not left unset.
 * [ ] The build log has no `prop macro:` or `enterprise:` warnings for your additions.
 * [ ] No mention of an unreleased property or feature on a Cloud page.
 
 == Seeing it work
 
-The preview site in this repository has fixtures for every case above, including a prerelease component version and a Cloud component:
+The preview site in this repository has fixtures for every case above, including a prerelease component version and a Cloud component. The fast, fully local way to build just those fixtures, with no GitHub token and no real docs/cloud-docs content:
 
 [,bash]
 ----
-./scripts/macro-test.sh --serve
+./scripts/macro-showcase.sh --serve
 ----
 
-Open `/preview/macros-showcase/`, which shows each macro call, what it renders, and why. `/preview/release-status-test/` and `/macro-fixtures/26.3/` show the same unreleased feature gated on a released version and badged on a prerelease one.
+That builds `local-macro-showcase-playbook.yml` in seconds. Run `./scripts/macro-test.sh --serve` instead when you also want the fixtures proven against real production content (needs a token; pulls the full docs, cloud-docs, redpanda-labs, and rp-connect-docs repos).
+
+Either way, open `/preview/macros-course/` first -- it's a hands-on course, not just a reference: it has you mark a property and register an enterprise feature, then edit the actual fixture data (a property JSON, the enterprise registry) yourself and rebuild to watch the macros react, including reproducing the `status: unreleased` gate on purpose. It links to `/preview/macros-showcase/`, which shows every other macro call, what it renders, and why, as pure reference. `/macro-fixtures/26.2/` and `/macro-fixtures/26.3/` are two versions of the SAME component -- one released, one prerelease (`prerelease: true` in its `antora.yml`) -- so flipping the version selector between them shows the same enterprise: mentions rendering differently with no edits: the unreleased feature badged on 26.3 and gated on 26.2, the since-gated feature (shipped `since: '26.3'`) gated on 26.2 and shipped plain on 26.3, and the beta feature badged on both. `/preview/release-status-test/` shows the unreleased/beta contrast again from a third, versionless component. `/macro-fixtures-cloud/` shows the Cloud availability rules.
 
 == Why the build enforces this rather than trusting reviewers
 

package/macros/REFERENCE.adoc

@@ -68,7 +68,7 @@ asciidoc:
 
 This inline macro marks a feature as an enterprise feature in prose. The feature name renders as a uniquely styled term with a tooltip explaining that the feature requires an Enterprise Edition license, and links to the feature's documentation or to the licensing page.
 
-The macro validates its target against the enterprise features registry: `modules/ROOT/partials/enterprise-features.yml` in the `shared` component (the `shared/` folder of the docs repository). The registry is the canonical list of enterprise features and their approved external names. Targets are matched case-insensitively, including aliases, and the canonical name, feature page link, and tooltip come from the matching entry. A target that matches no entry is reported according to `enterprise-validate`. To mark a new feature as enterprise, add it to the registry first.
+The macro validates its target against the enterprise features registry: `modules/ROOT/partials/enterprise-features.yml` in the `shared` component (the `shared/` folder of the docs repository). The registry is the canonical list of enterprise features and their approved external names. Targets are matched case-insensitively, including aliases, and the canonical name, feature page link, and tooltip come from the matching entry. A target that matches no entry is reported according to `enterprise-validate` and renders as plain text -- no styling, tooltip, or link, since there is nothing verified to style it with. To mark a new feature as enterprise, add it to the registry first.
 
 === Usage
 

package/macros/enterprise.js

@@ -639,22 +639,27 @@ function enterpriseInlineMacro (config) {
       let registry
       if (config && config.contentCatalog) {
         registry = loadRegistry(config)
-        if (!registry) warnNoRegistry(config && config.contentCatalog)
+        if (!registry) warnNoRegistry(config.contentCatalog)
+      }
+      if (!registry) {
+        // Nothing to validate against, so nothing should render as if it
+        // were. Mirrors prop:'s plain fallback for the same reason: a styled
+        // term this build cannot check is worse than an unstyled one.
+        return self.createInline(parent, 'quoted', attributes.text || target)
       }
       let feature = target
-      let entry
-      if (registry) {
-        entry = registry.lookup.get(target.trim().toLowerCase())
-        if (entry) {
-          feature = entry.name
-        } else {
-          reportUnknownFeature({
-            feature: target,
-            mode,
-            registry,
-            filePath,
-          })
-        }
+      const entry = registry.lookup.get(target.trim().toLowerCase())
+      if (entry) {
+        feature = entry.name
+      } else {
+        reportUnknownFeature({ feature: target, mode, registry, filePath })
+        // An unrecognized name has nothing behind it to style -- no xref, no
+        // tooltip, no licence terms to point at. Falling through to the same
+        // styled output a real feature gets, just with a generic fallback
+        // tooltip, let a typo pass for a real feature with nothing on the
+        // page to show a reader it was wrong. Mirrors prop:'s plain fallback
+        // for an unrecognized property name, for the same reason.
+        return self.createInline(parent, 'quoted', attributes.text || feature)
       }
       const status = entryStatus(entry, { mode, filePath, contentCatalog: config && config.contentCatalog })
       if (status === STATUS_UNRELEASED && !isPrereleasePage(config, document)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.41.0",
+  "version": "5.44.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/rpk-docs/generate-rpk-docs.js

@@ -3227,7 +3227,11 @@ function writeEnvVarsPartial (tree, partialsDir) {
     return { written: false }
   }
   const { renderPartial, keyToEnvVar } = require('./generate-x-env-partial.js')
-  const options = tree.x_options.map(o => ({ name: o.name, env: o.env || keyToEnvVar(o.name) }))
+  const options = tree.x_options.map(o => ({
+    name: o.name,
+    env: o.env || keyToEnvVar(o.name),
+    groupTitle: o.group_title || null
+  }))
   const output = path.join(partialsDir, 'rpk-env-vars.adoc')
   fs.mkdirSync(path.dirname(output), { recursive: true })
   fs.writeFileSync(output, renderPartial(options))

package/tools/rpk-docs/generate-x-env-partial.js

@@ -11,6 +11,12 @@
  *    descriptions.
  * 2. `rpk -X list` text output, for rpk versions that predate x_options.
  *
+ * Each x_option also carries the API it configures, as `group` (a stable
+ * slug) and `group_title` (the heading), added in
+ * redpanda-data/streaming-enterprise#311. When rpk supplies them the table is
+ * sectioned by API, so the grouping comes from rpk rather than being restated
+ * here; rpk versions without them get one flat table.
+ *
  * The partial is included by both reference:rpk/rpk-x-options.adoc and
  * reference:environment-variables.adoc in the docs repo. Hidden -X options
  * (for example cloud_environment, whose values are deliberately
@@ -38,10 +44,12 @@ const GENERATED_BANNER = `// tag::generated[]
 /**
  * Extract -X options from `rpk --print-tree` JSON.
  * @param {string} output - Raw stdout from `rpk --print-tree`
- * @returns {Array<{name: string, env: string}>|null} options in display
- *   order, or null when the tree has no x_options (rpk predates
- *   redpanda#31520). The env name comes from rpk itself when present
+ * @returns {Array<{name: string, env: string, group: ?string, groupTitle: ?string}>|null}
+ *   options in display order, or null when the tree has no x_options (rpk
+ *   predates redpanda#31520). The env name comes from rpk itself when present
  *   (the tree's env field is produced by the same derivation rpk reads).
+ *   group and groupTitle are null on rpk versions that do not group the
+ *   options.
  */
 function xOptionsFromTree (output) {
   let tree
@@ -51,7 +59,12 @@ function xOptionsFromTree (output) {
     return null
   }
   if (!Array.isArray(tree.x_options) || tree.x_options.length === 0) return null
-  return tree.x_options.map(o => ({ name: o.name, env: o.env || keyToEnvVar(o.name) }))
+  return tree.x_options.map(o => ({
+    name: o.name,
+    env: o.env || keyToEnvVar(o.name),
+    group: o.group || null,
+    groupTitle: o.group_title || null
+  }))
 }
 
 /**
@@ -96,16 +109,53 @@ function keyToAnchor (key) {
   return key.replace(/\./g, '-')
 }
 
+/**
+ * Group options by the API group rpk reports, in first-seen order.
+ *
+ * Returns null unless every option carries a group title, so a table is
+ * either fully sectioned or not sectioned at all: a half-sectioned table
+ * would read as though the options with no heading belonged to the section
+ * above them.
+ *
+ * Grouping by title rather than slicing on the boundaries means a group whose
+ * options are not contiguous still gets one heading instead of two.
+ * @param {Array<{name: string, env: string, groupTitle: ?string}>} options
+ * @returns {Array<{title: string, options: Array<Object>}>|null}
+ */
+function groupOptions (options) {
+  if (!options.every(o => o.groupTitle)) return null
+  const byTitle = new Map()
+  for (const option of options) {
+    const existing = byTitle.get(option.groupTitle)
+    if (existing) existing.push(option)
+    else byTitle.set(option.groupTitle, [option])
+  }
+  return [...byTitle].map(([title, opts]) => ({ title, options: opts }))
+}
+
+/**
+ * Render one table row for an option.
+ * @param {{name: string, env: string}} option
+ * @returns {string}
+ */
+function renderRow ({ name, env }) {
+  return `|xref:reference:rpk/rpk-x-options.adoc#${keyToAnchor(name)}[${name}] |${env}`
+}
+
 /**
  * Render the partial's AsciiDoc content.
- * @param {Array<{name: string, env: string}>} options - -X options
+ *
+ * The table is sectioned by API group when rpk reports one for every option,
+ * and is a single flat table otherwise (rpk versions that predate the groups,
+ * and the -X list fallback, which has no group data to parse).
+ * @param {Array<{name: string, env: string, groupTitle: ?string}>} options - -X options
  * @returns {string}
  */
 function renderPartial (options) {
-  const rows = options.map(({ name, env }) => {
-    const xrefTarget = `xref:reference:rpk/rpk-x-options.adoc#${keyToAnchor(name)}[${name}]`
-    return `|${xrefTarget} |${env}`
-  })
+  const groups = groupOptions(options)
+  const body = groups
+    ? groups.map(g => `2+s|${g.title}\n${g.options.map(renderRow).join('\n')}`).join('\n\n')
+    : options.map(renderRow).join('\n')
   return `${GENERATED_BANNER}
 Every \`-X\` option has a corresponding \`RPK_*\` environment variable. Convert by prefixing with \`RPK_\` and replacing dots with underscores:
 
@@ -113,7 +163,7 @@ Every \`-X\` option has a corresponding \`RPK_*\` environment variable. Convert
 |===
 |\`-X\` Option |Environment Variable
 
-${rows.join('\n')}
+${body}
 |===
 // end::generated[]
 `
@@ -276,6 +326,7 @@ function handleXEnvPartialGeneration (options) {
 
 module.exports = {
   xOptionsFromTree,
+  groupOptions,
   parseXList,
   keyToEnvVar,
   keyToAnchor,