@redpanda-data/docs-extensions-and-macros 4.11.0 → 4.12.0

package/tools/property-extractor/generate-handlebars-docs.js

@@ -105,7 +105,17 @@ function registerPartials() {
 }
 
 /**
- * Generate consolidated AsciiDoc partials for properties grouped by type.
+ * Generate AsciiDoc partial files grouping input properties by scope (cluster, topic, broker, object-storage).
+ *
+ * Reads property and topic templates, groups provided properties by their config_scope (treating keys as authoritative property names),
+ * renders each property into the appropriate template, writes combined partial files to "<partialsDir>/properties/<type>-properties.adoc",
+ * and invokes the optional onRender callback for every rendered property name. Entries missing a name or config_scope are skipped;
+ * duplicate keys are detected, warned about, and skipped.
+ *
+ * @param {Object<string, Object>} properties - Map of property key → property object; the map key is used as the property's name.
+ * @param {string} partialsDir - Destination directory under which a "properties" subdirectory will be created for output files.
+ * @param {(name: string) => void} [onRender] - Optional callback invoked with each rendered property's name.
+ * @returns {number} The total number of properties rendered and written to partial files.
  */
 function generatePropertyPartials(properties, partialsDir, onRender) {
   console.log(`📝 Generating consolidated property partials in ${partialsDir}…`);
@@ -122,9 +132,23 @@ function generatePropertyPartials(properties, partialsDir, onRender) {
 
   const propertyGroups = { cluster: [], topic: [], broker: [], 'object-storage': [] };
 
-  Object.values(properties).forEach(prop => {
+  // Track processed property keys to detect duplicates by unique key
+  const processedKeys = new Set();
+  
+  Object.entries(properties).forEach(([key, prop]) => {
     if (!prop.name || !prop.config_scope) return;
 
+    // Skip if we've already processed this key
+    if (processedKeys.has(key)) {
+      console.warn(`⚠️ Duplicate key detected: ${key}`);
+      return;
+    }
+    processedKeys.add(key);
+
+    // Ensure the property uses the key as its name for consistency
+    // This fixes issues where key != name field due to bugs in the source code
+    prop.name = key;
+
     switch (prop.config_scope) {
       case 'topic':
         propertyGroups.topic.push(prop);
@@ -243,19 +267,28 @@ function generateErrorReports(properties, documentedProperties = []) {
   const documentedSet = new Set(documentedProperties);
   const undocumented = [];
 
-  Object.entries(properties).forEach(([key, p]) => {
+    Object.entries(properties).forEach(([key, p]) => {
     const name = p.name || key;
-    if (!p.description || !p.description.trim()) emptyDescriptions.push(name);
+    const desc = p.description;
+
     if (p.is_deprecated) deprecatedProperties.push(name);
+
+    // Ensure description is a non-empty string (exclude deprecated properties)
+    if (!p.is_deprecated && (typeof desc !== 'string' || desc.trim().length === 0)) {
+      emptyDescriptions.push(name);
+    }
+
     if (!documentedSet.has(name)) undocumented.push(name);
   });
 
+
   const total = allKeys.length;
-  const pctEmpty = total ? ((emptyDescriptions.length / total) * 100).toFixed(2) : '0.00';
+  const nonDeprecatedTotal = total - deprecatedProperties.length;
+  const pctEmpty = nonDeprecatedTotal ? ((emptyDescriptions.length / nonDeprecatedTotal) * 100).toFixed(2) : '0.00';
   const pctDeprecated = total ? ((deprecatedProperties.length / total) * 100).toFixed(2) : '0.00';
   const pctUndocumented = total ? ((undocumented.length / total) * 100).toFixed(2) : '0.00';
 
-  console.log(`📉 Empty descriptions: ${emptyDescriptions.length} (${pctEmpty}%)`);
+  console.log(`📉 Empty descriptions: ${emptyDescriptions.length} (${pctEmpty}%) (excludes deprecated)`);
   console.log(`🕸️ Deprecated: ${deprecatedProperties.length} (${pctDeprecated}%)`);
   console.log(`🚫 Not documented: ${undocumented.length} (${pctUndocumented}%)`);
 
@@ -309,7 +342,7 @@ function generateAllDocs(inputFile, outputDir) {
   console.log(`   Deprecated properties:       ${deprecatedCount}`);
 
   if (notRendered > 0) {
-    console.log('⚠️ Undocumented properties:\n   ' + errors.undocumented_properties.join('\n   '));
+    console.log('Ignored:\n   ' + errors.undocumented_properties.join('\n   '));
   }
 
   return {
@@ -349,4 +382,4 @@ if (require.main === module) {
     console.error(`❌ Error: ${err.message}`);
     process.exit(1);
   }
-}
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Handlebars helper for greater than comparison
+ * @param {*} a - First value
+ * @param {*} b - Second value
+ * @returns {boolean} True if a is greater than b
+ */
+module.exports = function gt(a, b) {
+  return a > b;
+};

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

@@ -0,0 +1,17 @@
+'use strict';
+
+/**
+ * Handlebars helper to check if an array includes a value.
+ *
+ * Usage: {{#if (includes array value)}}...{{/if}}
+ *
+ * @param {Array} array - The array to search
+ * @param {*} value - The value to find
+ * @returns {boolean} True if array includes value
+ */
+module.exports = function(array, value) {
+  if (!Array.isArray(array)) {
+    return false;
+  }
+  return array.includes(value);
+};

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

@@ -4,9 +4,12 @@ module.exports = {
   join: require('./join.js'),
   eq: require('./eq.js'),
   ne: require('./ne.js'),
+  gt: require('./gt.js'),
   and: require('./and.js'),
   or: require('./or.js'),
   not: require('./not.js'),
+  includes: require('./includes.js'),
+  isEnterpriseEnum: require('./isEnterpriseEnum.js'),
   formatPropertyValue: require('./formatPropertyValue.js'),
   renderPropertyExample: require('./renderPropertyExample.js'),
   formatUnits: require('./formatUnits.js'),

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

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * Handlebars helper to check if an enum value is marked as enterprise.
+ *
+ * Usage: {{#if (isEnterpriseEnum enumValue x-enum-metadata)}}(Enterprise){{/if}}
+ * Usage in template: {{#each enum}}`{{this}}`{{#if (isEnterpriseEnum this ../x-enum-metadata)}} (Enterprise){{/if}}{{/each}}
+ *
+ * @param {string} enumValue - The enum value to check
+ * @param {Object} metadata - The x-enum-metadata object mapping values to {is_enterprise: boolean}
+ * @returns {boolean} True if the enum value is enterprise-only
+ */
+module.exports = function(enumValue, metadata) {
+  if (!metadata || typeof metadata !== 'object') {
+    return false;
+  }
+
+  const valueMetadata = metadata[enumValue];
+  if (!valueMetadata || typeof valueMetadata !== 'object') {
+    return false;
+  }
+
+  return valueMetadata.is_enterprise === true;
+};

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

@@ -18,8 +18,8 @@ module.exports = function renderPropertyExample(property) {
     if (property.example.includes('.Example') || property.example.includes('[,yaml]')) {
       exampleContent = property.example;
     } else {
-      // Simple string example - wrap it
-      exampleContent = `.Example\n[,yaml]\n----\n${property.name}: ${property.example}\n----`;
+      // Wrap simple string examples in backticks for inline code formatting
+      exampleContent = `\`${property.example}\``;
     }
   } else if (Array.isArray(property.example)) {
     // Multiline array example
@@ -34,9 +34,10 @@ module.exports = function renderPropertyExample(property) {
       exampleContent += `[,yaml]\n----\n${JSON.stringify(property.example.config, null, 2)}\n----`;
     }
   } else {
-    // Fallback: JSON stringify the example
-    exampleContent = `.Example\n[,yaml]\n----\n${property.name}: ${JSON.stringify(property.example, null, 2)}\n----`;
+    // Fallback: JSON stringify and wrap in backticks for inline code
+    const jsonStr = JSON.stringify(property.example, null, 2);
+    exampleContent = `\`${jsonStr}\``;
   }
 
-  return new handlebars.SafeString('\n' + exampleContent + '\n');
+  return new handlebars.SafeString(exampleContent);
 };

package/tools/property-extractor/overrides.json

@@ -0,0 +1,248 @@
+{
+  "$comment": "Overrides file for Redpanda property extraction. Supports two top-level keys: 'properties' for property overrides (descriptions, examples, etc.) and 'definitions' for type definition overrides (structs, enums with user-friendly names, etc.). Override definitions take precedence over dynamically extracted ones.",
+  "definitions": {
+    "client_group_quota": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/client_group_byte_rate_quota.h#L29",
+      "type": "object",
+      "properties": {
+        "group_name": {
+          "type": "string"
+        },
+        "clients_prefix": {
+          "type": "string"
+        },
+        "quota": {
+          "type": "integer",
+          "minimum": -9223372036854775808,
+          "maximum": 9223372036854775807
+        }
+      }
+    },
+    "config::broker_authn_endpoint": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/broker_authn_endpoint.h#L42",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "address": {
+          "type": "string"
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295
+        }
+      }
+    },
+    "config::endpoint_tls_config": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/endpoint_tls_config.h#L21",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "config": {
+          "$ref": "#/definitions/config::tls_config"
+        }
+      }
+    },
+    "config::tls_config": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/tls_config.h#L49",
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "require_client_auth": {
+          "type": "boolean"
+        },
+        "key_file": {
+          "type": "string"
+        },
+        "cert_file": {
+          "type": "string"
+        },
+        "truststore_file": {
+          "type": "string"
+        }
+      }
+    },
+    "tls_config": {
+      "$ref": "#/definitions/config::tls_config"
+    },
+    "config::rest_authn_endpoint": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/rest_authn_endpoint.h#L42",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "address": {
+          "type": "string"
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295
+        },
+        "authentication_method": {
+          "$ref": "#/definitions/config::rest_authn_method"
+        }
+      }
+    },
+    "config::rest_authn_method": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/rest_authn_endpoint.h#L31",
+      "enum": [
+        "none",
+        "http_basic"
+      ]
+    },
+    "endpoint_tls_config": {
+      "$ref": "#/definitions/config::endpoint_tls_config"
+    },
+    "model::broker_endpoint": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L88",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "address": {
+          "type": "string"
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295
+        }
+      }
+    },
+    "model::cleanup_policy_bitflags": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/fundamental.h#L72",
+      "enum": [
+        "none",
+        "delete",
+        "compact"
+      ]
+    },
+    "model::cloud_credentials_source": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L454",
+      "enum": [
+        "config_file",
+        "aws_instance_metadata",
+        "sts",
+        "gcp_instance_metadata"
+      ]
+    },
+    "model::cloud_storage_backend": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L481",
+      "enum": [
+        "aws",
+        "google_s3_compat",
+        "azure",
+        "minio",
+        "unknown"
+      ]
+    },
+    "model::cloud_storage_chunk_eviction_strategy": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L524",
+      "enum": [
+        "eager",
+        "capped",
+        "predictive"
+      ]
+    },
+    "model::compression": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/compression.h#L36",
+      "enum": [
+        "none",
+        "gzip",
+        "snappy",
+        "lz4",
+        "zstd",
+        "producer"
+      ]
+    },
+    "model::leader_balancer_mode": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L504",
+      "enum": [
+        "greedy_balanced_shards",
+        "random_hill_climbing"
+      ]
+    },
+    "model::node_id": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L36",
+      "type": "integer",
+      "minimum": -2147483648,
+      "maximum": 2147483647
+    },
+    "model::partition_autobalancing_mode": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L463",
+      "enum": [
+        "off",
+        "node_add",
+        "continuous"
+      ]
+    },
+    "model::rack_id": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/metadata.h#L60",
+      "type": "string"
+    },
+    "model::timestamp_type": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/model/timestamp.h#L30",
+      "enum": [
+        "create_time",
+        "append_time"
+      ]
+    },
+    "net::unresolved_address": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/net/unresolved_address.h#L27",
+      "properties": {
+        "address": {
+          "type": "string"
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295
+        }
+      }
+    },
+    "pandaproxy::schema_registry::schema_id_validation_mode": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/pandaproxy/schema_registry/schema_id_validation.h#L22",
+      "enum": [
+        "none",
+        "redpanda",
+        "compat"
+      ]
+    },
+    "retention_duration_property": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/property.h#L878",
+      "type": "integer",
+      "minimum": -2147483648,
+      "maximum": 2147483647
+    },
+    "seed_server": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/seed_server.h#L24",
+      "type": "object",
+      "properties": {
+        "host": {
+          "$ref": "#/definitions/net::unresolved_address"
+        }
+      }
+    },
+    "throughput_control_group": {
+      "defined_in": "https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/throughput_control_group.h#L36",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "client_id": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}