@redpanda-data/docs-extensions-and-macros 4.5.0 → 4.6.0

package/cli-utils/antora-utils.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Attempts to locate and parse `antora.yml` in the current working directory.
+ *
+ * @returns {Object|undefined} The parsed YAML as a JavaScript object, or undefined if not found or on error.
+ */
+function loadAntoraConfig() {
+  const antoraPath = path.join(process.cwd(), 'antora.yml');
+  if (!fs.existsSync(antoraPath)) {
+    // No antora.yml in project root
+    return undefined;
+  }
+
+  try {
+    const fileContents = fs.readFileSync(antoraPath, 'utf8');
+    const config = yaml.load(fileContents);
+    if (typeof config !== 'object' || config === null) {
+      console.error('Warning: antora.yml parsed to a non‐object value.');
+      return undefined;
+    }
+    return config;
+  } catch (err) {
+    console.error(`Error reading/parsing antora.yml: ${err.message}`);
+    return undefined;
+  }
+}
+
+/**
+ * Safely retrieves a nested value from the Antora configuration, given a "dot path".
+ *
+ * Example usage:
+ *   const latestVersion = getAntoraValue('asciidoc.attributes.latest-connect-version');
+ *
+ * @param {string} keyPath
+ *   A dot-separated path into the Antora object (e.g. "asciidoc.attributes.foo").
+ * @returns {*}
+ *   The value at that path, or undefined if the file is missing or the key does not exist.
+ */
+function getAntoraValue(keyPath) {
+  const config = loadAntoraConfig();
+  if (!config) {
+    return undefined;
+  }
+
+  // Split on dots, but ignore empty segments
+  const segments = keyPath.split('.').filter(Boolean);
+  let cursor = config;
+
+  for (const seg of segments) {
+    if (cursor && typeof cursor === 'object' && seg in cursor) {
+      cursor = cursor[seg];
+    } else {
+      return undefined;
+    }
+  }
+  return cursor;
+}
+
+/**
+ * Safely sets a nested value in the Antora configuration, given a "dot path".
+ * If the file or path does not exist, it will create intermediate objects as needed.
+ * After setting the value, writes the updated YAML back to `antora.yml`.
+ *
+ * @param {string} keyPath
+ *   A dot-separated path to set (e.g. "asciidoc.attributes.latest-connect-version").
+ * @param {*} newValue
+ *   The new value to assign at that path.
+ * @returns {boolean}
+ *   True if it succeeded, false otherwise.
+ */
+function setAntoraValue(keyPath, newValue) {
+  const antoraPath = path.join(process.cwd(), 'antora.yml');
+  if (!fs.existsSync(antoraPath)) {
+    console.error('Cannot update antora.yml: file not found in project root.');
+    return false;
+  }
+
+  let config;
+  try {
+    const fileContents = fs.readFileSync(antoraPath, 'utf8');
+    config = yaml.load(fileContents) || {};
+    if (typeof config !== 'object' || config === null) {
+      config = {};
+    }
+  } catch (err) {
+    console.error(`Error reading/parsing antora.yml: ${err.message}`);
+    return false;
+  }
+
+  // Traverse/construct nested objects
+  const segments = keyPath.split('.').filter(Boolean);
+  let cursor = config;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (i === segments.length - 1) {
+      // Last segment: assign
+      cursor[seg] = newValue;
+    } else {
+      // Intermediate: ensure object
+      if (!(seg in cursor) || typeof cursor[seg] !== 'object' || cursor[seg] === null) {
+        cursor[seg] = {};
+      }
+      cursor = cursor[seg];
+    }
+  }
+
+  // Serialize back to YAML and write
+  try {
+    const newYaml = yaml.dump(config, { lineWidth: 120 });
+    fs.writeFileSync(antoraPath, newYaml, 'utf8');
+    return true;
+  } catch (err) {
+    console.error(`Error writing antora.yml: ${err.message}`);
+    return false;
+  }
+}
+
+module.exports = {
+  loadAntoraConfig,
+  getAntoraValue,
+  setAntoraValue,
+};

package/cli-utils/self-managed-docs-branch.js

