@redpanda-data/docs-extensions-and-macros 5.56.1 → 5.58.0

package/macros/USER_GUIDE.adoc

@@ -25,6 +25,7 @@ asciidoc:
   extensions:
     - '@redpanda-data/docs-extensions-and-macros/macros/glossary'
     - '@redpanda-data/docs-extensions-and-macros/macros/config-ref'
+    - '@redpanda-data/docs-extensions-and-macros/macros/prop'
     - '@redpanda-data/docs-extensions-and-macros/macros/helm-ref'
 ----
 
@@ -63,6 +64,33 @@ config_ref:cleanup.policy,false[]
 * `isLink` - Whether to create a link (true/false, required)
 * `path` - Document path for link (required if isLink is true)
 
+=== prop and propval - Property names and values
+
+Mark a configuration property's name, and render its values from the property data:
+
+[,asciidoc]
+----
+Set prop:log_segment_ms[], which defaults to propval:log_segment_ms[default].
+The minimum is propval:log_segment_ms[min].
+----
+
+With Redpanda 26.2 data, that renders "defaults to 2 weeks" and "The minimum is 1 minute".
+
+*Syntax:* `prop:name[]` and `propval:name[field,format=raw]`
+
+* `name` - Property name (required)
+* `field` - `default` (when omitted), `type`, `unit`, `min`, `max`, `restart`, `nullable`, `values`, `scope`, `introduced`, `visibility`, `restored`, `aliases`, or `cloud-access`
+* `format=raw` - The exact value (`1209600000`) instead of the human-readable one (`2 weeks`)
+
+Register `@redpanda-data/docs-extensions-and-macros/macros/prop`, which provides both macros. If a value can't be verified for the page's version, the page shows `<unknown default>` and the build log says why. See link:REFERENCE.adoc#propval[the macros reference] for every field and failure case.
+
+To find hand-written values in a repo and check them against the data:
+
+[,bash]
+----
+npx doc-tools generate migrate-property-values --docs-dir . --report-dir ./propval-report
+----
+
 === helm_ref - Helm value references
 
 Link to Helm chart values:

package/macros/prop.js

@@ -83,6 +83,24 @@
  *   property-ref-role     CSS class applied to the code element
  *                         (default: property-ref).
  *
+ * PROPERTY VALUES: propval:
+ *
+ * The same registration also provides propval:<name>[<field>], which renders
+ * one value from the property data as plain text, so prose such as "defaults
+ * to 128 MiB" comes from the data instead of being typed by hand:
+ *
+ *   propval:log_segment_ms[default]              -> 2 weeks
+ *   propval:log_segment_ms[default,format=raw]   -> 1209600000
+ *   propval:log_segment_ms[min]                  -> 1 minute
+ *   propval:cloud_storage_enabled[restart]       -> yes
+ *
+ * It uses exactly prop:'s dataset selection, validation modes, Cloud gating
+ * and missing-data refusal (loadProperties, isAvailable, warnSeriesMissing),
+ * and formats values with the reference generator's own helpers (see
+ * extension-utils/property-values.js). Whenever no verified value exists, it
+ * renders a visible placeholder such as <unknown default> and reports why,
+ * because unlike a property name, a value has no safe fallback.
+ *
  * Example use in a playbook:
  *
  *   asciidoc:
@@ -92,6 +110,7 @@
 
 const semver = require('semver')
 const { escapeHtml } = require('../extension-utils/html-utils')
+const propertyValues = require('../extension-utils/property-values')
 const logger = require('@antora/logger')('prop-macro')
 
 const $propertyRegistry = Symbol('$propertyRegistry')
@@ -968,6 +987,116 @@ function propInlineMacro (config) {
   }
 }
 
