@redpanda-data/docs-extensions-and-macros 4.10.6 → 4.10.8

package/bin/doc-tools.js

@@ -4,9 +4,7 @@ const { execSync, spawnSync } = require('child_process');
 const os = require('os');
 const { Command, Option } = require('commander');
 const path = require('path');
-const yaml = require('yaml');
 const fs = require('fs');
-const handlebars = require('handlebars');
 const { determineDocsBranch } = require('../cli-utils/self-managed-docs-branch.js');
 const fetchFromGithub = require('../tools/fetch-from-github.js');
 const { urlToXref } = require('../cli-utils/convert-doc-links.js');
@@ -1031,12 +1029,12 @@ automation
   });
 
 automation
-    .command('property-docs')
+  .command('property-docs')
   .description(
-      'Generate JSON and consolidated AsciiDoc partials for Redpanda configuration properties. ' +
-      'By default, only extracts properties to JSON. Use --generate-partials to create consolidated ' +
-      'AsciiDoc partials (including deprecated properties).'
-    )
+    'Generate JSON and consolidated AsciiDoc partials for Redpanda configuration properties. ' +
+    'By default, only extracts properties to JSON. Use --generate-partials to create consolidated ' +
+    'AsciiDoc partials (including deprecated properties).'
+  )
   .option('--tag <tag>', 'Git tag or branch to extract from', 'dev')
   .option('--diff <oldTag>', 'Also diff autogenerated properties from <oldTag> to <tag>')
   .option('--overrides <path>', 'Optional JSON file with property description overrides')
@@ -1049,14 +1047,12 @@ automation
   .option('--template-deprecated-property <path>', 'Custom Handlebars template for individual deprecated property sections')
   .option('--generate-partials', 'Generate consolidated property partials (cluster-properties.adoc, topic-properties.adoc, etc.) in the partials directory')
   .option('--partials-dir <path>', 'Directory for property partials (relative to output-dir)', 'partials')
