@redpanda-data/docs-extensions-and-macros 4.12.3 → 4.12.5

package/extensions/process-context-switcher.js

@@ -205,7 +205,7 @@ module.exports.register = function ({ config }) {
   function injectContextSwitcherToTargetPage(targetPage, contextSwitcher, currentPageResourceId, logger) {
     // Check if target page already has context-switcher attribute
     if (targetPage.asciidoc.attributes['page-context-switcher']) {
-      logger.warn(`Target page ${buildResourceId(targetPage)} already has context-switcher attribute. Skipping injection to avoid overwriting existing configuration: ${targetPage.asciidoc.attributes['page-context-switcher']}`);
+      logger.info(`Target page ${buildResourceId(targetPage)} already has context-switcher attribute. Skipping injection to avoid overwriting existing configuration: ${targetPage.asciidoc.attributes['page-context-switcher']}`);
       return;
     }
 

package/package.json

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

package/tools/property-extractor/Makefile

@@ -92,7 +92,8 @@ redpanda-git:
 # --- Clone Tree-sitter grammar & generate parser ---
 treesitter:
 	@echo "🌲 Ensuring tree-sitter-cpp grammar…"
-	@if [ ! -d "$(TREESITTER_DIR)" ]; then \
+	@if [ ! -d "$(TREESITTER_DIR)/.git" ]; then \
+	  rm -rf "$(TREESITTER_DIR)"; \
 	  git clone https://github.com/tree-sitter/tree-sitter-cpp.git "$(TREESITTER_DIR)"; \
 	fi
 	@echo "🔄 Ensuring tree-sitter-cpp is at compatible version v0.20.5…"

package/tools/property-extractor/helpers/capitalize.js

@@ -0,0 +1,13 @@
+'use strict';
+
+/**
+ * Capitalizes the first letter of a string
+ * @param {string} str - The string to capitalize
+ * @returns {string} The string with first letter capitalized
+ */
+module.exports = function capitalize(str) {
+  if (typeof str !== 'string' || str.length === 0) {
+    return str;
+  }
+  return str.charAt(0).toUpperCase() + str.slice(1);
+};

package/tools/property-extractor/helpers/index.js

@@ -16,4 +16,6 @@ module.exports = {
   anchorName: require('./anchorName.js'),
   parseRelatedTopic: require('./parseRelatedTopic.js'),
   allTopicsConditional: require('./allTopicsConditional.js'),
+  capitalize: require('./capitalize.js'),
+  length: require('./length.js'),
 };

package/tools/property-extractor/helpers/length.js

@@ -0,0 +1,11 @@
+/**
+ * Handlebars helper to get the length of an array
+ * @param {Array} arr - The array
+ * @returns {number} The length of the array
+ */
+module.exports = function length(arr) {
+  if (!arr) return 0;
+  if (Array.isArray(arr)) return arr.length;
+  if (typeof arr === 'object' && arr.length !== undefined) return arr.length;
+  return 0;
+};

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

@@ -61,7 +61,7 @@ endif::[]
 
 {{/if}}
 
-[cols="1e,2a"]
+[cols="1s,2a"]
 |===
 | Property | Value
 
@@ -70,10 +70,22 @@ endif::[]
 
 {{#if enum}}
 | Accepted values
-| {{#each enum}}`{{this}}`{{#if (isEnterpriseEnum this ../x-enum-metadata)}} (Enterprise){{else}}{{#if ../is_enterprise}}{{#if (includes ../enterprise_restricted_value this)}} (Enterprise){{/if}}{{/if}}{{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+|
+ifndef::env-cloud[]
+{{#each enum}}`{{this}}`{{#if (isEnterpriseEnum this ../x-enum-metadata)}} (Enterprise){{else}}{{#if ../is_enterprise}}{{#if (includes ../enterprise_restricted_value this)}} (Enterprise){{/if}}{{/if}}{{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+endif::[]
+ifdef::env-cloud[]
+{{#each enum}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
+endif::[]
 {{else}}{{#if items.enum}}
 | Accepted values
-| {{#each items.enum}}`{{this}}`{{#if (isEnterpriseEnum this ../items.x-enum-metadata)}} (Enterprise){{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+|
+ifndef::env-cloud[]
+{{#each items.enum}}`{{this}}`{{#if (isEnterpriseEnum this ../items.x-enum-metadata)}} (Enterprise){{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+endif::[]
+ifdef::env-cloud[]
+{{#each items.enum}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
+endif::[]
 {{/if}}{{/if}}
 {{#if (and minimum maximum)}}
 
@@ -93,31 +105,34 @@ endif::[]
 {{/if}}
 
 | Default
-|{{#if is_enterprise}}{{#if enterprise_default_description}}{{{enterprise_default_description}}}{{else}}
+|
+{{#if is_enterprise}}
 ifdef::env-cloud[]
-Available in the Redpanda Cloud Console
+Available in the Redpanda Cloud Console{{#if cloud_readonly}} (read-only){{else if cloud_editable}} (editable){{/if}}
 endif::[]
 ifndef::env-cloud[]
 `{{formatPropertyValue default type}}`{{#if default_human_readable}} ({{default_human_readable}}){{/if}}
-endif::[]{{/if}}{{else}}
+endif::[]
+{{else}}
 ifdef::env-cloud[]
-Available in the Redpanda Cloud Console
+Available in the Redpanda Cloud Console{{#if cloud_readonly}} (read-only){{else if cloud_editable}} (editable){{/if}}
 endif::[]
 ifndef::env-cloud[]
 `{{formatPropertyValue default type}}`{{#if default_human_readable}} ({{default_human_readable}}){{/if}}
-endif::[]{{/if}}
+endif::[]
+{{/if}}
 
 | Nullable
 | {{#if nullable}}Yes{{else}}No{{/if}}
 {{#if units}}
 
 | Unit
-| {{units}}
+| {{capitalize units}}
 {{else}}
 {{#if (formatUnits name)}}
 
 | Unit
-| {{formatUnits name}}
+| {{capitalize (formatUnits name)}}
 {{/if}}
 {{/if}}
 {{#if (ne defined_in "src/v/config/node_config.cc")}}
@@ -134,22 +149,23 @@ ifndef::env-cloud[]
 endif::[]
 {{#if visibility}}
 
-// tag::self-managed-only[]
+ifndef::env-cloud[]
 | Visibility
-| `{{visibility}}`
-// end::self-managed-only[]
+| {{capitalize visibility}}
+endif::[]
 {{/if}}
 {{#if aliases}}
 
-// tag::self-managed-only[]
+ifndef::env-cloud[]
 | Aliases
-| {{join aliases ", "}}
-// end::self-managed-only[]
+| {{#each aliases}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
+endif::[]
 {{/if}}
 {{#if example}}
 
 | Example
-| {{{example}}}
+|
+{{{example}}}
 {{/if}}
 {{#if related_topics}}
 {{#with (allTopicsConditional related_topics) as |sectionType|}}
@@ -157,48 +173,75 @@ endif::[]
 {{#if (eq sectionType "cloud")}}
 ifdef::env-cloud[]
 | Related topics
-|
+|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+{{else}}
 {{#each ../related_topics}}
 {{#with (parseRelatedTopic this)}}
-{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
+{{{value}}}
 {{/with}}
 {{/each}}
+{{/if}}
 endif::[]
 {{else if (eq sectionType "self-managed")}}
 ifndef::env-cloud[]
 | Related topics
-|
+|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+{{else}}
 {{#each ../related_topics}}
 {{#with (parseRelatedTopic this)}}
-{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
+{{{value}}}
 {{/with}}
 {{/each}}
+{{/if}}
 endif::[]
 {{else}}
 | Related topics
-|
+|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+{{#if (eq type "cloud")}}
+ifdef::env-cloud[]
+* {{{value}}}
+endif::[]
+{{else if (eq type "self-managed")}}
+ifndef::env-cloud[]
+* {{{value}}}
+endif::[]
+{{else}}
+* {{{value}}}
+{{/if}}
+{{/with}}
+{{/each}}
+{{else}}
 {{#each ../related_topics}}
 {{#with (parseRelatedTopic this)}}
 {{#if (eq type "cloud")}}
 ifdef::env-cloud[]
-{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
+{{{value}}}
 endif::[]
 {{else if (eq type "self-managed")}}
 ifndef::env-cloud[]
-{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
+{{{value}}}
 endif::[]
 {{else}}
-{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
+{{{value}}}
 {{/if}}
 {{/with}}
 {{/each}}
 {{/if}}
+{{/if}}
 {{/with}}
 {{/if}}
 
 |===
 
----
 {{#if is_experimental_property}}
 // end::experimental[]
 {{/if}}

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

@@ -1,14 +1,11 @@
 [cols="1a,1a"]
 |===
-| Topic property | Corresponding cluster property
+| Topic Property | Corresponding Cluster Property
 
 {{#each topicProperties}}
 | <<{{anchorName name}},`{{name}}`>>
-| {{#if alternate_cluster_property~}}
-xref:./{{cluster_property_doc_file}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`] or xref:./{{alternate_cluster_property_doc_file}}#{{alternate_cluster_property}}[`{{alternate_cluster_property}}`]
-{{~else~}}
-xref:./{{cluster_property_doc_file}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`]
-{{~/if}}
+| {{#if alternate_cluster_property}}xref:./{{cluster_property_doc_file}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`] or xref:./{{alternate_cluster_property_doc_file}}#{{alternate_cluster_property}}[`{{alternate_cluster_property}}`]{{else}}xref:./{{cluster_property_doc_file}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`]{{/if}}
+
 {{/each}}
 
 |===

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

@@ -46,7 +46,7 @@ endif::[]
 
 {{/if}}
 
-[cols="1e,2a"]
+[cols="1s,2a"]
 |===
 | Property | Value
 
@@ -55,10 +55,21 @@ endif::[]
 
 {{#if enum}}
 | Accepted Values
-| {{#each enum}}`{{this}}`{{#if (isEnterpriseEnum this ../x-enum-metadata)}} (Enterprise){{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+|
+ifndef::env-cloud[]
+{{#each enum}}`{{this}}`{{#if (isEnterpriseEnum this ../x-enum-metadata)}} (Enterprise){{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+endif::[]
+ifdef::env-cloud[]
+{{#each enum}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
+endif::[]
 {{else}}{{#if items.enum}}
 | Accepted Values
-| {{#each items.enum}}`{{this}}`{{#if (isEnterpriseEnum this ../items.x-enum-metadata)}} (Enterprise){{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+|ifndef::env-cloud[]
+{{#each items.enum}}`{{this}}`{{#if (isEnterpriseEnum this ../items.x-enum-metadata)}} (Enterprise){{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+endif::[]
+ifdef::env-cloud[]
+{{#each items.enum}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
+endif::[]
 {{else}}{{#if acceptable_values}}
 | Accepted values
 | {{{acceptable_values}}}
@@ -87,19 +98,13 @@ endif::[]
 {{#if (ne default undefined)}}
 
 | Default
-| {{#if cloud_supported}}
+|
 ifdef::env-cloud[]
-Available in the Redpanda Cloud Console
+Available in the Redpanda Cloud Console{{#if cloud_readonly}} (read-only){{else if cloud_editable}} (editable){{/if}}
 endif::[]
 ifndef::env-cloud[]
 `{{formatPropertyValue default type}}`{{#if default_human_readable}} ({{default_human_readable}}){{/if}}
-endif::[]{{else}}
-ifdef::env-cloud[]
-Available in the Redpanda Cloud Console
 endif::[]
-ifndef::env-cloud[]
-`{{formatPropertyValue default type}}`{{#if default_human_readable}} ({{default_human_readable}}){{/if}}
-endif::[]{{/if}}
 {{/if}}
 
 | Nullable
@@ -112,7 +117,8 @@ endif::[]
 {{#if example}}
 
 | Example
-| {{{example}}}
+|
+{{{example}}}
 {{/if}}
 {{#if related_topics}}
 {{#with (allTopicsConditional related_topics) as |sectionType|}}
@@ -120,55 +126,82 @@ endif::[]
 {{#if (eq sectionType "cloud")}}
 ifdef::env-cloud[]
 | Related topics
-|
+|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+{{else}}
 {{#each ../related_topics}}
 {{#with (parseRelatedTopic this)}}
-{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
+{{{value}}}
 {{/with}}
 {{/each}}
+{{/if}}
 endif::[]
 {{else if (eq sectionType "self-managed")}}
 ifndef::env-cloud[]
 | Related topics
-|
+|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+{{else}}
 {{#each ../related_topics}}
 {{#with (parseRelatedTopic this)}}
-{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
+{{{value}}}
 {{/with}}
 {{/each}}
+{{/if}}
 endif::[]
 {{else}}
 | Related topics
-|
+|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+{{#if (eq type "cloud")}}
+ifdef::env-cloud[]
+* {{{value}}}
+endif::[]
+{{else if (eq type "self-managed")}}
+ifndef::env-cloud[]
+* {{{value}}}
+endif::[]
+{{else}}
+* {{{value}}}
+{{/if}}
+{{/with}}
+{{/each}}
+{{else}}
 {{#each ../related_topics}}
 {{#with (parseRelatedTopic this)}}
 {{#if (eq type "cloud")}}
 ifdef::env-cloud[]
-{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
+{{{value}}}
 endif::[]
 {{else if (eq type "self-managed")}}
 ifndef::env-cloud[]
-{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
+{{{value}}}
 endif::[]
 {{else}}
-{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
+{{{value}}}
 {{/if}}
 {{/with}}
 {{/each}}
 {{/if}}
+{{/if}}
 {{/with}}
 {{/if}}
 {{#if aliases}}
 
-// tag::self-managed-only[]
+ifndef::env-cloud[]
 | Aliases
-| {{join aliases ", "}}
-// end::self-managed-only[]
+| {{#each aliases}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
+endif::[]
 {{/if}}
 
 |===
 
----
 {{#if is_experimental_property}}
 // end::experimental[]
 {{/if}}

package/tools/property-extractor/topic_property_extractor.py

@@ -677,7 +677,7 @@ class TopicPropertyExtractor:
                 prop_data["corresponding_cluster_property"] = cluster_prop
                 prop_data["cluster_property_doc_file"] = self._get_cluster_property_doc_file(cluster_prop)
 
-                # Populate default value from cluster property if available
+                # Populate default value and type from cluster property if available
                 if self.cluster_properties:
                     cluster_props = self.cluster_properties.get("properties", {})
                     if cluster_prop in cluster_props:
@@ -686,6 +686,9 @@ class TopicPropertyExtractor:
                         # Also copy default_human_readable if available
                         if "default_human_readable" in cluster_prop_data:
                             prop_data["default_human_readable"] = cluster_prop_data["default_human_readable"]
+                        # Inherit type from cluster property (more reliable than heuristics)
+                        if "type" in cluster_prop_data:
+                            prop_data["type"] = cluster_prop_data["type"]
 
             # Add alternate cluster property if this has conditional mapping
             if prop_name in self.alternate_mappings:
@@ -706,8 +709,12 @@ class TopicPropertyExtractor:
         if "compression" in prop_name:
             if "compression" in self.enum_values:
                 values = self.enum_values["compression"]["values"]
-                # Filter out special values like 'count', 'producer'
-                filtered_values = [v for v in values if v not in ['count', 'producer']]
+                # Filter out internal values like 'count', but keep 'producer' (it's a valid Kafka value)
+                filtered_values = [v for v in values if v not in ['count']]
+                # Ensure 'producer' is first if present (it's the default and most common)
+                if 'producer' in filtered_values:
+                    filtered_values.remove('producer')
+                    filtered_values.insert(0, 'producer')
                 return f"[`{'`, `'.join(filtered_values)}`]"
                 
         elif "cleanup.policy" in prop_name: