@redpanda-data/docs-extensions-and-macros 5.55.0 → 5.56.0

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

@@ -17,6 +17,9 @@ Object.entries(helpers).forEach(([name, fn]) => {
   }
   handlebars.registerHelper(name, fn);
 });
+// The provenance marker the partial templates write on their first line
+const { generatedMarker } = require('../../cli-utils/generated-marker');
+handlebars.registerHelper('generatedMarker', generatedMarker);
 
 // Default “main” template (connector.hbs) which invokes partials {{> intro}}, {{> fields}}, {{> examples}}
 const DEFAULT_TEMPLATE = path.resolve(__dirname, './templates/connector.hbs');
@@ -34,9 +37,12 @@ const { hasStructuralHeadings, hasMarkdownHeadings, firstHeadingDepth, escapePla
 // section is removed upstream. Kept as an AsciiDoc comment so the file renders
 // nothing while any lingering include directive still resolves cleanly.
 const STALE_METADATA_PARTIAL =
-  '// This content is autogenerated. Do not edit manually. ' +
-  'The connector description no longer contains a `== Metadata` section, so this partial is intentionally empty. ' +
-  'You can remove the include directive that points at this file from the connector page.\n';
+  generatedMarker(
+    'rpcn-connector-docs',
+    'the component spec in redpanda-data/connect',
+    'The connector description no longer contains a `== Metadata` section, so this partial is intentionally empty. ' +
+      'You can remove the include directive that points at this file from the connector page.'
+  ) + '\n';
 
 // Banner-only content written to a description partial when the connector's
 // description is removed upstream. Same rationale as STALE_METADATA_PARTIAL:
@@ -50,12 +56,27 @@ const STALE_METADATA_PARTIAL =
 // every page that includes it, on every build, which is a build failure
 // wherever Asciidoctor warnings are treated as errors. An empty region
 // resolves to nothing and says nothing.
-const STALE_DESCRIPTION_PARTIAL =
-  '// This content is autogenerated. Do not edit manually. ' +
-  'The connector no longer has a description, so this partial is intentionally empty. ' +
-  'You can remove the include directive that points at this file from the connector page.\n' +
+const STALE_DESCRIPTION_REGIONS =
   '\n// tag::meta[]\n// end::meta[]\n' +
   '\n// tag::body[]\n// end::body[]\n';
+const STALE_DESCRIPTION_PARTIAL =
+  generatedMarker(
+    'rpcn-connector-docs',
+    'the component spec in redpanda-data/connect',
+    'The connector no longer has a description, so this partial is intentionally empty. ' +
+      'You can remove the include directive that points at this file from the connector page.'
+  ) + '\n' + STALE_DESCRIPTION_REGIONS;
+// What earlier releases wrote for the same blanked partial. The orphan sweep
+// treats either as already blanked, so a partial emptied before the marker
+// changed is not re-blanked and re-reported. The marker carries no version,
+// so this list grows only when the wording does.
+const STALE_DESCRIPTION_PARTIALS = new Set([
+  STALE_DESCRIPTION_PARTIAL,
+  '// This content is autogenerated. Do not edit manually. ' +
+    'The connector no longer has a description, so this partial is intentionally empty. ' +
+    'You can remove the include directive that points at this file from the connector page.\n' +
+    STALE_DESCRIPTION_REGIONS,
+]);
 
 // Component families with their own reference pages, keyed by the canonical
 // type directory from typeDirFor(). Other data keys -- `config`, the bloblang
@@ -932,7 +953,7 @@ async function generateRpcnConnectorDocs(options) {
         const orphanPath = path.join(typeDirPath, file);
         // Already blanked on an earlier run: leave it alone so it is not
         // re-reported forever.
-        if (fs.readFileSync(orphanPath, 'utf8') === STALE_DESCRIPTION_PARTIAL) continue;
+        if (STALE_DESCRIPTION_PARTIALS.has(fs.readFileSync(orphanPath, 'utf8'))) continue;
         orphans.push({ key, orphanPath });
       }
     }

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

@@ -30,11 +30,9 @@ function capToTwoSentences (description) {
   }
 
   const abbreviations = [
-    /https?:\/\/[^\s]+?(?=[.!?](?:\s|$)|\s|$)/gi,  // Protect URLs from being split by sentence detection (non-greedy, preserve trailing punctuation)
-    /\bxref:[^\s[\]]+\[[^\]]*\]/g,  // Protect Antora xref macros (e.g. xref:components:processors/try.adoc[`try`]) whose targets contain periods
-    /\b[\w/-]+\.(?:adoc|md|ya?ml|json|html)\b/gi,  // Protect bare doc/config filenames (try.adoc, config.yaml) from splitting
-    /\bv\d+\.\d+(?:\.\d+)?/gi,
-    /\d+\.\d+/g,
+    // A period inside a token (a URL, an xref target, a filename, a version
+    // or a decimal) has no whitespace after it, so it never ends a sentence.
+    // Only abbreviations that are followed by a space need protecting.
     /\be\.g\./gi,
     /\bi\.e\./gi,
     /\betc\./gi,