-    .action((options) => {
-      verifyPropertyDependencies();
+  .action((options) => {
+    verifyPropertyDependencies();
 
     // Validate cloud support dependencies if requested
     if (options.cloudSupport) {
       console.log('🔍 Validating cloud support dependencies...');
-
-      // Check for GITHUB_TOKEN, GH_TOKEN, or REDPANDA_GITHUB_TOKEN
       const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || process.env.REDPANDA_GITHUB_TOKEN;
       if (!token) {
         console.error('❌ Cloud support requires GITHUB_TOKEN, GH_TOKEN, or REDPANDA_GITHUB_TOKEN environment variable');
@@ -1068,7 +1064,6 @@ automation
         console.error('   Or: export REDPANDA_GITHUB_TOKEN=your_token_here');
         process.exit(1);
       }
-
       console.log('📦 Cloud support enabled - Python dependencies will be validated during execution');
       if (process.env.VIRTUAL_ENV) {
         console.log(`   Using virtual environment: ${process.env.VIRTUAL_ENV}`);
@@ -1077,87 +1072,88 @@ automation
       console.log('✅ GitHub token validated');
     }
 
-      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, overrides, templates = {}, outDir = '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 (options.cloudSupport) {
-          env.CLOUD_SUPPORT = '1';
-        }
-        if (templates.property) {
-          env.TEMPLATE_PROPERTY = path.resolve(templates.property);
-        }
-        if (templates.topicProperty) {
-          env.TEMPLATE_TOPIC_PROPERTY = path.resolve(templates.topicProperty);
-        }
-        if (templates.topicPropertyMappings) {
-          env.TEMPLATE_TOPIC_PROPERTY_MAPPINGS = path.resolve(templates.topicPropertyMappings);
-        }
-        if (templates.deprecated) {
-          env.TEMPLATE_DEPRECATED = path.resolve(templates.deprecated);
-        }
-        if (templates.deprecatedProperty) {
-          env.TEMPLATE_DEPRECATED_PROPERTY = path.resolve(templates.deprecatedProperty);
-        }
-
-        if (tempDir) {
-          env.OUTPUT_JSON_DIR = path.resolve(tempDir, 'examples');
-          env.OUTPUT_AUTOGENERATED_DIR = path.resolve(tempDir);
-        } else {
-          env.OUTPUT_JSON_DIR = path.resolve(outDir, 'examples');
-          env.OUTPUT_AUTOGENERATED_DIR = path.resolve(outDir);
-        }
-
-        // Partials generation options
-        if (options.generatePartials) {
-          env.GENERATE_PARTIALS = '1';
-          env.OUTPUT_PARTIALS_DIR = path.resolve(outDir, options.partialsDir || 'partials');
-        }
-
-        const r = spawnSync('make', args, { cwd, stdio: 'inherit', env });
-        if (r.error) {
-          console.error(`❌ ${r.error.message}`);
-          process.exit(1);
-        }
-        if (r.status !== 0) process.exit(r.status);
-      };
-
-      // Collect template options
-      const templates = {
-        property: options.templateProperty,
-        topicProperty: options.templateTopicProperty,
-        topicPropertyMappings: options.templateTopicPropertyMappings,
-        deprecated: options.templateDeprecated,
-        deprecatedProperty: options.templateDeprecatedProperty,
-      };
-
+    const newTag = options.tag;
+    let oldTag = options.diff;
+    const overridesPath = options.overrides;
+    const outputDir = options.outputDir;
+    const cwd = path.resolve(__dirname, '../tools/property-extractor');
+
+    // If --diff is not provided, try to get the latest-redpanda-tag from Antora attributes
+    if (!oldTag) {
+      oldTag = getAntoraValue('asciidoc.attributes.latest-redpanda-tag');
       if (oldTag) {
-        // Build old version first so its JSON exists for the diff step
-        make(oldTag, overridesPath, templates, outputDir, null);
+        console.log(`Using latest-redpanda-tag from Antora attributes for --diff: ${oldTag}`);
+      } else {
+        console.log('No --diff provided and no latest-redpanda-tag found in Antora attributes. Skipping diff.');
       }
+    }
 
-      // Build new version
-      make(newTag, overridesPath, templates, outputDir, null);
-
-      if (oldTag) {
-  // Generate property comparison report using the JSON now in outputDir/examples
-  generatePropertyComparisonReport(oldTag, newTag, outputDir);
+    const make = (tag, overrides, templates = {}, outDir = 'modules/reference/') => {
+      console.log(`⏳ Building property docs for ${tag}…`);
+      const args = ['build', `TAG=${tag}`];
+      const env = { ...process.env };
+      if (overrides) {
+        env.OVERRIDES = path.resolve(overrides);
+      }
+      if (options.cloudSupport) {
+        env.CLOUD_SUPPORT = '1';
+      }
+      if (templates.property) {
+        env.TEMPLATE_PROPERTY = path.resolve(templates.property);
+      }
+      if (templates.topicProperty) {
+        env.TEMPLATE_TOPIC_PROPERTY = path.resolve(templates.topicProperty);
+      }
+      if (templates.topicPropertyMappings) {
+        env.TEMPLATE_TOPIC_PROPERTY_MAPPINGS = path.resolve(templates.topicPropertyMappings);
+      }
+      if (templates.deprecated) {
+        env.TEMPLATE_DEPRECATED = path.resolve(templates.deprecated);
+      }
+      if (templates.deprecatedProperty) {
+        env.TEMPLATE_DEPRECATED_PROPERTY = path.resolve(templates.deprecatedProperty);
       }
+      env.OUTPUT_JSON_DIR = path.resolve(outDir, 'examples');
+      env.OUTPUT_AUTOGENERATED_DIR = path.resolve(outDir);
+      if (options.generatePartials) {
+        env.GENERATE_PARTIALS = '1';
+        env.OUTPUT_PARTIALS_DIR = path.resolve(outDir, options.partialsDir || 'partials');
+      }
+      const r = spawnSync('make', args, { cwd, stdio: 'inherit', env });
+      if (r.error) {
+        console.error(`❌ ${r.error.message}`);
+        process.exit(1);
+      }
+      if (r.status !== 0) process.exit(r.status);
+    };
+
+    const templates = {
+      property: options.templateProperty,
+      topicProperty: options.templateTopicProperty,
+      topicPropertyMappings: options.templateTopicPropertyMappings,
+      deprecated: options.templateDeprecated,
+      deprecatedProperty: options.templateDeprecatedProperty,
+    };
+
+    const tagsAreSame = oldTag && newTag && oldTag === newTag;
+    if (oldTag && !tagsAreSame) {
+      make(oldTag, overridesPath, templates, outputDir);
+    }
+    make(newTag, overridesPath, templates, outputDir);
+    if (oldTag && !tagsAreSame) {
+      generatePropertyComparisonReport(oldTag, newTag, outputDir);
+    } else if (tagsAreSame) {
+      console.log('--diff and --tag are the same. Skipping diff and Antora config update.');
+    }
 
-      process.exit(0);
-    });
+    // If we used Antora's latest-redpanda-tag for diff, update it to the new tag
+    if (!options.diff && !tagsAreSame) {
+      setAntoraValue('asciidoc.attributes.latest-redpanda-tag', newTag);
+      console.log(`✅ Updated Antora latest-redpanda-tag to: ${newTag}`);
+    }
+
+    process.exit(0);
+  });
 
 automation
   .command('rpk-docs')