@@ -56,7 +56,7 @@ async function determineDocsBranch(operatorTag) {
   if (!filtered) {
     throw new Error(`Could not parse major.minor from ${TAG}`)
   }
-
+  // We started versioning the operator in line with Redpanda core versions. But when v2.4.x was the latest version, the docs were still on 25.1 and v25.1.x of the operator was still in beta. So we need to handle this special case.
   let branch
   if (filtered === 'v2.4') {
     if (ANTORA === '25.1') {
@@ -64,6 +64,7 @@ async function determineDocsBranch(operatorTag) {
     } else {
       branch = 'v/24.3'
     }
+  // For all other versions use the v<major>.<minor> branch unless it is the current version, in which case we use 'main'.
   } else if (filtered === `v${ANTORA}`) {
     branch = 'main'
   } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -20,7 +20,8 @@
     "get-redpanda-version": "doc-tools get-redpanda-version",
     "get-console-version": "doc-tools get-console-version",
     "build": "antora --to-dir docs --fetch local-antora-playbook.yml",
-    "serve": "wds --node-resolve --open preview/test/ --watch --root-dir docs"
+    "serve": "wds --node-resolve --open preview/test/ --watch --root-dir docs",
+    "test": "jest"
   },
   "contributors": [
     {
@@ -56,8 +57,7 @@
     "./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/data-template": "./macros/data-template.js"
+    "./macros/helm-ref": "./macros/helm-ref.js"
   },
   "files": [
     "extensions",
@@ -101,6 +101,7 @@
   "devDependencies": {
     "@antora/cli": "3.1.4",
     "@antora/site-generator": "3.1.4",
-    "@web/dev-server": "^0.2.5"
+    "@web/dev-server": "^0.2.5",
+    "jest": "^29.7.0"
   }
 }

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

@@ -0,0 +1,205 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const handlebars = require('handlebars');
+const yaml = require('yaml');
+const helpers = require('./helpers');
+
+// Register each helper under handlebars, verifying that it’s a function
+Object.entries(helpers).forEach(([name, fn]) => {
+  if (typeof fn !== 'function') {
+    console.error(`❌ Helper "${name}" is not a function`);
+    process.exit(1);
+  }
+  handlebars.registerHelper(name, fn);
+});
+
+// Default “main” template (connector.hbs) which invokes partials {{> intro}}, {{> fields}}, {{> examples}}
+const DEFAULT_TEMPLATE = path.resolve(__dirname, './templates/connector.hbs');
+
+/**
+ * Reads a file at `filePath` and registers it as a Handlebars partial called `name`.
+ * Throws if the file cannot be read.
+ */
+function registerPartial(name, filePath) {
+  const resolved = path.resolve(filePath);
+  let source;
+  try {
+    source = fs.readFileSync(resolved, 'utf8');
+  } catch (err) {
+    throw new Error(`Unable to read "${name}" template at ${resolved}: ${err.message}`);
+  }
+  handlebars.registerPartial(name, source);
+}
+
+/**
+ * Deep-merge `overrides` into `target`. Only 'description', 'type',
+ * plus nested array/object entries get overridden; other keys remain intact.
+ */
+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');
+  }
+  for (const key in overrides) {
+    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 => {
+            if (Object.hasOwn(overrideItem, field)) {
+              item[field] = overrideItem[field];
+            }
+          });
+          // Recurse for nested children
+          item = mergeOverrides(item, overrideItem);
+        }
+        return item;
+      });
+    } else 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
+      target[key] = overrides[key];
+    }
+  }
+  return target;
+}
+
+async function generateRpcnConnectorDocs(options) {
+  const {
+    data,
+    overrides,
+    template,            // main Handlebars template (for full-draft mode)
+    templateIntro,
+    templateFields,
+    templateExamples,
+    writeFullDrafts
+  } = options;
+
+  // Read connector index (JSON or YAML)
+  const raw = fs.readFileSync(data, 'utf8');
+  const ext = path.extname(data).toLowerCase();
+  const dataObj = ext === '.json' ? JSON.parse(raw) : yaml.parse(raw);
+
+  // Apply overrides if provided
+  if (overrides) {
+    const ovRaw = fs.readFileSync(overrides, 'utf8');
+    const ovObj = JSON.parse(ovRaw);
+    mergeOverrides(dataObj, ovObj);
+  }
+
+  // Compile the “main” template (used when writeFullDrafts = true)
+  const compiledTemplate = handlebars.compile(fs.readFileSync(template, 'utf8'));
+
+  // Determine which templates to use for “fields” and “examples”
+  // If templateFields is not provided, fall back to the single `template`.
+  // If templateExamples is not provided, skip examples entirely.
+  const fieldsTemplatePath   = templateFields   || template;
+  const examplesTemplatePath = templateExamples || null;
+
+  // Register partials
+  if (!writeFullDrafts) {
+    if (fieldsTemplatePath) {
+      registerPartial('fields', fieldsTemplatePath);
+    }
+    if (examplesTemplatePath) {
+      registerPartial('examples', examplesTemplatePath);
+    }
+  } else {
+    registerPartial('intro', templateIntro);
+  }
+
+  const outputRoot     = path.resolve(process.cwd(), 'modules/components/partials');
+  const fieldsOutRoot   = path.join(outputRoot, 'fields');
+  const examplesOutRoot = path.join(outputRoot, 'examples');
+  const draftsRoot      = path.join(outputRoot, 'drafts');
+
+  if (!writeFullDrafts) {
+    fs.mkdirSync(fieldsOutRoot,   { recursive: true });
+    fs.mkdirSync(examplesOutRoot, { recursive: true });
+  }
+
+  let partialsWritten = 0;
+  let draftsWritten   = 0;
+  const partialFiles  = [];
+  const draftFiles    = [];
+
+  for (const [type, items] of Object.entries(dataObj)) {
+    if (!Array.isArray(items)) continue;
+
+    for (const item of items) {
+      if (!item.name) continue;
+      const name = item.name;
+
+      if (!writeFullDrafts) {
+        // Render fields using the registered “fields” partial
+        const fieldsOut = handlebars
+          .compile('{{> fields children=config.children}}')(item);
+
+        // Render examples only if an examples template was provided
+        let examplesOut = '';
+        if (examplesTemplatePath) {
+          examplesOut = handlebars
+            .compile('{{> examples examples=examples}}')(item);
+        }
+
+        if (fieldsOut.trim()) {
+          const fPath = path.join(fieldsOutRoot, type, `${name}.adoc`);
+          fs.mkdirSync(path.dirname(fPath), { recursive: true });
+          fs.writeFileSync(fPath, fieldsOut);
+          partialsWritten++;
+          partialFiles.push(path.relative(process.cwd(), fPath));
+        }
+
+        if (examplesOut.trim()) {
+          const ePath = path.join(examplesOutRoot, type, `${name}.adoc`);
+          fs.mkdirSync(path.dirname(ePath), { recursive: true });
+          fs.writeFileSync(ePath, examplesOut);
+          partialsWritten++;
+          partialFiles.push(path.relative(process.cwd(), ePath));
+        }
+      }
+
+      if (writeFullDrafts) {
+        let content;
+        try {
+          content = compiledTemplate(item);
+        } catch (err) {
+          throw new Error(`Template render failed for component "${name}": ${err.message}`);
+        }
+
+        const draftSubdir = name === 'gateway'
+          ? path.join(draftsRoot, 'cloud-only')
+          : draftsRoot;
+
+        const destFile = path.join(draftSubdir, `${name}.adoc`);
+        fs.mkdirSync(path.dirname(destFile), { recursive: true });
+        fs.writeFileSync(destFile, content, 'utf8');
+        draftsWritten++;
+        draftFiles.push(path.relative(process.cwd(), destFile));
+      }
+    }
+  }
+
+  return {
+    partialsWritten,
+    draftsWritten,
+    partialFiles,
+    draftFiles
+  };
+}
+
+module.exports = {
+  generateRpcnConnectorDocs,
+  mergeOverrides
+};

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

