@redpanda-data/docs-extensions-and-macros 4.6.1 → 4.6.2

package/bin/doc-tools.js

@@ -546,22 +546,27 @@ automation
     }
 
     if (options.draftMissing) {
-      console.log('⏳ Drafting missing connectors...');
+      console.log('⏳ Drafting missing connectors…');
       try {
         const connectorList = await parseCSVConnectors(options.csv, console);
-        const validConnectors = connectorList.filter(row => row.name && row.type);
+        const validConnectors = connectorList.filter(r => r.name && r.type);
 
-        const pagesRoot = path.resolve(process.cwd(), 'modules/components/pages');
+        const roots = {
+          pages:   path.resolve(process.cwd(), 'modules/components/pages'),
+          partials:path.resolve(process.cwd(), 'modules/components/partials/components'),
+        };
+
+        // find any connector that has NO .adoc under pages/TYPEs or partials/TYPEs
         const allMissing = validConnectors.filter(({ name, type }) => {
-          if (!name || !type) {
-            console.warn(`⚠️  Skipping invalid connector entry:`, { name, type });
-            return false;
-          }
-          const expected = path.join(pagesRoot, `${type}s`, `${name}.adoc`);
-          return !fs.existsSync(expected);
+          const relPath = path.join(`${type}s`, `${name}.adoc`);
+          const existsInAny = Object.values(roots).some(root =>
+            fs.existsSync(path.join(root, relPath))
+          );
+          return !existsInAny;
         });
 
-        const missingConnectors = allMissing.filter(({ name }) => !name.includes('sql_driver'));
+        // still skip sql_driver
+        const missingConnectors = allMissing.filter(c => !c.name.includes('sql_driver'));
 
         if (missingConnectors.length === 0) {
           console.log('✅ All connectors (excluding sql_drivers) already have docs—nothing to draft.');
@@ -572,17 +577,20 @@ automation
           });
           console.log('');
 
+          // build your filtered JSON as before…
           const rawData = fs.readFileSync(dataFile, 'utf8');
           const dataObj = JSON.parse(rawData);
-
           const filteredDataObj = {};
+
           for (const [key, arr] of Object.entries(dataObj)) {
             if (!Array.isArray(arr)) {
               filteredDataObj[key] = arr;
               continue;
             }
             filteredDataObj[key] = arr.filter(component =>
-              missingConnectors.some(m => m.name === component.name && `${m.type}s` === key)
+              missingConnectors.some(
+                m => m.name === component.name && `${m.type}s` === key
+              )
             );
           }
 
@@ -590,12 +598,12 @@ automation
           fs.writeFileSync(tempDataPath, JSON.stringify(filteredDataObj, null, 2), 'utf8');
 
           const draftResult = await generateRpcnConnectorDocs({
-            data: tempDataPath,
-            overrides: options.overrides,
-            template: options.templateMain,
-            templateFields: options.templateFields,
-            templateExamples: options.templateExamples,
-            templateIntro: options.templateIntro,
+            data:            tempDataPath,
+            overrides:       options.overrides,
+            template:        options.templateMain,
+            templateFields:  options.templateFields,
+            templateExamples:options.templateExamples,
+            templateIntro:   options.templateIntro,
             writeFullDrafts: true
           });
 

package/package.json

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

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

@@ -185,7 +185,7 @@ async function generateRpcnConnectorDocs(options) {
           partialFiles.push(path.relative(process.cwd(), fPath));
         }
 
-        if (examplesOut.trim()) {
+        if (examplesOut.trim() && type !== 'bloblang-functions' && type !== 'bloblang-methods') {
           const ePath = path.join(examplesOutRoot, type, `${name}.adoc`);
           fs.mkdirSync(path.dirname(ePath), { recursive: true });
           fs.writeFileSync(ePath, examplesOut);

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

@@ -26,7 +26,7 @@ module.exports = function renderConnectFields(children, prefix = '') {
   sorted.forEach(child => {
     if (child.is_deprecated || !child.name) return;
 
-    // Normalize type
+    // Normalize type: arrays and unknown-map as object
     let displayType;
     if (child.type === 'string' && child.kind === 'array') {
       displayType = 'array';
@@ -56,27 +56,49 @@ module.exports = function renderConnectFields(children, prefix = '') {
 
     block += `*Type*: \`${displayType}\`\n\n`;
 
-    // Default
-    if (child.type !== 'object' && child.default !== undefined) {
-      if (typeof child.default !== 'object') {
-        const display = child.default === '' ? '""' : String(child.default);
-        block += `*Default*: \`${display}\`\n\n`;
-      } else {
+    // Default value
+    if (child.default !== undefined) {
+      // Empty array
+      if (Array.isArray(child.default) && child.default.length === 0) {
+        block += `*Default*: \`[]\`\n\n`;
+      }
+      // Empty object
+      else if (
+        child.default !== null &&
+        typeof child.default === 'object' &&
+        !Array.isArray(child.default) &&
+        Object.keys(child.default).length === 0
+      ) {
+        block += `*Default*: \`{}\`\n\n`;
+      }
+      // Complex object/array
+      else if (typeof child.default === 'object') {
         const defYaml = yaml.stringify(child.default).trim();
         block += `*Default*:\n[source,yaml]\n----\n${defYaml}\n----\n\n`;
       }
+      // Primitive
+      else {
+        const display = typeof child.default === 'string'
+          ? (child.default.startsWith('"') && child.default.endsWith('"')
+              ? child.default
+              : child.default === ''
+              ? '""'
+              : child.default)
+          : String(child.default);
+        block += `*Default*: \`${display}\`\n\n`;
+      }
     }
 
-    // Annotated options
+    // Annotated options table
     if (child.annotated_options && child.annotated_options.length) {
-      block += `[cols=\"1m,2a\"]\n|===\n|Option |Summary\n\n`;
+      block += `[cols="1m,2a"]\n|===\n|Option |Summary\n\n`;
       child.annotated_options.forEach(([opt, summary]) => {
         block += `|${opt}\n|${summary}\n\n`;
       });
       block += `|===\n\n`;
     }
 
-    // Options list
+    // Simple options list
     if (child.options && child.options.length) {
       block += `*Options*: ${child.options.map(opt => `\`${opt}\``).join(', ')}\n\n`;
     }
@@ -84,54 +106,27 @@ module.exports = function renderConnectFields(children, prefix = '') {
     // Examples
     if (child.examples && child.examples.length) {
       block += `[source,yaml]\n----\n# Examples:\n`;
-      if (child.type === 'string') {
-        if (child.kind === 'array') {
-          block += renderYamlList(child.name, child.examples);
-        } else {
-          child.examples.forEach(example => {
-            if (typeof example === 'string' && example.includes('\n')) {
-              block += `${child.name}: |-\n`;
-              block += example.split('\n').map(line => '  ' + line).join('\n') + '\n';
-            } else {
-              block += `${child.name}: \`${example}\`\n`;
-            }
-          });
-          block += '\n';
-        }
-      } else if (child.type === 'processor') {
-        if (child.kind === 'array') {
-          block += renderYamlList(child.name, child.examples);
-        } else {
-          child.examples.forEach(example => {
-            block += `${child.name}: \`${String(example)}\`\n`;
-          });
-          block += '\n';
-        }
-      } else if (child.type === 'object') {
-        if (child.kind === 'array') {
-          block += renderYamlList(child.name, child.examples);
-        } else {
-          child.examples.forEach(example => {
-            if (typeof example === 'object') {
-              const snippet = yaml.stringify(example).trim();
-              block += `${child.name}:\n`;
-              block += snippet.split('\n').map(line => '  ' + line).join('\n') + '\n';
-            } else {
-              block += `${child.name}: \`${String(example)}\`\n`;
-            }
-          });
-          block += '\n';
-        }
+      if (child.kind === 'array') {
+        block += renderYamlList(child.name, child.examples);
       } else {
         child.examples.forEach(example => {
-          block += `${child.name}: \`${String(example)}\`\n`;
+          if (typeof example === 'object') {
+            const snippet = yaml.stringify(example).trim();
+            block += `${child.name}:\n`;
+            block += snippet.split('\n').map(line => '  ' + line).join('\n') + '\n';
+          } else if (typeof example === 'string' && example.includes('\n')) {
+            block += `${child.name}: |-\n`;
+            block += example.split('\n').map(line => '  ' + line).join('\n') + '\n';
+          } else {
+            // Primitive values
+            block += `${child.name}: ${example}\n`;
+          }
         });
-        block += '\n';
       }
       block += `----\n\n`;
     }
 
-    // Nested
+    // Nested children
     if (child.children && child.children.length) {
       block += renderConnectFields(child.children, currentPath);
     }

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

@@ -31,34 +31,57 @@ module.exports = function renderLeafField(field, indentLevel) {
 
   // If a default is provided, use it:
   if (field.default !== undefined) {
-    // If default is itself an object or array → dump as YAML block
+    // Empty array inline
+    if (Array.isArray(field.default) && field.default.length === 0) {
+      return `${indent}${name}: []`;
+    }
+    // Empty object inline
+    if (
+      field.default !== null &&
+      typeof field.default === 'object' &&
+      !Array.isArray(field.default) &&
+      Object.keys(field.default).length === 0
+    ) {
+      return `${indent}${name}: {}`;
+    }
+
+    // Complex object/array: dump as YAML block
     if (typeof field.default === 'object') {
-        try {
-          // Turn the object/array into a YAML string. We also need to indent that block
-          const rawYaml = yaml.stringify(field.default).trim();
-          // Indent each line of rawYaml by (indentLevel + 2) spaces:
-          const indentedYaml = rawYaml
+      try {
+        const rawYaml = yaml.stringify(field.default).trim();
+        const indentedYaml = rawYaml
           .split('\n')
           .map(line => ' '.repeat(indentLevel + 2) + line)
           .join('\n');
-          return `${indent}${name}:\n${indentedYaml}`;
-        } catch (error) {
-          console.warn(`Failed to serialize default value for field ${field.name}:`, error);
-          return `${indent}${name}: {} # Error serializing default value`;
-        }
+        return `${indent}${name}:\n${indentedYaml}`;
+      } catch (error) {
+        console.warn(`Failed to serialize default for ${field.name}:`, error);
+        return `${indent}${name}: {} # Error serializing default`;
+      }
     }
 
-    // Otherwise, default is a primitive (string/number/bool)
-    if (field.type === 'string') {
-      return `${indent}${name}: ${yaml.stringify(field.default)}`;
+    // Primitive default: string, number, boolean
+    let value;
+    if (typeof field.default === 'string') {
+      // Preserve existing quotes
+      if (field.default.startsWith('"') && field.default.endsWith('"')) {
+        value = field.default;
+      } else if (field.default === '') {
+        value = '""';
+      } else {
+        value = field.default;
+      }
+    } else {
+      value = String(field.default);
     }
-    return `${indent}${name}: ${field.default}`;
+
+    return `${indent}${name}: ${value}`;
   }
 
-  // No default → choose representation based on kind
+  // No default → choose representation
   if (field.kind === 'array') {
     return `${indent}${name}: [] ${comment}`;
   } else {
     return `${indent}${name}: "" ${comment}`;
   }
-}
+};

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

@@ -12,13 +12,27 @@ module.exports = function renderYamlList(name, exampleGroups) {
   exampleGroups.forEach(group => {
     const items = Array.isArray(group) ? group : [group];
     items.forEach(item => {
-      const snippet = yaml.stringify(item).trim();
-      const lines = snippet.split('\n');
-      out += lines
-        .map((line, idx) => (idx === 0 ? `  - ${line}` : `    ${line}`))
-        .join('\n') + '\n';
+      // Scalars
+      if (typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean') {
+        let value = String(item);
+        // Quote when needed: already-quoted scalars stay as-is; otherwise quote `*`
+        // and any value containing YAML-special characters.
+        if (!(value.startsWith('"') && value.endsWith('"'))) {
+          if (value === '*' || /[:\[\]\{\},&>|%@`]/.test(value)) {
+            value = `"${value}"`;
+          }
+        }
+        out += `  - ${value}\n`;
+      } else {
+        // Objects/arrays: stringify with indentation
+        const snippet = yaml.stringify(item).trim();
+        const lines = snippet.split('\n');
+        out += lines
+          .map((line, idx) => (idx === 0 ? `  - ${line}` : `    ${line}`))
+          .join('\n') + '\n';
+      }
     });
     out += '\n';
   });
   return out;
-}
+};