@redpanda-data/docs-extensions-and-macros 5.38.8 → 5.38.10

package/extensions/render-property-descriptions.js

@@ -261,11 +261,26 @@ function anchorIndex (contentCatalog, attachment, properties, logger) {
   }
   for (const [name, entry] of pages) {
     if (!entry || !entry.page) continue
-    index.set(propertyAnchor(name), { page: entry.page, name })
+    const anchor = propertyAnchor(name)
+    index.set(anchor, { page: entry.page, name, anchor })
+    // Legacy spelling. Before anchors replaced dots with hyphens they dropped
+    // them, so descriptions written then say <<redpandaremoteread>> for
+    // redpanda.remote.read, and some carry a stray hyphen (<<redpandastorage-mode>>).
+    // Those still name a documented property; only the spelling is old. Index
+    // the dot-and-hyphen-free form too, so they resolve to the real anchor
+    // instead of degrading to plain text and a warning on every build of every
+    // version still carrying them. A real anchor always wins over a legacy one.
+    const legacy = LEGACY_ANCHOR_PREFIX + legacyAnchorKey(name)
+    if (!index.has(legacy)) index.set(legacy, { page: entry.page, name, anchor })
   }
   return index
 }
 
+const LEGACY_ANCHOR_PREFIX = 'legacy:'
+function legacyAnchorKey (name) {
+  return name.replace(/[.-]/g, '')
+}
+
 /**
  * Rewrite <<anchor>> to an xref before conversion.
  *
@@ -278,8 +293,8 @@ function anchorIndex (contentCatalog, attachment, properties, logger) {
 function resolveInternalRefs (description, anchors, report) {
   return description.replace(INTERNAL_REF_RX, (match, anchor, display) => {
     const text = (display || '').trim()
-    const target = anchors.get(anchor)
-    if (target) return `xref:reference:${target.page}.adoc#${anchor}[${attrlistValue(text || `\`${target.name}\``)}]`
+    const target = anchors.get(anchor) || anchors.get(LEGACY_ANCHOR_PREFIX + legacyAnchorKey(anchor))
+    if (target) return `xref:reference:${target.page}.adoc#${target.anchor || anchor}[${attrlistValue(text || `\`${target.name}\``)}]`
     // The anchor names no documented property, so there is nothing to link to.
     // Asciidoctor would render a same-page fragment, and a tooltip is shown on
     // arbitrary pages, so that link would go nowhere and still invite a click --

package/package.json

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

package/tools/property-extractor/merge-rp-util.js

@@ -207,15 +207,21 @@ async function handleMergeUnavailable(tag, enhanced, reason, output = enhanced)
 }
 
 // rp_util covers every cluster/broker-scope property (see this file's own
-// header comment), so when its merge is skipped or fails, any cluster/
-// broker property still missing gets_restored isn't "no annotation exists"
-// (the pre-existing, legitimate case property.hbs already renders as an
-// absent row) -- it's "we don't know, because the merge that would have
-// told us didn't run". Mark those explicitly so the template can render
-// that as a visible "Unknown" state instead of silently rendering nothing,
-// which previously made a flaky rp_util fetch indistinguishable from a
-// real upstream change in the generated docs.
+// header comment), so when its merge is skipped or fails, a cluster/broker
+// property still missing gets_restored means "we don't know, because the
+// merge that would have told us didn't run". Mark those so the template can
+// render a visible "Unknown" instead of silently rendering nothing, which
+// made a flaky rp_util fetch indistinguishable from a real upstream change.
+//
+// Since the Tree-sitter pass materializes the declared default (see
+// GetsRestoredTransformer), a source-parsed property always arrives with the
+// key set, so this now marks only entries with no source to default from.
+// That is the honest scope for it: an override-fabricated stub has no
+// declaration to read, but the reason is the missing property, not the
+// missing merge, so those are skipped too and simply render no row.
 const RP_UTIL_COVERED_SCOPES = new Set(['cluster', 'broker'])
+const NO_SOURCE_PROVENANCE = 'override'
+
 
 function markRpUtilMergeUnavailable(enhancedPath) {
   let data
@@ -230,12 +236,17 @@ function markRpUtilMergeUnavailable(enhancedPath) {
   for (const prop of Object.values(properties)) {
     if (!prop || !RP_UTIL_COVERED_SCOPES.has(prop.config_scope)) continue
     if (prop.gets_restored !== undefined) continue
+    if (prop.defined_in === NO_SOURCE_PROVENANCE) continue
     prop.rp_util_merge_status = 'unavailable'
     marked++
   }
   if (marked === 0) return
   try {
-    fs.writeFileSync(enhancedPath, bigIntJson.stringify(data))
+    // indent 4, matching what property_extractor.py and rp_util_merge.py
+    // write. Without it this rewrite minified the whole dataset onto one
+    // line, flipping the committed attachment from 14,000 diffable lines
+    // to one.
+    fs.writeFileSync(enhancedPath, bigIntJson.stringify(data, 4))
   } catch (err) {
     console.warn(`Warning: could not write rp_util-unavailable marker to ${enhancedPath}: ${err.message}`)
   }

package/tools/property-extractor/templates/property.hbs

@@ -155,17 +155,19 @@ endif::[]
 {{/if}}
 {{/if}}
 
-ifndef::env-cloud[]
 {{#if (ne gets_restored undefined)}}
 
+ifndef::env-cloud[]
 | Restored on xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]
 | {{#if gets_restored}}Yes{{else}}No{{/if}}
+endif::[]
 {{else if (eq rp_util_merge_status "unavailable")}}
 
+ifndef::env-cloud[]
 | Restored on xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]
 | Unknown (rp_util merge unavailable this build)
-{{/if}}
 endif::[]
+{{/if}}
 {{#if visibility}}
 
 ifndef::env-cloud[]

package/tools/property-extractor/templates/topic-property.hbs

@@ -132,13 +132,13 @@ endif::[]
 | Nullable
 | {{#if nullable}}Yes{{else}}No{{/if}}
 
-ifndef::env-cloud[]
 {{#if (ne gets_restored undefined)}}
 
+ifndef::env-cloud[]
 | Restored on xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]
 | {{#if gets_restored}}Yes{{else}}No{{/if}}
-{{/if}}
 endif::[]
+{{/if}}
 {{#if example}}
 
 | Example

package/tools/property-extractor/topic_property_extractor.py

@@ -119,6 +119,16 @@ class TopicPropertyExtractor:
                             "default": None,  # Will be populated from cluster property if available
                             "is_noop": False,  # Will be updated later in _correlate_properties_with_data
                             "is_topic_property": True,
+                            # A topic property is a Kafka topic config, not a
+                            # config::property, so there is no per-property
+                            # `restored` annotation to read and rp_util's dumps
+                            # do not cover topic scope. Whole Cluster Restore
+                            # restores topic metadata (see the WCR docs), which
+                            # is where these live, so the answer is yes for all
+                            # of them. Set it explicitly: topic-property.hbs
+                            # drops the row when the key is absent, which
+                            # silently deleted it from all 48 properties.
+                            "gets_restored": True,
                             "config_scope": "topic"
                         }
             print(f"Found {total_matches} topic properties in {file_path}")
@@ -176,6 +186,16 @@ class TopicPropertyExtractor:
                             "default": None,  # Will be populated from cluster property if available
                             "is_noop": False,  # Will be updated later in _correlate_properties_with_data
                             "is_topic_property": True,
+                            # A topic property is a Kafka topic config, not a
+                            # config::property, so there is no per-property
+                            # `restored` annotation to read and rp_util's dumps
+                            # do not cover topic scope. Whole Cluster Restore
+                            # restores topic metadata (see the WCR docs), which
+                            # is where these live, so the answer is yes for all
+                            # of them. Set it explicitly: topic-property.hbs
+                            # drops the row when the key is absent, which
+                            # silently deleted it from all 48 properties.
+                            "gets_restored": True,
                             "config_scope": "topic"
                         }
         except Exception as e:

package/tools/property-extractor/transformers.py

@@ -479,7 +479,15 @@ def find_meta_dict(info):
 
         # Case 1: Already parsed dict
         if isinstance(val, dict) and any(
-            k in val for k in ("needs_restart", "visibility", "deprecated", "secret", "experimental")
+            k in val
+            for k in (
+                "needs_restart", "visibility", "deprecated", "secret", "experimental",
+                # A block holding only one of these is still a meta block. Left
+                # out, `meta{ .gets_restored = gets_restored::no }` resolved to
+                # None here and the caller fell back to its default, inverting
+                # the value it had already parsed correctly.
+                "gets_restored", "restored",
+            )
         ):
             return val
 
@@ -1072,14 +1080,45 @@ class GetsRestoredTransformer:
     """
     
     def accepts(self, info, file_pair):
-        """Process properties with backup/restore metadata."""
-        return (get_meta_value(info, "gets_restored") is not None or 
-                get_meta_value(info, "restored") is not None)
+        """Process every property parsed from source, annotated or not.
+
+        Accepting only annotated properties left the key absent for the
+        majority, and absent then had to carry two incompatible meanings:
+        "the declared default applies" and "the data never reached us". The
+        templates cannot tell those apart, and for a release whose rp_util
+        schema can never be published they picked the second, rendering
+        "Unknown" for 626 properties whose value is not in doubt.
+
+        A property reaching this transformer was parsed out of the C++, so the
+        first meaning is the true one and this is the place that knows it.
+        """
+        return True
 
     def parse(self, property, info, file_pair):
-        """Extract restoration flag from either naming convention."""
-        val = get_meta_value(info, "gets_restored") or get_meta_value(info, "restored", "no")
-        property["gets_restored"] = (val != "no")
+        """Extract the restoration flag, defaulting to the declared default.
+
+        base_property.h declares `gets_restored gets_restored{gets_restored::yes}`,
+        so a property carrying no annotation is restored. Materialize that
+        rather than leaving it implicit: at v26.2.2 every one of the 17
+        annotated properties says `no`, so the default is what the other 674
+        actually rely on.
+
+        rp_util's runtime value still wins wherever the merge runs -- it sets
+        the same key afterwards (see rp_util_merge.map_rp_util_property) -- so
+        this is the fallback for the releases the merge cannot cover, not a
+        competing source of truth.
+        """
+        val = get_meta_value(info, "gets_restored")
+        if val is None:
+            val = get_meta_value(info, "restored")
+        if val is not None:
+            property["gets_restored"] = (val != "no")
+        else:
+            # MetaParamTransformer runs first (property_extractor.py) and sets
+            # this key off the same meta block, so only default when nothing
+            # upstream resolved a real value. Assigning unconditionally would
+            # overwrite an explicit `no` with the default.
+            property.setdefault("gets_restored", True)
         return property