+const VALUE_ROLE = 'property-value'
+const UNKNOWN_VALUE_ROLE = 'property-value-unknown'
+
+/**
+ * Build the HTML emitted for one propval: instance. Exported for unit testing.
+ *
+ * @param {object} opts
+ * @param {string} opts.name - Property name.
+ * @param {string} opts.field - Canonical (or as-written, for a placeholder) field.
+ * @param {string} [opts.text] - The value, as plain text.
+ * @param {string} [opts.html] - Pre-escaped markup, used instead of text.
+ * @param {boolean} [opts.unknown] - Render the placeholder instead.
+ * @returns {string}
+ */
+function buildPropvalContent ({ name, field, text, html, unknown = false }) {
+  const attrs = `data-property="${escapeHtml(name)}" data-field="${escapeHtml(field)}"`
+  if (unknown) {
+    return `<span class="${VALUE_ROLE} ${UNKNOWN_VALUE_ROLE}" ${attrs}>${escapeHtml(`<unknown ${field}>`)}</span>`
+  }
+  return `<span class="${VALUE_ROLE}" ${attrs}>${html !== undefined ? html : escapeHtml(text)}</span>`
+}
+
+/**
+ * Resolve one propval: call to its value, or to the reason there is none.
+ * Shares every decision with prop: -- the dataset (loadProperties), the
+ * availability gate (isAvailable) -- so a value is shown exactly where prop:
+ * would mark the name, and nowhere else. Exported for unit testing and for
+ * the migrate-property-values report.
+ *
+ * @param {string} [opts.filePath] - Named in the message, when known.
+ * @returns {{ok: true, text: string, html?: string, registry: object, field: string} |
+ *           {ok: false, kind: string, message: string, registry?: object, field: string}}
+ */
+function resolvePropertyValue ({ registry, name, field: requested, format, component, filePath }) {
+  const field = propertyValues.normalizeField(requested)
+  const call = `propval:${name}[${requested}]${filePath ? ` in ${filePath}` : ''}`
+  if (!field) {
+    const supported = Object.keys(propertyValues.FIELDS).join(', ')
+    return { ok: false, kind: 'unsupported-field', field: requested, message: `${call}: '${requested}' is not a field propval: supports. Supported fields: ${supported}.` }
+  }
+  if (!registry) {
+    return { ok: false, kind: 'no-data', field, message: `${call}: this page has no property data to read '${field}' from (see the prop macro warning for this component version), so it renders <unknown ${field}> rather than a value from another release.` }
+  }
+  const entry = Object.prototype.hasOwnProperty.call(registry.properties, name) ? registry.properties[name] : undefined
+  if (!entry || typeof entry !== 'object') {
+    return { ok: false, kind: 'unknown-property', field, registry, message: `${call}: '${name}' is not in the property data this page validates against (${describeDataset(registry)}). Either the name is misspelled or the property does not exist in that release.` }
+  }
+  if (!isAvailable(registry, entry)) {
+    return { ok: false, kind: 'unavailable', field, registry, message: `${call}: '${name}' is not available in the ${component || 'this'} component: ${describeDataset(registry)} marks it cloud_supported: false, so no value is shown to readers who cannot set it.` }
+  }
+  if (registry.surface === SURFACE_CLOUD && propertyValues.FIELDS[field].cloudHidden) {
+    return { ok: false, kind: 'cloud-hidden', field, registry, message: `${call}: the property reference does not state '${field}' for Cloud (Cloud configures it, and the reference renders it only outside env-cloud), so this Cloud page renders <unknown ${field}>. Put the sentence in an ifndef::env-cloud[] block, or use a field the Cloud reference shows, such as cloud-access.` }
+  }
+  const value = propertyValues.fieldValue(entry, field, { format })
+  if (!value.ok && value.reason === 'imprecise') {
+    return { ok: false, kind: 'imprecise', field, registry, message: `${call}: the ${field} of '${name}' in ${describeDataset(registry)} is an integer larger than JavaScript represents exactly, so the build cannot render it without changing digits and renders <unknown ${field}>. State the value in prose by hand.` }
+  }
+  if (!value.ok) {
+    return { ok: false, kind: 'missing-field', field, registry, message: `${call}: '${name}' has no ${field} in ${describeDataset(registry)}, so it renders <unknown ${field}>.` }
+  }
+  return { ok: true, field, registry, text: value.text, html: value.html }
+}
+
+function propvalInlineMacro (config) {
+  return function () {
+    const self = this
+    self.named('propval')
+    self.positionalAttributes(['field'])
+    self.process(function (parent, target, attributes) {
+      const document = parent.getDocument()
+      const name = target.trim()
+      const mode = document.getAttribute('property-validate', 'warn')
+      const filePath = config && config.file && config.file.src && config.file.src.path
+      const component = (config && config.file && config.file.src && config.file.src.component) || ''
+      const version = (config && config.file && config.file.src && config.file.src.version) || ''
+      const requested = String(attributes.field || 'default').trim()
+      let format = String(attributes.format || propertyValues.FORMAT_HUMAN).trim().toLowerCase()
+      const where = filePath ? ` in ${filePath}` : ''
+      if (format !== propertyValues.FORMAT_HUMAN && format !== propertyValues.FORMAT_RAW) {
+        logger.warn(`propval:${name}[${requested}]${where}: format=${format} is not supported; use format=raw for the exact value. Rendering the human-readable value.`)
+        format = propertyValues.FORMAT_HUMAN
+      }
+
+      const contentCatalog = config && config.contentCatalog
+      const registry = contentCatalog ? loadProperties(config) : undefined
+      if (!registry && contentCatalog && mode !== 'off') {
+        // The same once-per-component-version diagnostic prop: emits.
+        if (!warnSeriesMissing(contentCatalog, component, version)) warnNoPropertyData(contentCatalog, component, version)
+      }
+      const result = resolvePropertyValue({ registry, name, field: requested, format, component, filePath })
+      if (result.ok) {
+        return self.createInline(parent, 'quoted', buildPropvalContent({ name, field: result.field, text: result.text, html: result.html }))
+      }
+      // Authoring errors fail the build in error mode, like an unknown prop:
+      // name. So do cloud-hidden and unavailable: they appear only in the
+      // Cloud build of single-sourced prose, where a warning alone would let
+      // the placeholder ship. Everything else is reported and rendered as the
+      // placeholder. A placeholder is reported even in off mode: off means
+      // "do not check names", but a value cannot fall back to anything, and a
+      // silent <unknown default> would reach readers unnoticed.
+      const { message } = result
+      if (mode === 'error' && ['unknown-property', 'missing-field', 'unsupported-field', 'cloud-hidden', 'unavailable'].includes(result.kind)) {
+        throw new Error(message)
+      }
+      logger.warn(message)
+      return self.createInline(parent, 'quoted', buildPropvalContent({ name, field: result.field, unknown: true }))
+    })
+  }
+}
+
 /**
  * helm-path=auto displays the property as its Helm values path on pages
  * rendered with env-kubernetes, so single-sourced content reads correctly for
@@ -986,9 +1115,11 @@ function register (registry, config = {}) {
   if (typeof registry.register === 'function') {
     registry.register(function () {
       this.inlineMacro(propInlineMacro(config))
+      this.inlineMacro(propvalInlineMacro(config))
     })
   } else if (typeof registry.inlineMacro === 'function') {
     registry.inlineMacro(propInlineMacro(config))
+    registry.inlineMacro(propvalInlineMacro(config))
   } else {
     logger.warn("no 'inlineMacro' method on alleged registry")
   }
@@ -1008,3 +1139,7 @@ module.exports.releaseSeries = releaseSeries
 module.exports.extractHeadingsWithTags = extractHeadingsWithTags
 module.exports.evaluateTagExpression = evaluateTagExpression
 module.exports.buildPageIndex = buildPageIndex
+module.exports.isAvailable = isAvailable
+module.exports.describeDataset = describeDataset
+module.exports.buildPropvalContent = buildPropvalContent
+module.exports.resolvePropertyValue = resolvePropertyValue

package/package.json

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

package/tools/lint-strings/surfaces/connect.js

@@ -1531,6 +1531,23 @@ const MARKUP_PATTERNS = [
 // link needs an explicit module to resolve in both places.
 const XREF_MODULES = new Set(['components', 'configuration', 'cookbooks', 'get-started', 'guides', 'install', 'reference'])
 
+// Component reference pages live in the components module, one directory
+// per registration kind (inputs/, outputs/, ...). Derived from the kinds
+// above so a new component kind needs no second list.
+const COMPONENT_PAGE_DIRS = new Set(Object.values(REGISTRATION_TYPES)
+  .filter((t) => !t.startsWith('bloblang-'))
+  .map((t) => `${t}s`))
+
+/** The fix a module-less xref needs. Component pages and Bloblang pages have
+ * a module the lint can know (the review prompt says the same); any other
+ * page's module is in its docs URL. */
+function xrefModuleHint (target) {
+  const dir = target.split('/')[0]
+  if (COMPONENT_PAGE_DIRS.has(dir)) return `Name the module: xref:components:${target}[...].`
+  if (dir === 'bloblang') return `Name the module: xref:guides:${target}[...].`
+  return 'Name the module the page lives in. It is the path segment after /connect/ in the page\'s docs URL, so https://docs.redpanda.com/connect/configuration/interpolation/ is xref:configuration:interpolation.adoc[...].'
+}
+
 const AVAILABILITY_PROSE = /\b(?:not (?:available|supported) (?:in|on) (?:Redpanda )?Cloud|only available (?:in|on|for) (?:self-managed|Redpanda Cloud|Cloud)|self-managed only|requires? (?:a )?cgo|CGO_ENABLED|x_benthos_extra)\b/i
 
 /** Surface-specific convention rules. */