package/cli-utils/antora-utils.js

@@ -10,9 +10,17 @@ const yaml = require('js-yaml');
  * @returns {Object|undefined} The parsed YAML as a JavaScript object, or undefined if not found or on error.
  */
 function loadAntoraConfig() {
-  const antoraPath = path.join(process.cwd(), 'antora.yml');
-  if (!fs.existsSync(antoraPath)) {
-    // No antora.yml in project root
+  // Support both antora.yml and antora.yaml
+  const cwd = process.cwd();
+  const ymlPath = path.join(cwd, 'antora.yml');
+  const yamlPath = path.join(cwd, 'antora.yaml');
+  let antoraPath;
+  if (fs.existsSync(ymlPath)) {
+    antoraPath = ymlPath;
+  } else if (fs.existsSync(yamlPath)) {
+    antoraPath = yamlPath;
+  } else {
+    // No antora.yml or antora.yaml in project root
     return undefined;
   }
 
@@ -20,12 +28,12 @@ function loadAntoraConfig() {
     const fileContents = fs.readFileSync(antoraPath, 'utf8');
     const config = yaml.load(fileContents);
     if (typeof config !== 'object' || config === null) {
-      console.error('Warning: antora.yml parsed to a non‐object value.');
+      console.error(`Warning: ${path.basename(antoraPath)} parsed to a non‐object value.`);
       return undefined;
     }
     return config;
   } catch (err) {
-    console.error(`Error reading/parsing antora.yml: ${err.message}`);
+    console.error(`Error reading/parsing ${path.basename(antoraPath)}: ${err.message}`);
     return undefined;
   }
 }
@@ -74,9 +82,17 @@ function getAntoraValue(keyPath) {
  *   True if it succeeded, false otherwise.
  */
 function setAntoraValue(keyPath, newValue) {
-  const antoraPath = path.join(process.cwd(), 'antora.yml');
-  if (!fs.existsSync(antoraPath)) {
-    console.error('Cannot update antora.yml: file not found in project root.');
+  // Support both antora.yml and antora.yaml
+  const cwd = process.cwd();
+  const ymlPath = path.join(cwd, 'antora.yml');
+  const yamlPath = path.join(cwd, 'antora.yaml');
+  let antoraPath;
+  if (fs.existsSync(ymlPath)) {
+    antoraPath = ymlPath;
+  } else if (fs.existsSync(yamlPath)) {
+    antoraPath = yamlPath;
+  } else {
+    console.error('Cannot update antora.yml or antora.yaml: file not found in project root.');
     return false;
   }
 
@@ -88,7 +104,7 @@ function setAntoraValue(keyPath, newValue) {
       config = {};
     }
   } catch (err) {
-    console.error(`Error reading/parsing antora.yml: ${err.message}`);
+    console.error(`Error reading/parsing ${path.basename(antoraPath)}: ${err.message}`);
     return false;
   }
 
@@ -115,7 +131,37 @@ function setAntoraValue(keyPath, newValue) {
     fs.writeFileSync(antoraPath, newYaml, 'utf8');
     return true;
   } catch (err) {
-    console.error(`Error writing antora.yml: ${err.message}`);
+    console.error(`Error writing ${path.basename(antoraPath)}: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Look for antora.yml in the current working directory
+ * (the project's root), load it if present, and return
+ * its `prerelease` value (boolean). If missing or on error,
+ * returns false.
+ */
+function getPrereleaseFromAntora() {
+  // Support both antora.yml and antora.yaml
+  const cwd = process.cwd();
+  const ymlPath = path.join(cwd, 'antora.yml');
+  const yamlPath = path.join(cwd, 'antora.yaml');
+  let antoraPath;
+  if (fs.existsSync(ymlPath)) {
+    antoraPath = ymlPath;
+  } else if (fs.existsSync(yamlPath)) {
+    antoraPath = yamlPath;
+  } else {
+    return false;
+  }
+
+  try {
+    const fileContents = fs.readFileSync(antoraPath, 'utf8');
+    const antoraConfig = yaml.load(fileContents);
+    return antoraConfig.prerelease === true;
+  } catch (error) {
+    console.error(`Error reading ${path.basename(antoraPath)}:`, error.message);
     return false;
   }
 }
@@ -124,4 +170,5 @@ module.exports = {
   loadAntoraConfig,
   getAntoraValue,
   setAntoraValue,
+  getPrereleaseFromAntora
 };

package/package.json

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

package/tools/get-console-version.js

@@ -4,7 +4,7 @@ const yaml = require('js-yaml');
 const fs = require('fs');
 const path = require('path');
 const GetLatestConsoleVersion = require('../extensions/version-fetcher/get-latest-console-version.js');
-const { getPrereleaseFromAntora } = require('../cli-utils/beta-from-antora.js');
+const { getPrereleaseFromAntora } = require('../cli-utils/antora-utils.js');
 
 /**
  * Fetches and prints the latest Console version and Docker repo.

package/tools/get-redpanda-version.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 const GetLatestRedpandaVersion = require('../extensions/version-fetcher/get-latest-redpanda-version.js');
-const { getPrereleaseFromAntora } = require('../cli-utils/beta-from-antora.js');
+const { getPrereleaseFromAntora } = require('../cli-utils/antora-utils.js');
 
 /**
  * Fetches and prints the latest Redpanda version and Docker repository.

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

@@ -22,7 +22,7 @@ const helpers = require('./helpers');
  * CLI Usage: node generate-handlebars-docs.js <input-file> <output-dir>
  */
 
-// Register all helpers
+// Register helpers
 Object.entries(helpers).forEach(([name, fn]) => {
   if (typeof fn !== 'function') {
     console.error(`❌ Helper "${name}" is not a function`);
@@ -62,11 +62,6 @@ function getTemplatePath(defaultPath, envVar) {
 
 /**
  * Register Handlebars partials used to render property documentation.
- *
- * Registers:
- *  - "property"
- *  - "topic-property"
- *  - "deprecated-property"
  */
 function registerPartials() {
   const templatesDir = path.join(__dirname, 'templates');
@@ -112,7 +107,7 @@ function registerPartials() {
 /**
  * Generate consolidated AsciiDoc partials for properties grouped by type.
  */
-function generatePropertyPartials(properties, partialsDir) {
+function generatePropertyPartials(properties, partialsDir, onRender) {
   console.log(`📝 Generating consolidated property partials in ${partialsDir}…`);
 
   const propertyTemplate = handlebars.compile(
@@ -129,11 +124,24 @@ function generatePropertyPartials(properties, partialsDir) {
 
   Object.values(properties).forEach(prop => {
     if (!prop.name || !prop.config_scope) return;
-    if (prop.config_scope === 'topic') propertyGroups.topic.push(prop);
-    else if (prop.config_scope === 'broker') propertyGroups.broker.push(prop);
-    else if (prop.config_scope === 'cluster') {
-      if (isObjectStorageProperty(prop)) propertyGroups['object-storage'].push(prop);
-      else propertyGroups.cluster.push(prop);
+
+    switch (prop.config_scope) {
+      case 'topic':
+        propertyGroups.topic.push(prop);
+        break;
+      case 'broker':
+        propertyGroups.broker.push(prop);
+        break;
+      case 'cluster':
+        if (isObjectStorageProperty(prop)) propertyGroups['object-storage'].push(prop);
+        else propertyGroups.cluster.push(prop);
+        break;
+      case 'object-storage':
+        propertyGroups['object-storage'].push(prop);
+        break;
+      default:
+        console.warn(`⚠️ Unknown config_scope: ${prop.config_scope} for ${prop.name}`);
+        break;
     }
   });
 
@@ -143,9 +151,16 @@ function generatePropertyPartials(properties, partialsDir) {
     if (props.length === 0) return;
     props.sort((a, b) => String(a.name || '').localeCompare(String(b.name || '')));
     const selectedTemplate = type === 'topic' ? topicTemplate : propertyTemplate;
-    const content = props.map(p => selectedTemplate(p)).join('\n');
+    const pieces = [];
+    props.forEach(p => {
+      if (typeof onRender === 'function') {
+        try { onRender(p.name); } catch (err) { /* swallow callback errors */ }
+      }
+      pieces.push(selectedTemplate(p));
+    });
+    const content = pieces.join('\n');
     const filename = `${type}-properties.adoc`;
-  fs.writeFileSync(path.join(propertiesPartialsDir, filename), AUTOGEN_NOTICE + content, 'utf8');
+    fs.writeFileSync(path.join(propertiesPartialsDir, filename), AUTOGEN_NOTICE + content, 'utf8');
     console.log(`✅ Generated ${filename} (${props.length} properties)`);
     totalCount += props.length;
   });
@@ -178,19 +193,18 @@ function generateDeprecatedDocs(properties, outputDir) {
     clusterProperties: clusterProperties.length ? clusterProperties : null
   };
 
-  const output = template(data);
   const outputPath = process.env.OUTPUT_PARTIALS_DIR
     ? path.join(process.env.OUTPUT_PARTIALS_DIR, 'deprecated', 'deprecated-properties.adoc')
     : path.join(outputDir, 'partials', 'deprecated', 'deprecated-properties.adoc');
 
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-  fs.writeFileSync(outputPath, AUTOGEN_NOTICE + output, 'utf8');
+  fs.writeFileSync(outputPath, AUTOGEN_NOTICE + template(data), 'utf8');
   console.log(`✅ Generated ${outputPath}`);
   return deprecatedProperties.length;
 }
 
 /**
- * Generate topic-property-mappings.adoc using the mappings template and topic properties.
+ * Generate topic-property-mappings.adoc
  */
 function generateTopicPropertyMappings(properties, partialsDir) {
   const templatesDir = path.join(__dirname, 'templates');
@@ -218,31 +232,42 @@ function generateTopicPropertyMappings(properties, partialsDir) {
 }
 
 /**
- * Generate error reports for missing descriptions and deprecated properties.
+ * Generate error reports for missing descriptions, deprecated, and undocumented properties.
  */
-function generateErrorReports(properties) {
+function generateErrorReports(properties, documentedProperties = []) {
   const emptyDescriptions = [];
   const deprecatedProperties = [];
+  const allKeys = Object.keys(properties);
 
-  Object.values(properties).forEach(p => {
-    if (!p.description || !p.description.trim()) emptyDescriptions.push(p.name);
-    if (p.is_deprecated) deprecatedProperties.push(p.name);
+  // Use documentedProperties array (property names that were rendered into partials)
+  const documentedSet = new Set(documentedProperties);
+  const undocumented = [];
+
+  Object.entries(properties).forEach(([key, p]) => {
+    const name = p.name || key;
+    if (!p.description || !p.description.trim()) emptyDescriptions.push(name);
+    if (p.is_deprecated) deprecatedProperties.push(name);
+    if (!documentedSet.has(name)) undocumented.push(name);
   });
 
-  const total = Object.keys(properties).length;
+  const total = allKeys.length;
   const pctEmpty = total ? ((emptyDescriptions.length / total) * 100).toFixed(2) : '0.00';
   const pctDeprecated = total ? ((deprecatedProperties.length / total) * 100).toFixed(2) : '0.00';
-  console.log(`Empty descriptions: ${emptyDescriptions.length} (${pctEmpty}%)`);
-  console.log(`Deprecated: ${deprecatedProperties.length} (${pctDeprecated}%)`);
+  const pctUndocumented = total ? ((undocumented.length / total) * 100).toFixed(2) : '0.00';
+
+  console.log(`📉 Empty descriptions: ${emptyDescriptions.length} (${pctEmpty}%)`);
+  console.log(`🕸️ Deprecated: ${deprecatedProperties.length} (${pctDeprecated}%)`);
+  console.log(`🚫 Not documented: ${undocumented.length} (${pctUndocumented}%)`);
 
   return {
     empty_descriptions: emptyDescriptions.sort(),
-    deprecated_properties: deprecatedProperties.sort()
+    deprecated_properties: deprecatedProperties.sort(),
+    undocumented_properties: undocumented.sort(),
   };
 }
 
 /**
- * Main generator — only supports partials and deprecated docs.
+ * Main generator
  */
 function generateAllDocs(inputFile, outputDir) {
   const data = JSON.parse(fs.readFileSync(inputFile, 'utf8'));
@@ -252,13 +277,14 @@ function generateAllDocs(inputFile, outputDir) {
 
   let partialsCount = 0;
   let deprecatedCount = 0;
+  const documentedProps = []; // Track which property names were rendered
 
   if (process.env.GENERATE_PARTIALS === '1' && process.env.OUTPUT_PARTIALS_DIR) {
     console.log('📄 Generating property partials and deprecated docs...');
     deprecatedCount = generateDeprecatedDocs(properties, outputDir);
-    partialsCount = generatePropertyPartials(properties, process.env.OUTPUT_PARTIALS_DIR);
 
-    // Generate topic-property-mappings.adoc
+    // Generate property partials using the shared helper and collect names via callback
+    partialsCount = generatePropertyPartials(properties, process.env.OUTPUT_PARTIALS_DIR, name => documentedProps.push(name));
     try {
       generateTopicPropertyMappings(properties, process.env.OUTPUT_PARTIALS_DIR);
     } catch (err) {
@@ -268,24 +294,34 @@ function generateAllDocs(inputFile, outputDir) {
     console.log('📄 Skipping partial generation (set GENERATE_PARTIALS=1 and OUTPUT_PARTIALS_DIR to enable)');
   }
 
-  const errors = generateErrorReports(properties);
-  const inputData = JSON.parse(fs.readFileSync(inputFile, 'utf8'));
-  inputData.empty_descriptions = errors.empty_descriptions;
-  inputData.deprecated_properties = errors.deprecated_properties;
-  fs.writeFileSync(inputFile, JSON.stringify(inputData, null, 2), 'utf8');
+  const errors = generateErrorReports(properties, documentedProps);
 
-  console.log('📊 Summary:');
-  console.log(`   Total properties: ${Object.keys(properties).length}`);
-  console.log(`   Total partials generated: ${partialsCount}`);
-  console.log(`   Deprecated properties: ${deprecatedCount}`);
+  const totalProperties = Object.keys(properties).length;
+  const notRendered = errors.undocumented_properties.length;
+  const pctRendered = totalProperties
+    ? ((partialsCount / totalProperties) * 100).toFixed(2)
+    : '0.00';
+
+  console.log('\n📊 Summary:');
+  console.log(`   Total properties found:      ${totalProperties}`);
+  console.log(`   Property partials generated: ${partialsCount} (${pctRendered}% of total)`);
+  console.log(`   Not documented:              ${notRendered}`);
+  console.log(`   Deprecated properties:       ${deprecatedCount}`);
+
+  if (notRendered > 0) {
+    console.log('⚠️ Undocumented properties:\n   ' + errors.undocumented_properties.join('\n   '));
+  }
 
   return {
-    totalProperties: Object.keys(properties).length,
-    propertyPartials: partialsCount,
-    deprecatedProperties: deprecatedCount
+    totalProperties,
+    generatedPartials: partialsCount,
+    undocumentedProperties: errors.undocumented_properties,
+    deprecatedProperties: deprecatedCount,
+    percentageRendered: pctRendered
   };
 }
 
+
 module.exports = {
   generateAllDocs,
   generateDeprecatedDocs,

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

@@ -0,0 +1,19 @@
+// Returns 'cloud' if all topics are cloud-only, 'self-managed' if all are self-managed-only, else 'normal'
+module.exports = function allTopicsConditional(related_topics) {
+  if (!Array.isArray(related_topics) || related_topics.length === 0) return null;
+  let allCloud = true;
+  let allSelfManaged = true;
+  for (const t of related_topics) {
+    if (typeof t !== 'string') {
+      allCloud = false;
+      allSelfManaged = false;
+      break;
+    }
+    const trimmed = t.trim();
+    if (!trimmed.startsWith('cloud-only:')) allCloud = false;
+    if (!trimmed.startsWith('self-managed-only:')) allSelfManaged = false;
+  }
+  if (allCloud) return 'cloud';
+  if (allSelfManaged) return 'self-managed';
+  return 'normal';
+};

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

@@ -28,6 +28,10 @@ function processDefaults(inputString, suffix) {
     return inputString;
   }
 
+  // Remove C++ digit separators (apostrophes) from numbers/durations
+  // e.g. 30'000ms -> 30000ms, 1'500 -> 1500
+  inputString = inputString.replace(/(?<=\d)'(?=\d)/g, '');
+
   // Test for ip:port in vector: std::vector<net::unresolved_address>({{...}})
   const vectorMatch = inputString.match(/std::vector<net::unresolved_address>\(\{\{("([\d.]+)",\s*(\d+))\}\}\)/);
   if (vectorMatch) {

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

@@ -11,4 +11,6 @@ module.exports = {
   renderPropertyExample: require('./renderPropertyExample.js'),
   formatUnits: require('./formatUnits.js'),
   anchorName: require('./anchorName.js'),
+  parseRelatedTopic: require('./parseRelatedTopic.js'),
+  allTopicsConditional: require('./allTopicsConditional.js'),
 };

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

@@ -0,0 +1,13 @@
+// Returns an object with type and value for a related topic
+// type: 'cloud', 'self-managed', or 'normal'
+module.exports = function parseRelatedTopic(topic) {
+  if (typeof topic !== 'string') return { type: 'normal', value: topic };
+  const trimmed = topic.trim();
+  if (trimmed.startsWith('cloud-only:')) {
+    return { type: 'cloud', value: trimmed.replace(/^cloud-only:/, '').trim() };
+  }
+  if (trimmed.startsWith('self-managed-only:')) {
+    return { type: 'self-managed', value: trimmed.replace(/^self-managed-only:/, '').trim() };
+  }
+  return { type: 'normal', value: trimmed };
+};

package/tools/property-extractor/property_extractor.py

@@ -1010,6 +1010,9 @@ def resolve_type_and_default(properties, definitions):
             processed (str): A string representing the JSON-ready value (for example: '"value"', 'null', '0', or the original input when no mapping applied).
         """
         arg_str = arg_str.strip()
+        # Remove C++ digit separators (apostrophes) that may appear in numeric literals
+        # Example: "30'000ms" -> "30000ms". Use conservative replace only between digits.
+        arg_str = re.sub(r"(?<=\d)'(?=\d)", '', arg_str)
         
         # Handle std::nullopt -> null
         if arg_str == "std::nullopt":
@@ -1023,9 +1026,27 @@ def resolve_type_and_default(properties, definitions):
             resolved_value = resolve_cpp_function_call(function_name)
             if resolved_value is not None:
                 return f'"{resolved_value}"'
+
+        # Handle std::chrono literals like std::chrono::minutes{5} -> "5min"
+        chrono_match = re.match(r'std::chrono::([a-zA-Z]+)\s*\{\s*(\d+)\s*\}', arg_str)
+        if chrono_match:
+            unit = chrono_match.group(1)
+            value = chrono_match.group(2)
+            unit_map = {
+                'hours': 'h',
+                'minutes': 'min',
+                'seconds': 's',
+                'milliseconds': 'ms',
+                'microseconds': 'us',
+                'nanoseconds': 'ns'
+            }
+            short = unit_map.get(unit.lower(), unit)
+            return f'"{value} {short}"'
         
-        # Handle enum-like patterns (such as fips_mode_flag::disabled -> "disabled")
-        enum_match = re.match(r'[a-zA-Z0-9_:]+::([a-zA-Z0-9_]+)', arg_str)
+        # Handle enum-like patterns (such as fips_mode_flag::disabled -> "disabled").
+        # Only treat bare 'X::Y' tokens as enums — do not match when the token
+        # is followed by constructor braces/parentheses (e.g. std::chrono::minutes{5}).
+        enum_match = re.match(r'[a-zA-Z0-9_:]+::([a-zA-Z0-9_]+)\s*$', arg_str)
         if enum_match:
             enum_value = enum_match.group(1)
             return f'"{enum_value}"'

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

@@ -23,6 +23,7 @@ endif::[]
 {{else}}
 
 No description available.
+
 {{/if}}
 {{#if is_enterprise}}
 
@@ -31,9 +32,11 @@ ifndef::env-cloud[]
 endif::[]
 {{/if}}
 {{#if cloud_byoc_only}}
+
 ifdef::env-cloud[]
 NOTE: This property is available only in Redpanda Cloud BYOC deployments.
 endif::[]
+
 {{/if}}
 {{#if units}}
 
@@ -50,6 +53,10 @@ endif::[]
 *Requires restart:* {{#if needs_restart}}Yes{{else}}No{{/if}}
 {{/if}}
 {{/if}}
+
+ifndef::env-cloud[]
+*Restored during xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]:* {{#if (ne gets_restored false)}}Yes{{else}}No{{/if}}
+endif::[]
 {{#if visibility}}
 
 // tag::self-managed-only[]
@@ -89,13 +96,49 @@ endif::[]
 {{{renderPropertyExample this}}}
 {{/if}}
 {{#if related_topics}}
+{{#with (allTopicsConditional related_topics) as |sectionType|}}
+
+{{#if (eq sectionType "cloud")}}
+ifdef::env-cloud[]
+*Related topics:*
+
+{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+endif::[]
+{{else if (eq sectionType "self-managed")}}
+ifndef::env-cloud[]
+*Related topics:*
 
+{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+endif::[]
+{{else}}
 *Related topics:*
 
-{{#each related_topics}}
-* {{{this}}}
+{{#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}}
 {{/if}}
+{{/with}}
+{{/if}}
 {{#if aliases}}
 
 // tag::self-managed-only[]

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

@@ -74,17 +74,57 @@ endif::[]
 {{/if}}
 
 *Nullable:* {{#if nullable}}Yes{{else}}No{{/if}}
+
+ifndef::env-cloud[]
+*Restored during xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]:* {{#if (ne gets_restored false)}}Yes{{else}}No{{/if}}
+endif::[]
 {{#if example}}
 
 {{{renderPropertyExample this}}}
 {{/if}}
 {{#if related_topics}}
+{{#with (allTopicsConditional related_topics) as |sectionType|}}
 
+{{#if (eq sectionType "cloud")}}
+ifdef::env-cloud[]
 *Related topics:*
 
-{{#each related_topics}}
-* {{{this}}}
+{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
 {{/each}}
+endif::[]
+{{else if (eq sectionType "self-managed")}}
+ifndef::env-cloud[]
+*Related topics:*
+
+{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+endif::[]
+{{else}}
+*Related topics:*
+
+{{#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}}
+{{/if}}
+{{/with}}
 {{/if}}
 {{#if aliases}}
 

package/tools/property-extractor/topic_property_extractor.py

@@ -304,11 +304,29 @@ class TopicPropertyExtractor:
             
     def _determine_property_type(self, property_name: str) -> str:
         """Determine the type of a property based on its name and usage patterns"""
-        
-        # Type mapping based on property name patterns
+        # Explicit exceptions / overrides for properties whose name contains
+        # keywords that would otherwise map to boolean but which are actually
+        # string-valued (for example, a bucket name).
+        if property_name == "redpanda.remote.readreplica":
+            # This topic property contains the read-replica bucket identifier
+            # and should be treated as a string (not a boolean).
+            return "string"
+        # Explicit override: iceberg.delete is a boolean (whether to delete
+        # the corresponding Iceberg table when the topic is deleted).
+        if property_name == "redpanda.iceberg.delete":
+            return "boolean"
+
+        # Type mapping based on property name patterns (heuristic)
         if any(keyword in property_name for keyword in ["caching", "recovery", "read", "write", "delete"]):
-            if property_name in ["write.caching", "redpanda.remote.recovery", "redpanda.remote.write", 
-                               "redpanda.remote.read", "redpanda.remote.delete", "redpanda.remote.readreplica"]:
+            # Known boolean topic properties (keep list conservative)
+            boolean_props = [
+                "write.caching",
+                "redpanda.remote.recovery",
+                "redpanda.remote.write",
+                "redpanda.remote.read",
+                "redpanda.remote.delete",
+            ]
+            if property_name in boolean_props:
                 return "boolean"
                 
         elif any(suffix in property_name for suffix in [".bytes", ".ms", ".factor", ".lag.ms"]):
@@ -583,7 +601,8 @@ NOTE: All topic properties take effect immediately after being set.
 *Type:* {prop_type}
 
 """
-            if acceptable_values:
+            # If the property type is boolean, never include an Accepted values section
+            if acceptable_values and str(prop_type).lower() not in ("boolean", "bool"):
                 adoc_content += f"*Accepted values:* {acceptable_values}\n\n"
             
             adoc_content += "*Default:* null\n\n"

package/tools/property-extractor/transformers.py

@@ -145,15 +145,19 @@ class IsArrayTransformer:
 
 class NeedsRestartTransformer:
     def accepts(self, info, file_pair):
-        return True
-    
+        # Only accept when the params blob exists and contains a needs_restart entry
+        return (
+            len(info.get("params", [])) > 2
+            and isinstance(info["params"][2].get("value"), dict)
+            and "needs_restart" in info["params"][2]["value"]
+        )
+
     def parse(self, property, info, file_pair):
-        needs_restart = "yes"
-        if len(info["params"]) > 2 and "needs_restart" in info["params"][2]["value"]:
-            needs_restart = re.sub(
-                r"^.*::", "", info["params"][2]["value"]["needs_restart"]
-            )
-        property["needs_restart"] = needs_restart != "no"  # True by default, unless we find "no"
+        # We only get here if accepts(...) returned True, so the metadata blob is present
+        raw = info["params"][2]["value"]["needs_restart"]
+        flag = re.sub(r"^.*::", "", raw)
+        # Store as boolean; do not set any default when metadata is absent
+        property["needs_restart"] = (flag != "no")
 
 class GetsRestoredTransformer:
     def accepts(self, info, file_pair):

package/cli-utils/beta-from-antora.js

@@ -1,27 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-const yaml = require('js-yaml');
-
-/**
- * Look for antora.yml in the current working directory
- * (the project's root), load it if present, and return
- * its `prerelease` value (boolean). If missing or on error,
- * returns false.
- */
-function getPrereleaseFromAntora() {
-  const antoraPath = path.join(process.cwd(), 'antora.yml');
-  if (!fs.existsSync(antoraPath)) {
-    return false;
-  }
-
-  try {
-    const fileContents = fs.readFileSync(antoraPath, 'utf8');
-    const antoraConfig = yaml.load(fileContents);
-    return antoraConfig.prerelease === true;
-  } catch (error) {
-    console.error('Error reading antora.yml:', error.message);
-    return false;
-  }
-}
-
-module.exports = { getPrereleaseFromAntora };