@@ -0,0 +1,17 @@
+const buildConfigYaml = require('./buildConfigYaml.js');
+const handlebars = require('handlebars');
+
+/**
+ * Handlebars helper “advancedConfig”.  Omits only deprecated.
+ *
+ * Usage in template:
+ *   {{advancedConfig this.type this.name this.config.children}}
+ */
+module.exports = function advancedConfig(type, connectorName, children) {
+  if (typeof type !== 'string' || typeof connectorName !== 'string' || !Array.isArray(children)) {
+    return '';
+  }
+
+  const yamlText = buildConfigYaml(type, connectorName, children, /*includeAdvanced=*/ true);
+  return new handlebars.SafeString(yamlText);
+}

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

@@ -0,0 +1,53 @@
+const renderLeafField = require('./renderLeafField');
+const renderObjectField = require('./renderObjectField');
+
+/**
+ * Builds either “Common” or “Advanced” YAML for one connector.
+ *
+ * - type            = “input” or “output” (or whatever type)
+ * - connectorName   = such as “amqp_1”
+ * - children        = the array of field‐definitions (entry.config.children)
+ * - includeAdvanced = if false → only fields where is_advanced !== true
+ *                      if true  → all fields (except deprecated)
+ *
+ * Structure produced:
+ *
+ *   type:
+ *     label: ""
+ *     connectorName:
+ *       ...child fields (with comments for “no default”)
+ */
+module.exports = function buildConfigYaml(type, connectorName, children, includeAdvanced) {
+  const lines = [];
+
+  // “type:” top‐level
+  lines.push(`${type}:`);
+
+  // Two‐space indent for “label”
+  lines.push(`  label: ""`);
+
+  // Two‐space indent for connectorName heading
+  lines.push(`  ${connectorName}:`);
+
+  // Four‐space indent for children
+  const baseIndent = 4;
+  children.forEach(field => {
+    if (field.is_deprecated) {
+      return; // skip deprecated fields
+    }
+    if (!includeAdvanced && field.is_advanced) {
+      return; // skip advanced fields in “common” mode
+    }
+
+    if (field.type === 'object' && Array.isArray(field.children)) {
+      // Render nested object
+      const nestedLines = renderObjectField(field, baseIndent);
+      lines.push(...nestedLines);
+    } else {
+      // Render a scalar or array leaf
+      lines.push(renderLeafField(field, baseIndent));
+    }
+  });
+
+  return lines.join('\n');
+}

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

