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

package/bin/doc-tools.js

@@ -485,7 +485,16 @@ automation
   .option('--template-examples <path>', 'Examples section partial template', path.resolve(__dirname, '../tools/redpanda-connect/templates/examples-partials.hbs'))
   .option('--overrides <path>', 'Optional JSON file with overrides')
   .action(async (options) => {
-    let success = true;
+    requireTool('rpk', {
+      versionFlag: '--version',
+      help: 'rpk is not installed. Install rpk: https://docs.redpanda.com/current/get-started/rpk-install/'
+    });
+
+    requireTool('rpk connect', {
+      versionFlag: '--version',
+      help: 'rpk connect is not installed. Run rpk connect install before continuing.'
+    });
+
     const dataDir = path.resolve(process.cwd(), options.dataDir);
     fs.mkdirSync(dataDir, { recursive: true });
 
@@ -495,7 +504,6 @@ automation
     let dataFile;
     if (options.fetchConnectors) {
       try {
-        execSync('rpk --version', { stdio: 'ignore' });
         newVersion = getRpkConnectVersion();
         const tmpFile = path.join(dataDir, `connect-${newVersion}.tmp.json`);
         const finalFile = path.join(dataDir, `connect-${newVersion}.json`);
@@ -512,7 +520,7 @@ automation
         console.log(`✅ Fetched and saved: ${finalFile}`);
       } catch (err) {
         console.error(`❌ Failed to fetch connectors: ${err.message}`);
-        success = false;
+        process.exit(1);
       }
     } else {
       const candidates = fs.readdirSync(dataDir).filter(f => /^connect-\d+\.\d+\.\d+\.json$/.test(f));
@@ -542,7 +550,7 @@ automation
       partialFiles    = result.partialFiles;
     } catch (err) {
       console.error(`❌ Failed to generate partials: ${err.message}`);
-      success = false;
+      process.exit(1);
     }
 
     if (options.draftMissing) {
@@ -613,7 +621,7 @@ automation
         }
       } catch (err) {
         console.error(`❌ Could not draft missing: ${err.message}`);
-        success = false;
+        process.exit(1);
       }
     }
 
@@ -667,8 +675,7 @@ automation
     console.log('\n📄 Summary:');
     console.log(`   • Run time: ${timestamp}`);
     console.log(`   • Version used: ${newVersion}`);
-
-    process.exit(success ? 0 : 1);
+    process.exit(0);
   });
 
 automation

package/extensions/generate-rp-connect-info.js