@@ -1575,7 +1592,7 @@ const RULES = [
         if (parts.length === 2 && XREF_MODULES.has(parts[0])) continue
         issues.push({
           message: parts.length === 1
-            ? `"xref:${m[1]}[" has no module. It resolves on the self-managed page, but Cloud includes the same partial into its own module, where the link breaks. Name the module, for example xref:components:${m[1]}[...].`
+            ? `"xref:${m[1]}[" has no module. It resolves on the self-managed page, but Cloud includes the same partial into its own module, where the link breaks. ${xrefModuleHint(m[1])}`
             : `"xref:${m[1]}[" names the ${parts[0]} module, which the Redpanda Connect docs do not have, so the link breaks on the rendered page. Use one of ${[...XREF_MODULES].join(', ')}, a component:module:page xref, or a full https:// link.`
         })
       }

package/tools/migrate-property-refs.js

@@ -150,6 +150,19 @@ function convertDocument (content, convertible, options = {}) {
   return { content: converted.join('\n'), count: total, skippedConfigRefs }
 }
 
+// Paths no migration touches: generated content, whose hand edits revert on
+// regeneration, and non-page assets. Shared with migrate-property-values.
+const DEFAULT_EXCLUDE = [
+  'modules/reference/partials/properties/',
+  'modules/reference/pages/rpk/',
+  'modules/reference/partials/rpk',
+  'modules/reference/pages/k-crd.adoc',
+  '-helm-spec.adoc',
+  '/attachments/',
+  '/examples/',
+  '/test-resources/',
+]
+
 /**
  * Walk a modules tree and migrate every .adoc file.
  *
@@ -160,17 +173,7 @@ function convertDocument (content, convertible, options = {}) {
  * @param {string[]} [opts.exclude] - Path substrings to skip.
  * @returns {{files: number, conversions: number, changed: {file: string, count: number}[], ambiguous: string[]}}
  */
-function migrate ({ docsDir, propertiesJson, write, configRefs = false, exclude = [
-    'modules/reference/partials/properties/',
-    // Autogenerated; hand edits revert on regeneration.
-    'modules/reference/pages/rpk/',
-    'modules/reference/partials/rpk',
-    'modules/reference/pages/k-crd.adoc',
-    '-helm-spec.adoc',
-    '/attachments/',
-    '/examples/',
-    '/test-resources/',
-  ] }) {
+function migrate ({ docsDir, propertiesJson, write, configRefs = false, exclude = DEFAULT_EXCLUDE }) {
   const { convertible, ambiguous } = classifyNames(propertiesJson)
   const knownNames = new Set(Object.keys(propertiesJson.properties || {}))
   const changed = []
@@ -203,4 +206,4 @@ function migrate ({ docsDir, propertiesJson, write, configRefs = false, exclude
   return { files, conversions, changed, ambiguous, skippedConfigRefs: [...skippedConfigRefs] }
 }
 
-module.exports = { classifyNames, convertLine, convertConfigRefLine, convertDocument, migrate }
+module.exports = { classifyNames, convertLine, convertConfigRefLine, convertDocument, migrate, DEFAULT_EXCLUDE }