@@ -0,0 +1,31 @@
+const buildConfigYaml = require('./buildConfigYaml.js');
+const handlebars = require('handlebars');
+
+/**
+ * Handlebars helper “commonConfig”.  Omits deprecated + advanced.
+ *
+ * Usage in template:
+ *   {{commonConfig this.type this.name this.config.children}}
+ */
+module.exports = function commonConfig(type, connectorName, children) {
+  if (typeof type !== 'string' || !type.trim()) {
+    console.warn('commonConfig: type must be a non-empty string');
+    return '';
+  }
+  if (typeof connectorName !== 'string' || !connectorName.trim()) {
+    console.warn('commonConfig: connectorName must be a non-empty string');
+    return '';
+  }
+  if (!Array.isArray(children)) {
+    console.warn('commonConfig: children must be an array');
+    return '';
+  }
+
+  try {
+    const yamlText = buildConfigYaml(type, connectorName, children, /*includeAdvanced=*/ false);
+    return new handlebars.SafeString(yamlText);
+  } catch (error) {
+    console.error('Error in commonConfig helper:', error);
+    return new handlebars.SafeString('<!-- Error generating configuration -->');
+  }
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Checks if two values are equal.
+ *
+ * @param {*} a - The first value.
+ * @param {*} b - The second value.
+ * @returns {boolean} True if the values are equal.
+ */
+module.exports = function eq(a, b) {
+  return a === b;
+}

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

@@ -0,0 +1,19 @@
+'use strict';
+
+module.exports = {
+  uppercase:       require('./uppercase.js'),
+  eq:              require('./eq.js'),
+  ne:              require('./ne.js'),
+  join:              require('./join.js'),
+  or:              require('./or.js'),
+  toYaml:              require('./toYaml.js'),
+  isObject:              require('./isObject.js'),
+  renderYamlList:  require('./renderYamlList.js'),
+  renderConnectFields:    require('./renderConnectFields.js'),
+  renderConnectExamples:  require('./renderConnectExamples.js'),
+  renderLeafField:        require('./renderLeafField.js'),
+  renderObjectField:      require('./renderObjectField.js'),
+  buildConfigYaml:        require('./buildConfigYaml.js'),
+  commonConfig:           require('./commonConfig.js'),
+  advancedConfig:         require('./advancedConfig.js'),
+};

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

@@ -0,0 +1 @@
+module.exports = v => v !== null && typeof v === 'object' && !Array.isArray(v)

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

@@ -0,0 +1,6 @@
+module.exports = function join(array, separator) {
+  if (!Array.isArray(array)) {
+    return '';
+  }
+  return array.join(separator);
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Checks if two values are not equal.
+ *
+ * @param {*} a - The first value.
+ * @param {*} b - The second value.
+ * @returns {boolean} True if the values are not equal.
+ */
+module.exports = function ne(a, b) {
+  return a !== b;
+}

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

@@ -0,0 +1,4 @@
+module.exports = function (...args) {
+    const options = args.pop(); // Last argument is always the options object
+    return args.some(Boolean);
+};

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

@@ -0,0 +1,37 @@
+const handlebars = require('handlebars');
+
+/**
+ * Renders a list of examples.
+ *
+ * @param {Array<Object>} examples - An array of example objects.
+ * @returns {handlebars.SafeString} The rendered SafeString containing the examples.
+ */
+module.exports = function renderConnectExamples(examples) {
+  if (!examples || !Array.isArray(examples) || examples.length === 0) {
+    return '';
+  }
+  let output = '';
+  examples.forEach(example => {
+    if (example.title) {
+      const sanitizedTitle = example.title.replace(/[=]/g, '\\=');
+      output += `=== ${sanitizedTitle}\n\n`;
+    }
+    if (example.summary) {
+      output += `${example.summary}\n\n`;
+    }
+    if (example.config) {
+      if (typeof example.config !== 'string') {
+        console.warn('Example config must be a string, skipping');
+        return;
+      }
+      const configContent = example.config.trim();
+      if (configContent.includes('----')) {
+        console.warn('Example config contains AsciiDoc delimiters, this may break rendering');
+      }
+      output += '[source,yaml]\n----\n';
+      output += configContent + '\n';
+      output += '----\n\n';
+    }
+  });
+  return new handlebars.SafeString(output);
+}