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

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

@@ -28,7 +28,10 @@ module.exports = function renderConnectFields(children, prefix = '') {
 
     // Normalize types
     let displayType;
-    if (child.type === 'string' && child.kind === 'array') {
+    const isArrayTitle = typeof child.name === 'string' && child.name.endsWith('[]');
+    if (isArrayTitle) {
+      displayType = 'array<object>';
+    } else if (child.type === 'string' && child.kind === 'array') {
       displayType = 'array';
     } else if (child.type === 'unknown' && child.kind === 'map') {
       displayType = 'object';
@@ -42,14 +45,38 @@ module.exports = function renderConnectFields(children, prefix = '') {
 
     let block = '';
     const isArray = child.kind === 'array';
+    // Only append [] if kind is array and name does not already end with []
+    const nameWithArray = (typeof child.name === 'string' && isArray && !child.name.endsWith('[]'))
+      ? `${child.name}[]`
+      : child.name;
     const currentPath = prefix
-      ? `${prefix}.${child.name}${isArray ? '[]' : ''}`
-      : `${child.name}${isArray ? '[]' : ''}`;
+      ? `${prefix}.${nameWithArray}`
+      : `${nameWithArray}`;
 
     block += `=== \`${currentPath}\`\n\n`;
 
-    if (child.description) {
-      block += `${child.description}\n\n`;
+    // --- Beta badge logic (now uses is_beta) ---
+    let desc = child.description || '';
+    if (child.is_beta) {
+      // Remove any leading "BETA:" label (case-insensitive, trims leading whitespace)
+      desc = 'badge::[label=Beta, size=large, tooltip={page-beta-text}]\n\n' + desc.replace(/^\s*BETA:\s*/i, '');
+    }
+
+    // --- Interpolation support notice ---
+    const interpolationNotice = 'This field supports xref:configuration:interpolation.adoc#bloblang-queries[interpolation functions].';
+    if (child.interpolation === true) {
+      // Only add if not already present (case-insensitive)
+      const descLower = desc.toLowerCase();
+      if (!descLower.includes('interpolation functions')) {
+        desc = desc.trim() + (desc.trim() ? '\n\n' : '') + interpolationNotice;
+      }
+    } else {
+      // If interpolation is not true, remove the notice if present
+      desc = desc.replace(new RegExp(interpolationNotice.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), '').replace(/\n{2,}/g, '\n\n');
+    }
+
+    if (desc) {
+      block += `${desc}\n\n`;
     }
     if (child.is_secret) {
       block += `include::redpanda-connect:components:partial$secret_warning.adoc[]\n\n`;

package/tools/redpanda-connect/report-delta.js

@@ -1,3 +1,103 @@
+/**
+ * Generate a JSON diff report between two connector index objects.
+ * @param {object} oldIndex - Previous version connector index
+ * @param {object} newIndex - Current version connector index
+ * @param {object} opts - { oldVersion, newVersion, timestamp }
+ * @returns {object} JSON diff report
+ */
+function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
+  const oldMap = buildComponentMap(oldIndex);
+  const newMap = buildComponentMap(newIndex);
+
+  // New components
+  const newComponentKeys = Object.keys(newMap).filter(k => !(k in oldMap));
+  const newComponents = newComponentKeys.map(key => {
+    const [type, name] = key.split(':');
+    const raw = newMap[key].raw;
+    return {
+      name,
+      type,
+      status: raw.status || raw.type || '',
+      version: raw.version || raw.introducedInVersion || '',
+      description: raw.description || ''
+    };
+  });
+
+  // Removed components
+  const removedComponentKeys = Object.keys(oldMap).filter(k => !(k in newMap));
+  const removedComponents = removedComponentKeys.map(key => {
+    const [type, name] = key.split(':');
+    const raw = oldMap[key].raw;
+    return {
+      name,
+      type,
+      status: raw.status || raw.type || '',
+      version: raw.version || raw.introducedInVersion || '',
+      description: raw.description || ''
+    };
+  });
+
+  // New fields under existing components
+  const newFields = [];
+  Object.keys(newMap).forEach(cKey => {
+    if (!(cKey in oldMap)) return;
+    const oldFields = new Set(oldMap[cKey].fields || []);
+    const newFieldsArr = newMap[cKey].fields || [];
+    newFieldsArr.forEach(fName => {
+      if (!oldFields.has(fName)) {
+        const [type, compName] = cKey.split(':');
+        let rawFieldObj = null;
+        if (type === 'config') {
+          rawFieldObj = (newMap[cKey].raw.children || []).find(f => f.name === fName);
+        } else {
+          rawFieldObj = (newMap[cKey].raw.config?.children || []).find(f => f.name === fName);
+        }
+        newFields.push({
+          component: cKey,
+          field: fName,
+          introducedIn: rawFieldObj && (rawFieldObj.introducedInVersion || rawFieldObj.version),
+          description: rawFieldObj && rawFieldObj.description
+        });
+      }
+    });
+  });
+
+  // Removed fields under existing components
+  const removedFields = [];
+  Object.keys(oldMap).forEach(cKey => {
+    if (!(cKey in newMap)) return;
+    const newFieldsSet = new Set(newMap[cKey].fields || []);
+    const oldFieldsArr = oldMap[cKey].fields || [];
+    oldFieldsArr.forEach(fName => {
+      if (!newFieldsSet.has(fName)) {
+        removedFields.push({
+          component: cKey,
+          field: fName
+        });
+      }
+    });
+  });
+
+  return {
+    comparison: {
+      oldVersion: opts.oldVersion || '',
+      newVersion: opts.newVersion || '',
+      timestamp: opts.timestamp || new Date().toISOString()
+    },
+    summary: {
+      newComponents: newComponents.length,
+      removedComponents: removedComponents.length,
+      newFields: newFields.length,
+      removedFields: removedFields.length
+    },
+    details: {
+      newComponents,
+      removedComponents,
+      newFields,
+      removedFields
+    }
+  };
+}
 // tools/redpanda-connect/report-delta.js
 'use strict';
 
@@ -149,4 +249,5 @@ module.exports = {
   buildComponentMap,
   getRpkConnectVersion,
   printDeltaReport,
+  generateConnectorDiffJson,
 };

package/tools/redpanda-connect/templates/bloblang-function.hbs

@@ -0,0 +1,28 @@
+// This content is autogenerated. Do not edit manually. To override descriptions, use the doc-tools CLI with the --overrides option: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1247543314/Generate+reference+docs+for+Redpanda+Connect
+
+= {{name}}
+
+{{#if signature}}
+*Signature*: `{{signature}}`
+{{/if}}
+
+{{#if description}}
+{{description}}
+{{/if}}
+
+
+{{#if examples}}
+== Examples
+
+{{#each examples}}
+{{{bloblangExample this}}}
+{{/each}}
+{{/if}}
+
+{{#if related}}
+== Related
+
+{{#each related}}
+* {{this}}
+{{/each}}
+{{/if}}