@@ -115,40 +115,58 @@ module.exports.register = function ({ config }) {
       let redpandaConnectUrl = '';
       let redpandaCloudUrl = '';
 
+      function isConnectorDocPath (filePath, type) {
+        const dirsToCheck = [
+          `pages/${type}s/`,
+          `partials/components/${type}s/`
+        ];
+        return dirsToCheck.some(dir => filePath.includes(dir));
+      }
+
+      function isCloudDoc(file, connector, type) {
+        return (
+          file.src.component === 'redpanda-cloud' &&
+          file.path.includes(`connect/components/${type}s/${connector}.adoc`)
+        );
+      }
+
       // Look for both Redpanda Connect and Cloud URLs
       for (const file of pages) {
-        const component = file.src.component;
-        const filePath = file.path;
+        const { component } = file.src;      // such as 'redpanda-connect'
+        const { path: filePath } = file;     // such as modules/.../pages/sinks/foo.adoc
 
         if (
           component === 'redpanda-connect' &&
           filePath.endsWith(`/${connector}.adoc`) &&
-          filePath.includes(`pages/${type}s/`)
+          isConnectorDocPath(filePath, type)
         ) {
           redpandaConnectUrl = file.pub.url;
         }
 
-        // Only check for Redpanda Cloud URLs if cloud is supported
-        if (
-          is_cloud_supported === 'y' &&
-          component === 'redpanda-cloud' &&
-          filePath.endsWith(`/${connector}.adoc`) &&
-          filePath.includes(`${type}s/`)
-        ) {
+        // -------------------------------------------------
+        // Redpanda Cloud (only if cloud supported)
+        // -------------------------------------------------
+        if (is_cloud_supported === 'y' && isCloudDoc(file, connector, type)) {
           redpandaCloudUrl = file.pub.url;
         }
       }
 
-      // Log a warning if neither URL was found and the component is not deprecated
       if (
         deprecated !== 'y' &&
         !connector.includes('sql_driver') &&
         !redpandaConnectUrl &&
-        (!redpandaCloudUrl && is_cloud_supported === 'y')
+        !(is_cloud_supported === 'y' && redpandaCloudUrl)
       ) {
-        logger.warn(`Docs missing for: ${connector} of type: ${type}`);
+        logger.warn(`Self-Managed docs missing for: ${connector} of type: ${type}`);
       }
 
+      if (
+        is_cloud_supported === 'y' &&
+        !redpandaCloudUrl &&
+        redpandaConnectUrl
+      ) {
+        logger.warn(`Cloud docs missing for: ${connector} of type: ${type}`);
+      }
 
       // Return the translated and enriched row
       return {

package/macros/badge.js

@@ -0,0 +1,21 @@
+'use strict';
+
+module.exports.register = function (registry) {
+  registry.inlineMacro(function () {
+    const self = this;
+    self.named('badge');
+    self.process((parent, target, attrs) => {
+      const label = attrs.label || 'label';
+      const className = `badge--${label.toLowerCase().replace(/\s+/g, '-')}`;
+      const isLarge = attrs.size === 'large';
+      const sizeClass = isLarge ? 'badge--large' : '';
+      const tooltip = attrs.tooltip;
+      const tooltipAttr = tooltip ? ` data-tooltip="${tooltip}"` : '';
+
+      // Add brackets if not large
+      const renderedLabel = isLarge ? label : `(${label})`;
+
+      return `<span class="badge ${className} ${sizeClass}"${tooltipAttr}>${renderedLabel}</span>`;
+    });
+  });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.6.2",
+  "version": "4.6.4",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -57,7 +57,8 @@
     "./macros/glossary": "./macros/glossary.js",
     "./macros/rp-connect-components": "./macros/rp-connect-components.js",
     "./macros/config-ref": "./macros/config-ref.js",
-    "./macros/helm-ref": "./macros/helm-ref.js"
+    "./macros/helm-ref": "./macros/helm-ref.js",
+    "./macros/badge": "./macros/badge.js"
   },
   "files": [
     "extensions",

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

@@ -35,47 +35,99 @@ function registerPartial(name, filePath) {
 
 /**
  * Deep-merge `overrides` into `target`. Only 'description', 'type',
- * plus nested array/object entries get overridden; other keys remain intact.
+ * 'annotated_field', 'examples', and known nested fields are overridden.
  */
 function mergeOverrides(target, overrides) {
   if (!overrides || typeof overrides !== 'object') return target;
   if (!target || typeof target !== 'object') {
     throw new Error('Target must be a valid object');
   }
+
+  const scalarKeys = ['description', 'type', 'annotated_field', 'version'];
+
   for (const key in overrides) {
+    // === Handle annotated_options ===
+    if (key === 'annotated_options' && Array.isArray(overrides[key]) && Array.isArray(target[key])) {
+      const overrideMap = new Map(overrides[key].map(([name, desc]) => [name, desc]));
+
+      target[key] = target[key].map(([name, desc]) => {
+        if (overrideMap.has(name)) {
+          return [name, overrideMap.get(name)];
+        }
+        return [name, desc];
+      });
+
+      const existingNames = new Set(target[key].map(([name]) => name));
+      for (const [name, desc] of overrides[key]) {
+        if (!existingNames.has(name)) {
+          target[key].push([name, desc]);
+        }
+      }
+      continue;
+    }
+
+    // === Handle examples ===
+    if (key === 'examples' && Array.isArray(overrides[key]) && Array.isArray(target[key])) {
+      const overrideMap = new Map(overrides[key].map(o => [o.title, o]));
+
+      target[key] = target[key].map(example => {
+        const override = overrideMap.get(example.title);
+        if (override) {
+          return {
+            ...example,
+            ...(override.summary && { summary: override.summary }),
+            ...(override.config && { config: override.config }),
+          };
+        }
+        return example;
+      });
+
+      const existingTitles = new Set(target[key].map(e => e.title));
+      for (const example of overrides[key]) {
+        if (!existingTitles.has(example.title)) {
+          target[key].push(example);
+        }
+      }
+      continue;
+    }
+
+    // === Merge arrays of objects with .name ===
     if (Array.isArray(target[key]) && Array.isArray(overrides[key])) {
-      // Merge two parallel arrays by matching items on `.name`
       target[key] = target[key].map(item => {
         const overrideItem = overrides[key].find(o => o.name === item.name);
         if (overrideItem) {
-          // Overwrite description/type if present
-          ['description', 'type'].forEach(field => {
+          scalarKeys.forEach(field => {
             if (Object.hasOwn(overrideItem, field)) {
               item[field] = overrideItem[field];
             }
           });
-          // Copy through selfManagedOnly flag
           if (Object.hasOwn(overrideItem, 'selfManagedOnly')) {
             item.selfManagedOnly = overrideItem.selfManagedOnly;
           }
-          // Recurse for nested children
-          item = mergeOverrides(item, overrideItem);
+          return mergeOverrides(item, overrideItem);
         }
         return item;
       });
-    } else if (
+      continue;
+    }
+
+    // === Merge nested objects ===
+    if (
       typeof target[key] === 'object' &&
       typeof overrides[key] === 'object' &&
       !Array.isArray(target[key]) &&
       !Array.isArray(overrides[key])
     ) {
-      // Deep-merge plain objects
       target[key] = mergeOverrides(target[key], overrides[key]);
-    } else if (['description', 'type'].includes(key) && Object.hasOwn(overrides, key)) {
-      // Overwrite the primitive
+      continue;
+    }
+
+    // === Overwrite scalar keys ===
+    if (scalarKeys.includes(key) && Object.hasOwn(overrides, key)) {
       target[key] = overrides[key];
     }
   }
+
   return target;
 }
 

package/macros/enterprise-label.js

@@ -1,11 +0,0 @@
-'use strict';
-
-module.exports.register = function (registry) {
-  registry.inlineMacro(function () {
-    const self = this;
-    self.named('enterprise-label');
-    self.process((parent, target, attrs) => {
-      return `<span class="inline-enterprise-label">Enterprise</span>`;
-    });
-  });
-};