Add support for saving properties to partials

Author: JakeSCahill

bin/doc-tools.js

@@ -1032,17 +1032,20 @@ automation
 
 automation
   .command('property-docs')
-  .description('Generate JSON and AsciiDoc documentation for Redpanda configuration properties')
+  .description('Generate JSON and AsciiDoc documentation for Redpanda configuration properties. By default, only extracts properties to JSON. Use --generate-partials to create consolidated AsciiDoc partials (including deprecated properties). Use --generate-pages to create complete property pages that include the partials using AsciiDoc includes.')
   .option('--tag <tag>', 'Git tag or branch to extract from', 'dev')
-  .option('--diff <oldTag>', 'Also diff autogenerated properties from <oldTag> → <tag>')
+  .option('--diff <oldTag>', 'Also diff autogenerated properties from <oldTag> to <tag>')
   .option('--overrides <path>', 'Optional JSON file with property description overrides')
   .option('--output-dir <dir>', 'Where to write all generated files', 'modules/reference')
-  .option('--cloud-support', 'Enable cloud support metadata by fetching configuration from the cloudv2 repository (requires GITHUB_TOKEN, GH_TOKEN, or REDPANDA_GITHUB_TOKEN)')
+  .option('--cloud-support', 'Add AsciiDoc tags to generated property docs to indicate which ones are supported in Redpanda Cloud. This data is fetched from the cloudv2 repository so requires a GitHub token with repo permissions. Set the token as an environment variable using GITHUB_TOKEN, GH_TOKEN, or REDPANDA_GITHUB_TOKEN')
   .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-topic-property <path>', 'Custom Handlebars template for individual topic 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')
+  .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')
+  .option('--generate-pages', 'Generate complete property pages that include the partials using AsciiDoc includes')
   .action((options) => {
     verifyPropertyDependencies();
 
@@ -1115,6 +1118,17 @@ automation
         env.OUTPUT_ASCIIDOC_DIR = path.resolve(outputDir, 'pages', 'properties');
       }
 
+      // Set partials generation options
+      if (options.generatePartials) {
+        env.GENERATE_PARTIALS = '1';
+        env.OUTPUT_PARTIALS_DIR = path.resolve(outputDir, options.partialsDir || 'partials');
+      }
+      
+      // Set page generation options
+      if (options.generatePages) {
+        env.GENERATE_PAGES = '1';
+      }
+      
       const r = spawnSync('make', args, { cwd, stdio: 'inherit', env });
       if (r.error) {
         console.error(`❌ ${r.error.message}`);

package-lock.json

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

package.json

@@ -28,6 +28,7 @@ TREE_SITTER   := npx tree-sitter
 OUTPUT_AUTOGENERATED_DIR ?= $(REPO_ROOT)/modules/reference
 OUTPUT_ASCIIDOC_DIR      ?= $(OUTPUT_AUTOGENERATED_DIR)/pages
 OUTPUT_JSON_DIR          ?= $(OUTPUT_AUTOGENERATED_DIR)/examples
+OUTPUT_PARTIALS_DIR      ?= $(OUTPUT_AUTOGENERATED_DIR)/partials
 
 # --- Main build: venv, fetch code, build parser, extract & docgen ---
 build: venv redpanda-git treesitter