@@ -79,21 +77,12 @@ function capToTwoSentences (description) {
     return placeholder
   })
 
-  const sentenceRegex = /[^.!?]+[.!?]+(?:\s|$)/g
-
-  // An unprotected mid-token period (`fetch.max.partition.bytes`) stops a
-  // match, and the regex then resumes after it, so the text before that
-  // period never belongs to any match. Merge each such gap into the sentence
-  // that follows it rather than silently discarding it, otherwise the second
-  // "sentence" can be a tail such as "bytes`.". Text after the last match
-  // (an unterminated colon lead-in, for example) is still dropped.
-  let sentences = null
-  let lastEnd = 0
-  for (const m of normalized.matchAll(sentenceRegex)) {
-    if (!sentences) sentences = []
-    sentences.push(normalized.slice(lastEnd, m.index) + m[0])
-    lastEnd = m.index + m[0].length
-  }
+  // A sentence ends at punctuation, optionally followed by a closing quote,
+  // parenthesis or bracket, then whitespace or the end of the text. Matching
+  // lazily up to that boundary keeps a period inside a token, such as the
+  // dotted name partition.assignment.strategy, in its sentence. Text after the
+  // last match (an unterminated colon lead-in, for example) is dropped.
+  const sentences = normalized.match(/[\s\S]+?[.!?]+["')\]`]*(?:\s|$)/g)
 
   if (!sentences || sentences.length === 0) {
     let result = normalized
@@ -644,7 +633,8 @@ function buildFieldsTable (fields, capFn, opts = {}) {
       })
     }
 
-    const desc = info.description ? capFn(info.description) : '// TODO: Add description'
+    // A | in the description would end the cell and shift the row.
+    const desc = info.description ? capFn(info.description).replace(/\|/g, '\\|') : '// TODO: Add description'
 
     section += `|${fieldName}\n`
     section += `|${desc}\n`
@@ -687,18 +677,23 @@ function buildChangedDefaultsTable (changedDefaults, capFn) {
   for (const [, info] of Object.entries(byFieldAndDefaults)) {
     // Values render as literal inline code, so interpolations like
     // ${!uuid_v4()} and characters like * or _ show as typed.
+    // Values render as literal inline code through pass:c, which, unlike
+    // `+...+`, also keeps values with ++ or with spaces at either end. Strings
+    // that are empty, start or end with whitespace, or contain a newline show
+    // as JSON, so " " and "\n" read as the values they are.
     const formatDefault = (val) => {
       if (val === undefined || val === null) return 'none'
       let text
-      if (typeof val === 'string') text = val === '' ? '""' : val
+      if (typeof val === 'string') text = (val === '' || /^\s|\s$|\n/.test(val)) ? JSON.stringify(val) : val
       else if (typeof val === 'number' || typeof val === 'boolean') text = String(val)
       else text = JSON.stringify(val)
-      return `\`+${text.replace(/\|/g, '\\|')}+\``
+      return `\`pass:c[${text.replace(/\]/g, '\\]').replace(/\|/g, '\\|')}]\``
     }
 
     const oldVal = formatDefault(info.oldDefault)
     const newVal = formatDefault(info.newDefault)
-    const desc = info.description ? capFn(info.description) : '// TODO: Add description'
+    // A | in the description would end the cell and shift the row.
+    const desc = info.description ? capFn(info.description).replace(/\|/g, '\\|') : '// TODO: Add description'
 
     const byType = {}
     for (const comp of info.components) {

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

@@ -1,4 +1,4 @@
-// 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
+{{{generatedMarker "rpcn-connector-docs" "the Bloblang spec in redpanda-data/connect or redpanda-data/benthos" "This file is a doc-tools preview. The published partials are generated in redpanda-data/connect by `task docs`, and their first line names the file that registers the function or method. To change the text, edit the spec in that file."}}}
 
 = {{name}}
 {{#if signature}}

package/tools/redpanda-connect/templates/descriptions-partials.hbs

@@ -1,5 +1,5 @@
 {{#if (or summary description version)}}
-// This content is autogenerated. Do not edit manually. The summary and description come from the connector's definition in the Connect source. To change them, update the connector upstream, or use the doc-tools CLI with the --overrides option: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1247543314/Generate+reference+docs+for+Redpanda+Connect
+{{{generatedMarker "rpcn-connector-docs" "the component spec in redpanda-data/connect or redpanda-data/benthos" "The summary and description come from the component spec. This file is a doc-tools preview. The published partials are generated in redpanda-data/connect by `task docs`, and their first line names the file that registers the component. To change the text, edit the component spec in that file."}}}
 //
 // Pages consume this partial in two places so both stay fresh:
 //   header: include::...[tag=meta]  (sets :description: for search snippets and meta tags)

package/tools/redpanda-connect/templates/examples-partials.hbs

@@ -1,5 +1,5 @@
 {{#with examples}}
-// 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
+{{{generatedMarker "rpcn-connector-docs" "the component spec in redpanda-data/connect or redpanda-data/benthos" "This file is a doc-tools preview. The published partials are generated in redpanda-data/connect by `task docs`, and their first line names the file that registers the component. To change the text, edit the component spec in that file."}}}
 
 == Examples
 

package/tools/redpanda-connect/templates/fields-partials.hbs

@@ -1,11 +1,11 @@
 {{#if this.config.children}}
-// 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
+{{{generatedMarker "rpcn-connector-docs" "the component spec in redpanda-data/connect or redpanda-data/benthos" "This file is a doc-tools preview. The published partials are generated in redpanda-data/connect by `task docs`, and their first line names the file that registers the component. To change the text, edit the component spec in that file."}}}
 
 == Fields
 
 {{{renderConnectFields this.config.children}}}
 {{else if this.children}}
-// 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
+{{{generatedMarker "rpcn-connector-docs" "the component spec in redpanda-data/connect or redpanda-data/benthos" "This file is a doc-tools preview. The published partials are generated in redpanda-data/connect by `task docs`, and their first line names the file that registers the component. To change the text, edit the component spec in that file."}}}
 
 == Fields
 

package/tools/redpanda-connect/templates/metadata-partials.hbs

@@ -1,5 +1,5 @@
 {{#if (renderConnectMetadata description)}}
-// This content is autogenerated. Do not edit manually. Metadata fields come from the connector's description in the Connect source. To change them, update the connector description upstream, or use the doc-tools CLI with the --overrides option: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1247543314/Generate+reference+docs+for+Redpanda+Connect
+{{{generatedMarker "rpcn-connector-docs" "the component spec in redpanda-data/connect or redpanda-data/benthos" "Metadata fields come from the `== Metadata` section of the component description. This file is a doc-tools preview. The published partials are generated in redpanda-data/connect by `task docs`, and their first line names the file that registers the component. To change the text, edit the component spec in that file."}}}
 
 {{{renderConnectMetadata description}}}
 {{/if}}

package/tools/rpk-docs/generate-rpk-docs.js

@@ -11,6 +11,8 @@ Object.entries(helpers).forEach(([name, fn]) => {
     handlebars.registerHelper(name, fn)
   }
 })
+// The provenance marker command.hbs writes under the page header
+handlebars.registerHelper('generatedMarker', require('../../cli-utils/generated-marker').generatedMarker)
 
 // Template paths
 const TEMPLATES_DIR = path.resolve(__dirname, './templates')

package/tools/rpk-docs/generate-x-env-partial.js

@@ -28,17 +28,20 @@ const fs = require('fs')
 const os = require('os')
 const path = require('path')
 const { spawnSync } = require('child_process')
+const { generatedMarker } = require('../../cli-utils/generated-marker')
 
 // A healthy rpk exposes ~30 -X options. Refuse to overwrite the partial
 // with a suspiciously small table (for example, if -X list output ever
 // changes format and only partially parses).
 const MIN_OPTIONS = 20
 
+// The shared marker, so convert-to-markdown reports the partial as generated.
 const GENERATED_BANNER = `// tag::generated[]
-// Generated from rpk's own -X option data. Do not edit manually:
-// regenerate with doc-tools generate rpk-docs (which rewrites this
-// file alongside the rpk command pages) or, for a targeted refresh,
-// doc-tools generate rpk-env-partial.
+${generatedMarker(
+  'rpk-env-partial',
+  "rpk's own -X option data (rpk --print-tree)",
+  'Regenerate with doc-tools generate rpk-docs, which rewrites this file alongside the rpk command pages, or, for a targeted refresh, doc-tools generate rpk-env-partial.'
+)}
 `
 
 /**

package/tools/rpk-docs/helpers/index.js

@@ -426,7 +426,10 @@ function wrapDescriptionPassthrough(str) {
   if (!str) return ''
   // Check if contains backticks (inline code) or other formatting markers
   if (/`/.test(str)) {
-    return `pass:q[${str}]`
+    // pass:q[] skips special-character substitution, so a placeholder such as
+    // <agent> would reach the HTML raw and be dropped as an unknown tag.
+    const escaped = str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    return `pass:q[${escaped}]`
   }
   return str
 }

package/tools/rpk-docs/templates/command.hbs

@@ -22,7 +22,7 @@
 :page-deprecated: true
 {{/if}}
 
-// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc
+{{{generatedMarker "rpk-docs" "the rpk command help in redpanda-data/streaming-enterprise" "To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc"}}}
 {{#each pageAttributes}}
 :{{@key}}: {{this}}
 {{/each}}