@redpanda-data/docs-extensions-and-macros 4.15.7 → 4.15.9

package/package.json

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

package/tools/property-extractor/property_extractor.py

@@ -991,6 +991,14 @@ def _apply_override_to_existing_property(property_dict, override, overrides_file
     if "category" in override:
         property_dict["category"] = override["category"]
 
+    # Apply accepted_values override - replaces enum field to filter displayed values
+    # Use case: Exclude internal-only enum values (e.g., greedy mode for leader_balancer_mode)
+    if "accepted_values" in override:
+        if isinstance(override["accepted_values"], list):
+            property_dict["enum"] = override["accepted_values"]
+        else:
+            logger.warning(f"accepted_values for property must be an array")
+
 
 def _create_property_from_override(prop_name, override, overrides_file_path):
     """Create a new property from override specification."""
@@ -1025,9 +1033,10 @@ def _create_property_from_override(prop_name, override, overrides_file_path):
     
     # Add any other custom fields from override
     for key, value in override.items():
-        if key not in ["description", "type", "default", "config_scope", "version", 
-                       "example", "example_file", "example_yaml", "related_topics", 
-                       "is_deprecated", "visibility"]:
+        if key not in ["description", "type", "default", "config_scope", "version",
+                       "example", "example_file", "example_yaml", "related_topics",
+                       "is_deprecated", "visibility", "exclude_from_docs", "category",
+                       "accepted_values", "_comment"]:
             new_property[key] = value
 
     # Add exclude_from_docs if specified
@@ -1037,7 +1046,14 @@ def _create_property_from_override(prop_name, override, overrides_file_path):
     # Add category if specified
     if "category" in override:
         new_property["category"] = override["category"]
-    
+
+    # Add accepted_values as enum field if specified
+    if "accepted_values" in override:
+        if isinstance(override["accepted_values"], list):
+            new_property["enum"] = override["accepted_values"]
+        else:
+            logger.warning(f"accepted_values for property '{prop_name}' must be an array")
+
     return new_property
 
 

package/tools/redpanda-connect/connector-binary-analyzer.js

@@ -247,6 +247,7 @@ function getConnectorList(binaryPath) {
 
     let result;
     if (needsDocker) {
+      console.log(`   Using Docker to run Linux binary on ${os.platform()}`);
       // Use Docker to run Linux binaries on macOS/Windows
       const binaryDir = path.dirname(binaryPath);
       const binaryFile = path.basename(binaryPath);
@@ -268,6 +269,7 @@ function getConnectorList(binaryPath) {
         maxBuffer: 10 * 1024 * 1024 // 10MB buffer
       });
     } else {
+      console.log(`   Running natively on ${os.platform()}`);
       // Run natively
       result = spawnSync(binaryPath, ['list', '--format', 'json-full'], {
         stdio: ['ignore', 'pipe', 'ignore'],

package/tools/redpanda-connect/generate-rpcn-connector-docs.js

@@ -472,6 +472,28 @@ async function generateRpcnConnectorDocs(options) {
       if (!Array.isArray(items)) continue;
       const outRoot = path.join(outputRoot, folder);
       fs.mkdirSync(outRoot, { recursive: true });
+
+      // Get current item names
+      const currentNames = new Set(items.filter(fn => fn.name).map(fn => fn.name));
+
+      // Delete partials that no longer exist in the data
+      if (fs.existsSync(outRoot)) {
+        const existingFiles = fs.readdirSync(outRoot).filter(f => f.endsWith('.adoc'));
+        for (const file of existingFiles) {
+          const name = file.replace('.adoc', '');
+          // Skip hand-authored files (by convention, start with underscore)
+          if (name.startsWith('_')) {
+            console.log(`Skipping hand-authored file: ${file}`);
+            continue;
+          }
+          if (!currentNames.has(name)) {
+            const filePath = path.join(outRoot, file);
+            fs.unlinkSync(filePath);
+            console.log(`Deleted removed ${folder} partial: ${file}`);
+          }
+        }
+      }
+
       // Use custom or default template
       const bloblangTemplatePath = templateBloblang || path.resolve(__dirname, './templates/bloblang-function.hbs');
       const bloblangTemplate = handlebars.compile(fs.readFileSync(bloblangTemplatePath, 'utf8'));
@@ -484,6 +506,71 @@ async function generateRpcnConnectorDocs(options) {
         partialFiles.push(path.relative(process.cwd(), outPath));
       }
     }
+
+    // Generate overview pages for Bloblang methods and functions
+    const guidesRoot = path.join(process.cwd(), 'modules/guides/pages/bloblang');
+    fs.mkdirSync(guidesRoot, { recursive: true });
+
+    // Generate methods.adoc with categorized methods
+    if (dataObj['bloblang-methods']) {
+      const methodsData = dataObj['bloblang-methods'];
+      const categoriesMap = new Map();
+
+      // Extract categories and their methods
+      for (const method of methodsData) {
+        if (!method.name || !method.categories || !Array.isArray(method.categories)) continue;
+
+        for (const cat of method.categories) {
+          const categoryName = cat.Category;
+          if (!categoryName) continue;
+
+          if (!categoriesMap.has(categoryName)) {
+            categoriesMap.set(categoryName, []);
+          }
+          categoriesMap.get(categoryName).push(method.name);
+        }
+      }
+
+      // Sort categories and prepare data for template
+      const categories = Array.from(categoriesMap.entries())
+        .map(([name, methods]) => ({
+          name,
+          methods: methods.sort()
+        }))
+        .sort((a, b) => {
+          // Special ordering: General first, Deprecated last
+          if (a.name === 'General') return -1;
+          if (b.name === 'General') return 1;
+          if (a.name === 'Deprecated') return 1;
+          if (b.name === 'Deprecated') return -1;
+          return a.name.localeCompare(b.name);
+        });
+
+      const methodsTemplatePath = path.resolve(__dirname, './templates/bloblang-methods-overview.hbs');
+      const methodsTemplate = handlebars.compile(fs.readFileSync(methodsTemplatePath, 'utf8'));
+      const methodsAdoc = methodsTemplate({ categories });
+      const methodsOutPath = path.join(guidesRoot, 'methods.adoc');
+      fs.writeFileSync(methodsOutPath, methodsAdoc, 'utf8');
+      console.log('Generated methods.adoc overview page');
+      partialFiles.push(path.relative(process.cwd(), methodsOutPath));
+    }
+
+    // Generate functions.adoc with all functions
+    if (dataObj['bloblang-functions']) {
+      const functionsData = dataObj['bloblang-functions'];
+      const functionNames = functionsData
+        .filter(fn => fn.name)
+        .map(fn => fn.name)
+        .sort();
+
+      const functionsTemplatePath = path.resolve(__dirname, './templates/bloblang-functions-overview.hbs');
+      const functionsTemplate = handlebars.compile(fs.readFileSync(functionsTemplatePath, 'utf8'));
+      const functionsAdoc = functionsTemplate({ functions: functionNames });
+      const functionsOutPath = path.join(guidesRoot, 'functions.adoc');
+      fs.writeFileSync(functionsOutPath, functionsAdoc, 'utf8');
+      console.log('Generated functions.adoc overview page');
+      partialFiles.push(path.relative(process.cwd(), functionsOutPath));
+    }
   }
 
   // Common/Advanced config snippet YAMLs in modules/components/examples

package/tools/redpanda-connect/helpers/bloblangExample.js

@@ -1,10 +1,30 @@
 // Bloblang example formatting helper for Handlebars
 function bloblangExample(example) {
   if (typeof example === 'object' && example !== null && example.mapping) {
+    let leadIn = '';
     let codeBlock = '';
+
+    // Extract summary as lead-in prose (not a comment in code)
     if (example.summary && example.summary.trim()) {
-      codeBlock += `# ${example.summary.trim().replace(/\n/g, '\n# ')}\n\n`;
+      let summary = example.summary.trim();
+
+      // Convert Markdown headings to AsciiDoc
+      // ##### Heading -> ==== Heading (H5 -> H4 in AsciiDoc)
+      summary = summary.replace(/^#####\s+(.+)$/gm, '==== $1');
+      // #### Heading -> === Heading (H4 -> H3 in AsciiDoc)
+      summary = summary.replace(/^####\s+(.+)$/gm, '=== $1');
+      // ### Heading -> == Heading (H3 -> H2 in AsciiDoc)
+      summary = summary.replace(/^###\s+(.+)$/gm, '== $1');
+
+      // Ensure lead-in ends with a colon (replace period/exclamation/question mark if present)
+      if (summary.endsWith('.') || summary.endsWith('!') || summary.endsWith('?')) {
+        summary = summary.slice(0, -1) + ':';
+      } else if (!summary.endsWith(':')) {
+        summary += ':';
+      }
+      leadIn = summary + '\n\n';
     }
+
     if (typeof example.mapping === 'string') {
       codeBlock += example.mapping.trim() + '\n';
     }
@@ -15,7 +35,7 @@ function bloblangExample(example) {
         }
       }
     }
-    return `[,coffeescript]\n----\n${codeBlock.trim()}\n----\n`;
+    return `${leadIn}[,bloblang]\n----\n${codeBlock.trim()}\n----\n`;
   } else {
     let exStr = '';
     if (typeof example === 'string') {
@@ -35,7 +55,7 @@ function bloblangExample(example) {
     } else {
       exStr = String(example);
     }
-    return `[source,coffeescript]\n----\n${exStr}\n----\n`;
+    return `[source,bloblang]\n----\n${exStr}\n----\n`;
   }
 }
 

package/tools/redpanda-connect/helpers/ensurePeriod.js

@@ -0,0 +1,27 @@
+/**
+ * Ensures a text string ends with a period (or other terminal punctuation).
+ * Used for normalizing Bloblang descriptions.
+ *
+ * @param {string} text - The text to process
+ * @returns {string} Text ending with appropriate punctuation
+ */
+function ensurePeriod(text) {
+  if (!text || typeof text !== 'string') {
+    return text;
+  }
+
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return text;
+  }
+
+  // Check if already ends with terminal punctuation
+  if (trimmed.endsWith('.') || trimmed.endsWith('!') || trimmed.endsWith('?')) {
+    return text;
+  }
+
+  // Add period
+  return text.trim() + '.';
+}
+
+module.exports = ensurePeriod;

package/tools/redpanda-connect/helpers/hasOptionalParams.js

@@ -0,0 +1,7 @@
+// Check if any parameters are optional
+function hasOptionalParams(params) {
+  if (!Array.isArray(params)) return false;
+  return params.some(param => param.is_optional);
+}
+
+module.exports = hasOptionalParams;

package/tools/redpanda-connect/helpers/index.js

@@ -17,4 +17,7 @@ module.exports = {
   commonConfig:           require('./commonConfig.js'),
   advancedConfig:         require('./advancedConfig.js'),
   bloblangExample:        require('./bloblangExample.js'),
+  hasOptionalParams:      require('./hasOptionalParams.js'),
+  ensurePeriod:           require('./ensurePeriod.js'),
+  toSentenceCase:         require('./toSentenceCase.js'),
 };

package/tools/redpanda-connect/helpers/toSentenceCase.js

@@ -0,0 +1,69 @@
+'use strict'
+
+/**
+ * Convert a string to sentence case, preserving acronyms and proper nouns
+ * @param {string} text - The text to convert
+ * @returns {string} The text in sentence case
+ */
+function toSentenceCase(text) {
+  if (!text) return ''
+
+  // Map of exact word matches to preserve (case-sensitive)
+  const exactPreserve = new Map([
+    ['geoip', 'GeoIP'],
+    ['GEOIP', 'GeoIP'],
+    ['GeoIP', 'GeoIP']
+  ])
+
+  // List of acronyms to preserve (will be uppercased)
+  const preserveWords = new Set([
+    'SQL',
+    'JSON',
+    'JWT',
+    'XML',
+    'HTML',
+    'URL',
+    'URI',
+    'HTTP',
+    'HTTPS',
+    'TLS',
+    'SSL',
+    'AWS',
+    'GCP',
+    'API',
+    'ID',
+    'UUID',
+    'CSV'
+  ])
+
+  // Split into words
+  const words = text.split(/\s+/)
+
+  return words.map((word, index) => {
+    // Check if word is in exact preserve map first
+    if (exactPreserve.has(word) || exactPreserve.has(word.toLowerCase()) || exactPreserve.has(word.toUpperCase())) {
+      const key = exactPreserve.has(word) ? word : (exactPreserve.has(word.toLowerCase()) ? word.toLowerCase() : word.toUpperCase())
+      return exactPreserve.get(key)
+    }
+
+    // Check if word is in preserve list (case-insensitive check)
+    if (preserveWords.has(word.toUpperCase())) {
+      return word.toUpperCase()
+    }
+
+    // Check if word contains special characters like &
+    if (word === '&') {
+      return word
+    }
+
+    // First word: capitalize first letter, lowercase rest
+    if (index === 0) {
+      return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+    }
+
+    // Subsequent words: lowercase
+    return word.toLowerCase()
+  }).join(' ')
+}
+
+module.exports = toSentenceCase