@redpanda-data/docs-extensions-and-macros 4.7.4 → 4.8.1

package/bin/doc-tools.js

@@ -98,7 +98,7 @@ function requireCmd(cmd, help, versionFlag = '--version') {
  * @param {number} [minMinor=10] - Minimum required minor version of Python.
  */
 function requirePython(minMajor = 3, minMinor = 10) {
-  const candidates = ['python3', 'python'];
+  const candidates = ['python3', 'python', 'python3.12', 'python3.11', 'python3.10'];
   for (const p of candidates) {
     try {
       const out = execSync(`${p} --version`, { encoding: 'utf8' }).trim();
@@ -234,12 +234,16 @@ For more details, visit: https://github.com/norwoodj/helm-docs
 /**
  * Ensures all dependencies required for generating property documentation are installed.
  *
- * Checks for the presence of `make`, Python 3.10 or newer, C++ compiler, and C++ standard library headers.
+ * Checks for the presence of `make`, Python 3.10 or newer, Node.js, C++ compiler, and C++ standard library headers.
  * Exits the process with an error message if any dependency is missing.
  */
 function verifyPropertyDependencies() {
   requireCmd('make', 'Your OS package manager');
   requirePython();
+  
+  // Check for Node.js (required for Handlebars templates)
+  requireCmd('node', 'https://nodejs.org/en/download/ or use your package manager (e.g., brew install node)');
+  requireCmd('npm', 'Usually installed with Node.js');
 
   // Check for C++ compiler
   let cppCompiler = null;
@@ -463,25 +467,23 @@ function runClusterDocs(mode, tag, options) {
   if (r.status !== 0) process.exit(r.status);
 }
 
-// helper to diff two autogenerated directories
-function diffDirs(kind, oldTag, newTag) {
-  const oldDir = path.join('autogenerated', oldTag, kind);
-  const newDir = path.join('autogenerated', newTag, kind);
-  const diffDir = path.join('autogenerated', 'diffs', kind, `${oldTag}_to_${newTag}`);
+// helper to diff two temporary directories
+function diffDirs(kind, oldTag, newTag, oldTempDir, newTempDir) {
+  const diffDir = path.join('tmp', 'diffs', kind, `${oldTag}_to_${newTag}`);
   const patch = path.join(diffDir, 'changes.patch');
 
-  if (!fs.existsSync(oldDir)) {
-    console.error(`❌ Cannot diff: missing ${oldDir}`);
+  if (!fs.existsSync(oldTempDir)) {
+    console.error(`❌ Cannot diff: missing ${oldTempDir}`);
     process.exit(1);
   }
-  if (!fs.existsSync(newDir)) {
-    console.error(`❌ Cannot diff: missing ${newDir}`);
+  if (!fs.existsSync(newTempDir)) {
+    console.error(`❌ Cannot diff: missing ${newTempDir}`);
     process.exit(1);
   }
 
   fs.mkdirSync(diffDir, { recursive: true });
 
-  const cmd = `diff -ru "${oldDir}" "${newDir}" > "${patch}" || true`;
+  const cmd = `diff -ru "${oldTempDir}" "${newTempDir}" > "${patch}" || true`;
   const res = spawnSync(cmd, { stdio: 'inherit', shell: true });
 
   if (res.error) {
@@ -489,6 +491,10 @@ function diffDirs(kind, oldTag, newTag) {
     process.exit(1);
   }
   console.log(`✅ Wrote patch: ${patch}`);
+  
+  // Clean up temporary directories
+  fs.rmSync(oldTempDir, { recursive: true, force: true });
+  fs.rmSync(newTempDir, { recursive: true, force: true });
 }
 
 automation
@@ -747,15 +753,56 @@ automation
   .description('Generate JSON and AsciiDoc documentation for Redpanda configuration properties')
   .option('--tag <tag>', 'Git tag or branch to extract from', 'dev')
   .option('--diff <oldTag>', 'Also diff autogenerated properties from <oldTag> → <tag>')
+  .option('--overrides <path>', 'Optional JSON file with property description overrides')
+  .option('--output-dir <dir>', 'Where to write all generated files', 'modules/reference')
+  .option('--template-property-page <path>', 'Custom Handlebars template for property page layout')
+  .option('--template-property <path>', 'Custom Handlebars template for individual property sections')
+  .option('--template-deprecated <path>', 'Custom Handlebars template for deprecated properties page')
+  .option('--template-deprecated-property <path>', 'Custom Handlebars template for individual deprecated property sections')
   .action((options) => {
     verifyPropertyDependencies();
 
     const newTag = options.tag;
     const oldTag = options.diff;
+    const overridesPath = options.overrides;
+    const outputDir = options.outputDir;
     const cwd = path.resolve(__dirname, '../tools/property-extractor');
-    const make = (tag) => {
-      console.log(`⏳ Building property docs for ${tag}…`);
-      const r = spawnSync('make', ['build', `TAG=${tag}`], { cwd, stdio: 'inherit' });
+    
+    const make = (tag, overrides, templates = {}, outputDir = 'modules/reference/', tempDir = null) => {
+      console.log(`⏳ Building property docs for ${tag}${tempDir ? ' (for diff)' : ''}…`);
+      const args = ['build', `TAG=${tag}`];
+      
+      // Pass all paths as environment variables for consistency
+      const env = { ...process.env };
+      if (overrides) {
+        env.OVERRIDES = path.resolve(overrides);
+      }
+      if (templates.propertyPage) {
+        env.TEMPLATE_PROPERTY_PAGE = path.resolve(templates.propertyPage);
+      }
+      if (templates.property) {
+        env.TEMPLATE_PROPERTY = path.resolve(templates.property);
+      }
+      if (templates.deprecated) {
+        env.TEMPLATE_DEPRECATED = path.resolve(templates.deprecated);
+      }
+      if (templates.deprecatedProperty) {
+        env.TEMPLATE_DEPRECATED_PROPERTY = path.resolve(templates.deprecatedProperty);
+      }
+      
+      if (tempDir) {
+        // For diff purposes, generate to temporary directory
+        env.OUTPUT_ASCIIDOC_DIR = path.resolve(tempDir);
+        env.OUTPUT_JSON_DIR = path.resolve(tempDir, 'examples');
+        env.OUTPUT_AUTOGENERATED_DIR = path.resolve(tempDir);
+      } else {
+        // Normal generation - go directly to final destination
+        // Let Makefile calculate OUTPUT_ASCIIDOC_DIR as OUTPUT_AUTOGENERATED_DIR/pages
+        env.OUTPUT_JSON_DIR = path.resolve(outputDir, 'examples');
+        env.OUTPUT_AUTOGENERATED_DIR = path.resolve(outputDir);
+      }
+      
+      const r = spawnSync('make', args, { cwd, stdio: 'inherit', env });
       if (r.error) {
         console.error(`❌ ${r.error.message}`);
         process.exit(1);
@@ -763,15 +810,38 @@ automation
       if (r.status !== 0) process.exit(r.status);
     };
 
+    // Collect template options
+    const templates = {
+      propertyPage: options.templatePropertyPage,
+      property: options.templateProperty,
+      deprecated: options.templateDeprecated,
+      deprecatedProperty: options.templateDeprecatedProperty
+    };
+
+    let oldTempDir = null;
+    let newTempDir = null;
+
     if (oldTag) {
-      const oldDir = path.join('autogenerated', oldTag, 'properties');
-      if (!fs.existsSync(oldDir)) make(oldTag);
+      // Generate old version to temporary directory for diff
+      oldTempDir = path.join('tmp', 'diff', `${oldTag}-properties`);
+      fs.mkdirSync(oldTempDir, { recursive: true });
+      make(oldTag, overridesPath, templates, outputDir, oldTempDir);
     }
 
-    make(newTag);
-
     if (oldTag) {
-      diffDirs('properties', oldTag, newTag);
+      // Generate new version to temporary directory for diff
+      newTempDir = path.join('tmp', 'diff', `${newTag}-properties`);
+      fs.mkdirSync(newTempDir, { recursive: true });
+      make(newTag, overridesPath, templates, outputDir, newTempDir);
+      
+      // Then generate new version to final destination
+      make(newTag, overridesPath, templates, outputDir);
+      
+      // Compare the temporary directories
+      diffDirs('properties', oldTag, newTag, oldTempDir, newTempDir);
+    } else {
+      // No diff requested, just generate to final destination
+      make(newTag, overridesPath, templates, outputDir);
     }
 
     process.exit(0);

package/package.json

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

package/tools/property-extractor/Makefile

@@ -1,16 +1,28 @@
 .PHONY: build venv clean redpanda-git treesitter generate-docs check
 
+# --- Main build: venv, fetch code, build parser, extract & docgen ---
+build: venv redpanda-git treesitter
+	@echo "🔧 Building with Redpanda tag: $(TAG)"
+	@mkdir -p $(TOOL_ROOT)/gen
+	@cd $(TOOL_ROOT) && \
+	  $(PYTHON) -W ignore::FutureWarning property_extractor.py \
+	    --recursive \
+	    --path $(REDPANDA_SRC) \
+	    --output gen/properties-output.json
+	@echo "✅ Cluster properties JSON generated at $(TOOL_ROOT)/gen/properties-output.json"
+	@$(MAKE) generate-docs
+
 # Default tag (can be overridden via `make TAG=v25.1.1`)
 TAG       ?= dev
 
 # Derive a “major.minor” or rc identifier from TAG for folder naming
 VERSION := $(shell \
   if echo "$(TAG)" | grep -qE '^v?[0-9]+\.[0-9]+'; then \
-    echo "$(TAG)" \
-      | sed -E 's/^v?([0-9]+\.[0-9]+)(\.[0-9]+)?(-rc[0-9]+)?.*/\1\3/' \
-      | sed 's/-rc/rc/'; \
+	echo "$(TAG)" \
+	  | sed -E 's/^v?([0-9]+\.[0-9]+)(\.[0-9]+)?(-rc[0-9]+)?.*/\1\3/' \
+	  | sed 's/-rc/rc/'; \
   else \
-    echo "$(TAG)"; \
+	echo "$(TAG)"; \
   fi)
 
 # Paths
@@ -22,19 +34,31 @@ REDPANDA_SRC  := $(TMP_ROOT)/redpanda
 TREESITTER_DIR:= $(TOOL_ROOT)/tree-sitter/tree-sitter-cpp
 VENV          := $(TOOL_ROOT)/tmp/redpanda-property-extractor-venv
 PYTHON        := $(VENV)/bin/python
-OUTPUT_DIR    := $(REPO_ROOT)/autogenerated/$(TAG)/properties
 TREE_SITTER   := npx tree-sitter
 
+# Output directory configuration (can be overridden by environment variables)
+OUTPUT_AUTOGENERATED_DIR ?= $(REPO_ROOT)/modules/reference
+OUTPUT_ASCIIDOC_DIR      ?= $(OUTPUT_AUTOGENERATED_DIR)/pages
+OUTPUT_JSON_DIR          ?= $(OUTPUT_AUTOGENERATED_DIR)/examples
+
 # --- Main build: venv, fetch code, build parser, extract & docgen ---
 build: venv redpanda-git treesitter
 	@echo "🔧 Building with Redpanda tag: $(TAG)"
 	@mkdir -p $(TOOL_ROOT)/gen
+	@if [ -n "$(OVERRIDES)" ] && [ ! -f "$(OVERRIDES)" ]; then \
+	  echo "❌ Error: Overrides file '$(OVERRIDES)' does not exist."; \
+	  echo "   Please check the path or omit the OVERRIDES variable to continue without overrides."; \
+	  exit 1; \
+	fi
 	@cd $(TOOL_ROOT) && \
 	  $(PYTHON) -W ignore::FutureWarning property_extractor.py \
-	    --recursive \
-	    --path $(REDPANDA_SRC) \
-	    --output gen/properties-output.json
+		--recursive \
+		--path $(REDPANDA_SRC) \
+		--output gen/properties-output.json \
+		--enhanced-output gen/$(TAG)-properties.json \
+		$(if $(OVERRIDES),$(if $(shell [ -f "$(OVERRIDES)" ] && echo exists),--overrides $(OVERRIDES),),)
 	@echo "✅ JSON generated at $(TOOL_ROOT)/gen/properties-output.json"
+	@echo "✅ Enhanced JSON (with overrides) generated at $(TOOL_ROOT)/gen/$(TAG)-properties.json"
 	@$(MAKE) generate-docs
 
 # --- Ensure Python venv & dependencies ---
@@ -84,22 +108,38 @@ treesitter:
 	@echo "🔧 Generating parser in $(TREESITTER_DIR)…"
 	@cd "$(TREESITTER_DIR)" && npm install --silent && $(TREE_SITTER) generate
 
-# --- Turn the JSON into AsciiDoc pages under autogen/<version>/properties ---
-generate-docs:
-	@echo "📝 Generating AsciiDoc pages in $(OUTPUT_DIR)…"
-	@mkdir -p "$(OUTPUT_DIR)"
-	@cd $(TOOL_ROOT) && \
-	  $(PYTHON) json-to-asciidoc/generate_docs.py --output-dir "$(OUTPUT_DIR)"
-	@echo "📄 Copying properties-output.json to $(OUTPUT_DIR)…"
-	@cp "$(TOOL_ROOT)/gen/properties-output.json" "$(OUTPUT_DIR)/"
-	@echo "✅ Docs generated at $(OUTPUT_DIR)"
+# --- Install Node.js dependencies for Handlebars ---
+node-deps:
+	@echo "📦 Installing Node.js dependencies…"
+	@cd $(TOOL_ROOT) && npm install --silent
+
+# --- Turn the JSON into AsciiDoc pages under the specified output directories ---
+generate-docs: node-deps
+	@echo "📝 Generating AsciiDoc pages in $(OUTPUT_ASCIIDOC_DIR)…"
+	@mkdir -p "$(OUTPUT_ASCIIDOC_DIR)"
+	@mkdir -p "$(OUTPUT_JSON_DIR)"
+	@# Use the enhanced properties file (with overrides) for documentation generation if it exists
+	@if [ -f "$(TOOL_ROOT)/gen/$(TAG)-properties.json" ]; then \
+	  cd $(TOOL_ROOT) && \
+	    node generate-handlebars-docs.js "gen/$(TAG)-properties.json" "$(OUTPUT_AUTOGENERATED_DIR)"; \
+	else \
+	  cd $(TOOL_ROOT) && \
+	    node generate-handlebars-docs.js "gen/properties-output.json" "$(OUTPUT_AUTOGENERATED_DIR)"; \
+	fi
+	@echo "📄 Copying properties JSON files to $(OUTPUT_JSON_DIR)…"
+	@if [ -f "$(TOOL_ROOT)/gen/$(TAG)-properties.json" ]; then \
+	  cp "$(TOOL_ROOT)/gen/$(TAG)-properties.json" "$(OUTPUT_JSON_DIR)/"; \
+	fi
+	@echo "✅ Docs generated at $(OUTPUT_AUTOGENERATED_DIR)"
 
 # --- Debug helper to print all the key paths/vars ---
 check:
-	@echo "MODULE_ROOT:   $(MODULE_ROOT)"
-	@echo "TOOL_ROOT:     $(TOOL_ROOT)"
-	@echo "REDPANDA_SRC:  $(REDPANDA_SRC)"
-	@echo "TREESITTER:    $(TREESITTER_DIR)"
-	@echo "VENV:          $(VENV)"
-	@echo "PYTHON:        $(PYTHON)"
-	@echo "OUTPUT_DIR:    $(OUTPUT_DIR)"
+	@echo "MODULE_ROOT:              $(MODULE_ROOT)"
+	@echo "TOOL_ROOT:                $(TOOL_ROOT)"
+	@echo "REDPANDA_SRC:             $(REDPANDA_SRC)"
+	@echo "TREESITTER:               $(TREESITTER_DIR)"
+	@echo "VENV:                     $(VENV)"
+	@echo "PYTHON:                   $(PYTHON)"
+	@echo "OUTPUT_ASCIIDOC_DIR:      $(OUTPUT_ASCIIDOC_DIR)"
+	@echo "OUTPUT_JSON_DIR:          $(OUTPUT_JSON_DIR)"
+	@echo "OUTPUT_AUTOGENERATED_DIR: $(OUTPUT_AUTOGENERATED_DIR)"

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

@@ -0,0 +1,344 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const handlebars = require('handlebars');
+const helpers = require('./helpers');
+
+// Register all helpers
+Object.entries(helpers).forEach(([name, fn]) => {
+  if (typeof fn !== 'function') {
+    console.error(`❌ Helper "${name}" is not a function`);
+    process.exit(1);
+  }
+  handlebars.registerHelper(name, fn);
+});
+
+/**
+ * Configuration mapping for different property types
+ */
+const PROPERTY_CONFIG = {
+  broker: {
+    pageTitle: 'Broker Configuration Properties',
+    pageAliases: ['reference:node-properties.adoc', 'reference:node-configuration-sample.adoc'],
+    description: 'Reference of broker configuration properties.',
+    intro: `Broker configuration properties are applied individually to each broker in a cluster. You can find and modify these properties in the \`redpanda.yaml\` configuration file.
+
+For information on how to edit broker properties, see xref:manage:cluster-maintenance/node-property-configuration.adoc[].
+
+NOTE: All broker properties require that you restart Redpanda for any update to take effect.`,
+    sectionTitle: 'Broker configuration',
+    groups: [
+      {
+        filter: (prop) => prop.config_scope === 'broker' && !prop.is_deprecated
+      }
+    ],
+    filename: 'broker-properties.adoc'
+  },
+  cluster: {
+    pageTitle: 'Cluster Configuration Properties',
+    pageAliases: ['reference:tunable-properties.adoc', 'reference:cluster-properties.adoc'],
+    description: 'Cluster configuration properties list.',
+    intro: `Cluster configuration properties are the same for all brokers in a cluster, and are set at the cluster level.
+
+For information on how to edit cluster properties, see xref:manage:cluster-maintenance/cluster-property-configuration.adoc[] or xref:manage:kubernetes/k-cluster-property-configuration.adoc[].
+
+NOTE: Some cluster properties require that you restart the cluster for any updates to take effect. See the specific property details to identify whether or not a restart is required.`,
+    sectionTitle: 'Cluster configuration',
+    groups: [
+      {
+        filter: (prop) => prop.config_scope === 'cluster' && !prop.is_deprecated
+      }
+    ],
+    filename: 'cluster-properties.adoc'
+  },
+  'object-storage': {
+    pageTitle: 'Object Storage Properties',
+    description: 'Reference of object storage properties.',
+    intro: `Object storage properties are a type of cluster property. For information on how to edit cluster properties, see xref:manage:cluster-maintenance/cluster-property-configuration.adoc[].
+
+NOTE: Some object storage properties require that you restart the cluster for any updates to take effect. See the specific property details to identify whether or not a restart is required.`,
+    sectionTitle: 'Object storage configuration',
+    sectionIntro: 'Object storage properties should only be set if you enable xref:manage:tiered-storage.adoc[Tiered Storage].',
+    groups: [
+      {
+        filter: (prop) => prop.name && (
+          prop.name.includes('cloud_storage') ||
+          prop.name.includes('s3_') ||
+          prop.name.includes('azure_') ||
+          prop.name.includes('gcs_') ||
+          prop.name.includes('archival_') ||
+          prop.name.includes('remote_') ||
+          prop.name.includes('tiered_')
+        ) && !prop.is_deprecated
+      }
+    ],
+    filename: 'object-storage-properties.adoc'
+  },
+  topic: {
+    pageTitle: 'Topic Configuration Properties',
+    pageAliases: ['reference:topic-properties.adoc'],
+    description: 'Reference of topic configuration properties.',
+    intro: `A topic-level property sets a Redpanda or Kafka configuration for a particular topic.
+
+Many topic-level properties have corresponding xref:manage:cluster-maintenance/cluster-property-configuration.adoc[cluster properties] that set a default value for all topics of a cluster. To customize the value for a topic, you can set a topic-level property that overrides the value of the corresponding cluster property.
+
+NOTE: All topic properties take effect immediately after being set.`,
+    sectionTitle: 'Topic configuration',
+    groups: [
+      {
+        filter: (prop) => prop.config_scope === 'topic' && !prop.is_deprecated,
+        template: 'topic-property'
+      }
+    ],
+    filename: 'topic-properties.adoc'
+  }
+};
+
+// "src/v/kafka/server/handlers/topics/types.cc": "topic"
+
+/**
+ * Gets template path, checking environment variables for custom paths first
+ */
+function getTemplatePath(defaultPath, envVar) {
+  const customPath = process.env[envVar];
+  if (customPath && fs.existsSync(customPath)) {
+    console.log(`📄 Using custom template: ${customPath}`);
+    return customPath;
+  }
+  return defaultPath;
+}
+
+/**
+ * Registers Handlebars partials from template files
+ */
+function registerPartials() {
+  const templatesDir = path.join(__dirname, 'templates');
+  
+  // Register property partial
+  const propertyTemplatePath = getTemplatePath(
+    path.join(templatesDir, 'property.hbs'),
+    'TEMPLATE_PROPERTY'
+  );
+  const propertyTemplate = fs.readFileSync(propertyTemplatePath, 'utf8');
+  handlebars.registerPartial('property', propertyTemplate);
+  
+  // Register topic property partial
+  const topicPropertyTemplatePath = getTemplatePath(
+    path.join(templatesDir, 'topic-property.hbs'),
+    'TEMPLATE_TOPIC_PROPERTY'
+  );
+  const topicPropertyTemplate = fs.readFileSync(topicPropertyTemplatePath, 'utf8');
+  handlebars.registerPartial('topic-property', topicPropertyTemplate);
+  
+  // Register deprecated property partial
+  const deprecatedPropertyTemplatePath = getTemplatePath(
+    path.join(templatesDir, 'deprecated-property.hbs'),
+    'TEMPLATE_DEPRECATED_PROPERTY'
+  );
+  const deprecatedPropertyTemplate = fs.readFileSync(deprecatedPropertyTemplatePath, 'utf8');
+  handlebars.registerPartial('deprecated-property', deprecatedPropertyTemplate);
+}
+
+/**
+ * Generates documentation for a specific property type
+ */
+function generatePropertyDocs(properties, config, outputDir) {
+  const templatePath = getTemplatePath(
+    path.join(__dirname, 'templates', 'property-page.hbs'),
+    'TEMPLATE_PROPERTY_PAGE'
+  );
+  const template = handlebars.compile(fs.readFileSync(templatePath, 'utf8'));
+
+  // Filter and group properties according to configuration
+  const groups = config.groups.map(group => {
+    const filteredProperties = Object.values(properties)
+      .filter(prop => group.filter(prop))
+      .sort((a, b) => String(a.name || '').localeCompare(String(b.name || '')));
+
+    return {
+      title: group.title,
+      intro: group.intro,
+      properties: filteredProperties,
+      template: group.template || 'property' // Default to 'property' template
+    };
+  }).filter(group => group.properties.length > 0);
+
+  const data = {
+    ...config,
+    groups
+  };
+
+  const output = template(data);
+  const outputPath = path.join(outputDir, config.filename);
+  
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, output, 'utf8');
+  
+  console.log(`✅ Generated ${outputPath}`);
+  return groups.reduce((total, group) => total + group.properties.length, 0);
+}
+
+/**
+ * Generates deprecated properties documentation
+ */
+function generateDeprecatedDocs(properties, outputDir) {
+  const templatePath = getTemplatePath(
+    path.join(__dirname, 'templates', 'deprecated-properties.hbs'),
+    'TEMPLATE_DEPRECATED'
+  );
+  const template = handlebars.compile(fs.readFileSync(templatePath, 'utf8'));
+
+  const deprecatedProperties = Object.values(properties).filter(prop => prop.is_deprecated);
+  
+  const brokerProperties = deprecatedProperties
+    .filter(prop => prop.config_scope === 'broker')
+    .sort((a, b) => String(a.name || '').localeCompare(String(b.name || '')));
+    
+  const clusterProperties = deprecatedProperties
+    .filter(prop => prop.config_scope === 'cluster')
+    .sort((a, b) => String(a.name || '').localeCompare(String(b.name || '')));
+
+  const data = {
+    deprecated: deprecatedProperties.length > 0,
+    brokerProperties: brokerProperties.length > 0 ? brokerProperties : null,
+    clusterProperties: clusterProperties.length > 0 ? clusterProperties : null
+  };
+
+  const output = template(data);
+  const outputPath = path.join(outputDir, 'deprecated', 'partials', 'deprecated-properties.adoc');
+  
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, output, 'utf8');
+  
+  console.log(`✅ Generated ${outputPath}`);
+  return deprecatedProperties.length;
+}
+
+/**
+ * Main function to generate all property documentation
+ */
+function generateAllDocs(inputFile, outputDir) {
+  // Register partials
+  registerPartials();
+
+  // Read input JSON
+  const data = JSON.parse(fs.readFileSync(inputFile, 'utf8'));
+  const properties = data.properties || {};
+
+  let totalProperties = 0;
+  let totalBrokerProperties = 0;
+  let totalClusterProperties = 0;
+  let totalObjectStorageProperties = 0;
+  let totalTopicProperties = 0;
+
+  // Generate each type of documentation
+  for (const [type, config] of Object.entries(PROPERTY_CONFIG)) {
+    const count = generatePropertyDocs(properties, config, path.join(outputDir, 'pages'));
+    totalProperties += count;
+    
+    if (type === 'broker') totalBrokerProperties = count;
+    else if (type === 'cluster') totalClusterProperties = count;
+    else if (type === 'object-storage') totalObjectStorageProperties = count;
+    else if (type === 'topic') totalTopicProperties = count;
+  }
+
+  // Generate deprecated properties documentation
+  const deprecatedCount = generateDeprecatedDocs(properties, path.join(outputDir, 'pages'));
+
+  // Generate summary file
+  const allPropertiesContent = Object.keys(properties).sort().join('\n');
+  fs.writeFileSync(path.join(outputDir, 'all_properties.txt'), allPropertiesContent, 'utf8');
+
+  // Generate error reports
+  generateErrorReports(properties, outputDir);
+
+  console.log(`📊 Generation Summary:`);
+  console.log(`   Total properties read: ${Object.keys(properties).length}`);
+  console.log(`   Total Broker properties: ${totalBrokerProperties}`);
+  console.log(`   Total Cluster properties: ${totalClusterProperties}`);
+  console.log(`   Total Object Storage properties: ${totalObjectStorageProperties}`);
+  console.log(`   Total Topic properties: ${totalTopicProperties}`);
+  console.log(`   Total Deprecated properties: ${deprecatedCount}`);
+
+  return {
+    totalProperties: Object.keys(properties).length,
+    brokerProperties: totalBrokerProperties,
+    clusterProperties: totalClusterProperties,
+    objectStorageProperties: totalObjectStorageProperties,
+    topicProperties: totalTopicProperties,
+    deprecatedProperties: deprecatedCount
+  };
+}
+
+/**
+ * Generate error reports for properties with missing or invalid data
+ */
+function generateErrorReports(properties, outputDir) {
+  const errorDir = path.join(outputDir, 'error');
+  fs.mkdirSync(errorDir, { recursive: true });
+
+  const emptyDescriptions = [];
+  const deprecatedProperties = [];
+
+  Object.values(properties).forEach(prop => {
+    if (!prop.description || prop.description.trim() === '') {
+      emptyDescriptions.push(prop.name);
+    }
+    if (prop.is_deprecated) {
+      deprecatedProperties.push(prop.name);
+    }
+  });
+
+  // Write error reports
+  if (emptyDescriptions.length > 0) {
+    fs.writeFileSync(
+      path.join(errorDir, 'empty_description.txt'),
+      emptyDescriptions.join('\n'),
+      'utf8'
+    );
+    const percentage = ((emptyDescriptions.length / Object.keys(properties).length) * 100).toFixed(2);
+    console.log(`You have ${emptyDescriptions.length} properties with empty description. Percentage of errors: ${percentage}%. Data written in 'empty_description.txt'.`);
+  }
+
+  if (deprecatedProperties.length > 0) {
+    fs.writeFileSync(
+      path.join(errorDir, 'deprecated_properties.txt'),
+      deprecatedProperties.join('\n'),
+      'utf8'
+    );
+    const percentage = ((deprecatedProperties.length / Object.keys(properties).length) * 100).toFixed(2);
+    console.log(`You have ${deprecatedProperties.length} deprecated properties. Percentage of errors: ${percentage}%. Data written in 'deprecated_properties.txt'.`);
+  }
+}
+
+module.exports = {
+  generateAllDocs,
+  generatePropertyDocs,
+  generateDeprecatedDocs,
+  PROPERTY_CONFIG
+};
+
+// CLI interface
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  if (args.length < 2) {
+    console.error('Usage: node generate-handlebars-docs.js <input-file> <output-dir>');
+    process.exit(1);
+  }
+
+  const [inputFile, outputDir] = args;
+  
+  if (!fs.existsSync(inputFile)) {
+    console.error(`❌ Input file not found: ${inputFile}`);
+    process.exit(1);
+  }
+
+  try {
+    generateAllDocs(inputFile, outputDir);
+    console.log('✅ Documentation generation completed successfully');
+  } catch (error) {
+    console.error(`❌ Error generating documentation: ${error.message}`);
+    process.exit(1);
+  }
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Handlebars helper for logical AND
+ * @param {...*} args - Values to check
+ * @returns {boolean} True if all values are truthy per JavaScript semantics
+ */
+module.exports = function and(...args) {
+  // Remove the last argument which is the Handlebars options object
+  const values = args.slice(0, -1);
+  return values.every(val => Boolean(val));
+};

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

@@ -0,0 +1,9 @@
+/**
+ * Handlebars helper for equality comparison
+ * @param {*} a - First value
+ * @param {*} b - Second value
+ * @returns {boolean} True if values are equal
+ */
+module.exports = function eq(a, b) {
+  return a === b;
+};