@redpanda-data/docs-extensions-and-macros 5.46.0 → 5.47.0

package/tools/property-extractor/helpers/audienceScope.js

@@ -0,0 +1,172 @@
+'use strict';
+
+// The two prefixes `related_topics` has used since it was free text, and the two
+// booleans `see_also` replaced them with. Both spellings stay supported: the
+// prefix is what 79 entries in the live overrides file are written as, and the
+// booleans are what a JSON schema can actually check.
+const CLOUD_PREFIX = 'cloud-only:';
+const SELF_MANAGED_PREFIX = 'self-managed-only:';
+
+/**
+ * Read the audience an override value is scoped to.
+ *
+ * One parser for every field that can be narrowed to a single docs build, so
+ * `see_also`, `links`, description paragraphs and admonitions cannot drift apart
+ * on how the scope is spelled. Strings carry the scope as a leading
+ * `cloud-only:` / `self-managed-only:` prefix; objects carry it as a
+ * `cloud_only` / `self_managed_only` boolean beside a `content` string
+ * (`self_hosted_only` is the deprecated spelling of the same flag).
+ *
+ * Setting both would wrap the value in `ifdef` and `ifndef` at once, so it would
+ * render in neither build. The schema rejects that on objects; on a string it
+ * cannot happen, since only one prefix can lead.
+ *
+ * @param {string|{content: string, cloud_only?: boolean, self_managed_only?: boolean}} item
+ * @returns {{content: string, cloudOnly: boolean, selfManagedOnly: boolean}|null} Null when the item carries no usable content.
+ */
+function parseAudience(item) {
+  if (typeof item === 'string') {
+    const trimmed = item.trim();
+    if (trimmed.startsWith(CLOUD_PREFIX)) {
+      return { content: trimmed.slice(CLOUD_PREFIX.length).trim(), cloudOnly: true, selfManagedOnly: false };
+    }
+    if (trimmed.startsWith(SELF_MANAGED_PREFIX)) {
+      return { content: trimmed.slice(SELF_MANAGED_PREFIX.length).trim(), cloudOnly: false, selfManagedOnly: true };
+    }
+    return { content: trimmed, cloudOnly: false, selfManagedOnly: false };
+  }
+  if (item && typeof item === 'object' && typeof item.content === 'string') {
+    return {
+      content: item.content.trim(),
+      cloudOnly: item.cloud_only === true,
+      // self_hosted_only is the old name for the same flag. The product is
+      // called Self-Managed and the string prefix has always been
+      // `self-managed-only:`, so one concept was going by two different words
+      // depending on whether you wrote it as a prefix or a boolean. Still read,
+      // because it is in the published schema, but nothing emits it.
+      selfManagedOnly: item.self_managed_only === true || item.self_hosted_only === true,
+    };
+  }
+  return null;
+}
+
+/**
+ * Wrap AsciiDoc in the conditional for one audience, or return it unchanged when
+ * it belongs in every build.
+ *
+ * The blank lines are not cosmetic. A conditional is resolved by the
+ * preprocessor, so one glued to neighbouring prose leaves those lines adjacent
+ * and Asciidoctor merges them into a single paragraph. Worse, the merge depends
+ * on the branch: a conditional wrapping a delimited block renders correctly with
+ * the attribute set and merges its neighbours with it unset, so a self-managed
+ * preview can look right while cloud-docs silently loses its paragraph breaks.
+ * Nothing errors and no text goes missing, so only a structural assertion on
+ * rendered HTML catches it -- see __tests__/tools/property-extractor/conditional-rendering.test.js.
+ *
+ * Emits the bare `endif::[]` and puts the cloud branch first, matching the
+ * convention already used throughout templates/property.hbs.
+ *
+ * @param {string} content - AsciiDoc to wrap.
+ * @param {{cloudOnly: boolean, selfManagedOnly: boolean}} scope - Audience, as returned by parseAudience.
+ * @returns {string} The content, wrapped in a blank-line-separated conditional when it is scoped.
+ */
+function wrapForAudience(content, scope) {
+  if (!scope || (!scope.cloudOnly && !scope.selfManagedOnly)) return content;
+  const directive = scope.cloudOnly ? 'ifdef::env-cloud[]' : 'ifndef::env-cloud[]';
+  return `\n${directive}\n${content}\nendif::[]\n`;
+}
+
+/**
+ * Build the paired conditional for a value that differs by audience, so each
+ * build sees its own form of the same passage.
+ *
+ * Used where a link cannot survive in one build -- a cross-page xref to a page
+ * Cloud does not publish -- and the sentence still has to read correctly there.
+ * Cloud branch first, same as wrapForAudience.
+ *
+ * @param {string} cloudContent - What the Cloud build shows.
+ * @param {string} selfManagedContent - What the self-managed build shows.
+ * @returns {string} Both branches, blank-line separated.
+ */
+function wrapBothAudiences(cloudContent, selfManagedContent) {
+  if (cloudContent === selfManagedContent) return cloudContent;
+  // A blank line between the two directive pairs, not just around the
+  // whole block. Nothing downstream of this function currently calls it
+  // twice for overlapping text (applyLinksToText groups every scoped spec
+  // matching one paragraph into a single call), so nothing today depends on
+  // this specific line -- but paragraphBounds treats an unbroken run of
+  // conditional directives as ONE paragraph, exactly the mechanism that let
+  // a second duplication nest inside a first one's endif::[]/ifndef::[]
+  // pair with no blank line to stop it. Kept here too, defensively, so a
+  // future caller of this function alone does not have to rediscover that.
+  return [
+    '',
+    'ifdef::env-cloud[]',
+    cloudContent,
+    'endif::[]',
+    '',
+    'ifndef::env-cloud[]',
+    selfManagedContent,
+    'endif::[]',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Find conditionals that are glued to neighbouring content.
+ *
+ * The complement to the cross-branch paragraph check in the corpus tests, and
+ * the only one of the two that catches the symmetric case. When a conditional in
+ * prose has no blank line before it, both builds merge the neighbouring
+ * paragraphs, so comparing the two renders sees no difference and reports
+ * nothing -- yet both are wrong. Reading the source catches it.
+ *
+ * Scoped to prose: a conditional whose neighbour is a table row (`|`), a block
+ * delimiter, a block attribute line (`[...]`), a list item or another
+ * conditional is left alone. Table cells have carried their own conditional
+ * shape since long before this, and a delimiter terminates the paragraph on its
+ * own.
+ *
+ * @param {string} text - AsciiDoc to inspect.
+ * @returns {Array<{line: number, directive: string, neighbour: string, side: ('before'|'after')}>}
+ */
+function findGluedConditionals(text) {
+  if (typeof text !== 'string' || !text.includes('::')) return [];
+  const lines = text.split('\n');
+  const offenders = [];
+  const selfTerminating = (line) => {
+    const t = line.trim();
+    if (t === '') return true;
+    if (/^if(n?)def::/.test(t) || t === 'endif::[]') return true;
+    if (/^(?:-{4,}|={4,}|\.{4,}|\*{4,}|_{4,}|\+{4,}|\/{4,})$/.test(t)) return true;
+    if (/^\[.*\]$/.test(t)) return true;          // block attribute, e.g. [NOTE] or [cols="1s,2a"]
+    if (/^[|!]/.test(t)) return true;             // table row or cell
+    if (/^[*.-]+\s/.test(t) || /^\d+\.\s/.test(t)) return true; // list item
+    if (/^\.\S/.test(t)) return true;             // block title, e.g. .Enterprise license required
+    return false;
+  };
+  lines.forEach((line, i) => {
+    const trimmed = line.trim();
+    if (/^if(n?)def::/.test(trimmed)) {
+      const before = i === 0 ? '' : lines[i - 1];
+      if (!selfTerminating(before)) {
+        offenders.push({ line: i + 1, directive: trimmed, neighbour: before.trim(), side: 'before' });
+      }
+    }
+    if (trimmed === 'endif::[]') {
+      const after = i === lines.length - 1 ? '' : lines[i + 1];
+      if (!selfTerminating(after)) {
+        offenders.push({ line: i + 1, directive: trimmed, neighbour: after.trim(), side: 'after' });
+      }
+    }
+  });
+  return offenders;
+}
+
+module.exports = parseAudience;
+module.exports.parseAudience = parseAudience;
+module.exports.wrapForAudience = wrapForAudience;
+module.exports.wrapBothAudiences = wrapBothAudiences;
+module.exports.findGluedConditionals = findGluedConditionals;
+module.exports.CLOUD_PREFIX = CLOUD_PREFIX;
+module.exports.SELF_MANAGED_PREFIX = SELF_MANAGED_PREFIX;

package/tools/property-extractor/helpers/findAudienceScopeProblems.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const { CLOUD_PREFIX, SELF_MANAGED_PREFIX } = require('./audienceScope.js');
+
+// A prefix that was clearly MEANT to scope a value to one docs build, spelled
+// in a way the parser does not accept. Deliberately generous: underscores for
+// hyphens, a space before the colon, any casing, a missing separator, and the
+// retired `self-hosted-only` product name.
+//
+// Why this matters more than an unmatched link: an unrecognised prefix is not
+// dropped, it is published. `cloud_only: Cloud clusters require...` renders on
+// the page as that literal string, prefix and all, in both builds. Nothing
+// errors, nothing is missing, and the only way to notice is to read the
+// rendered page.
+const SUSPICIOUS_PREFIX = /^[\s]*((?:cloud|self[-_ ]?managed|self[-_ ]?hosted)[-_ ]?only)[\s]*:/i;
+
+// Keys that look like an attempt at the audience booleans but are not the two
+// the templates read. `self_hosted_only` is absent on purpose: it is the
+// deprecated spelling and parseAudience still honours it.
+const VALID_FLAGS = new Set(['cloud_only', 'self_managed_only', 'self_hosted_only']);
+const SUSPICIOUS_FLAG = /^(?:cloud|self[-_ ]?managed|self[-_ ]?hosted)[-_ ]?only$/i;
+
+/**
+ * Report a string whose leading prefix looks like a failed audience scope.
+ *
+ * @param {unknown} value
+ * @returns {string|null} The offending prefix, or null when the value is fine.
+ */
+function findSuspiciousPrefix (value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  // An exact prefix is correct by definition, so check those first.
+  if (trimmed.startsWith(CLOUD_PREFIX) || trimmed.startsWith(SELF_MANAGED_PREFIX)) return null;
+  const match = SUSPICIOUS_PREFIX.exec(trimmed);
+  return match ? match[1] : null;
+}
+
+/**
+ * Report object keys that look like an attempt at the audience booleans.
+ *
+ * A misspelled flag is silent in a different way: the template's `{{#if
+ * cloud_only}}` is simply false, so the value renders in BOTH builds rather
+ * than the one the writer scoped it to.
+ *
+ * @param {unknown} item
+ * @returns {string[]} The offending key names.
+ */
+function findSuspiciousFlags (item) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return [];
+  return Object.keys(item).filter((key) => !VALID_FLAGS.has(key) && SUSPICIOUS_FLAG.test(key));
+}
+
+function pushPrefix (problems, property, field, value) {
+  const prefix = findSuspiciousPrefix(value);
+  if (prefix) {
+    problems.push({
+      property,
+      field,
+      problem: 'unrecognized-prefix',
+      detail: prefix,
+      text: String(value).trim().slice(0, 120)
+    });
+  }
+}
+
+function pushFlags (problems, property, field, item) {
+  for (const key of findSuspiciousFlags(item)) {
+    problems.push({ property, field, problem: 'unrecognized-flag', detail: key, text: '' });
+  }
+}
+
+/**
+ * Walk every audience-scopable field on every property and report the scopes
+ * that will not take effect.
+ *
+ * Run BEFORE applyPropertyLinks: that pass flattens an array description into
+ * a single string, after which a per-paragraph prefix can no longer be
+ * attributed to the paragraph it came from.
+ *
+ * @param {Record<string, object>} properties
+ * @returns {Array<{property: string, field: string, problem: string, detail: string, text: string}>}
+ */
+function findAudienceScopeProblems (properties) {
+  const problems = [];
+  for (const [name, prop] of Object.entries(properties || {})) {
+    if (!prop || typeof prop !== 'object') continue;
+
+    if (Array.isArray(prop.description)) {
+      prop.description.forEach((para, i) => pushPrefix(problems, name, `description[${i}]`, para));
+    }
+
+    if (prop.links && typeof prop.links === 'object') {
+      for (const [key, value] of Object.entries(prop.links)) {
+        pushPrefix(problems, name, `links["${key}"]`, value);
+      }
+    }
+
+    // Both spellings: `related_topics` is the field 118 live entries use, and
+    // `see_also` is what replaced it.
+    for (const field of ['see_also', 'related_topics']) {
+      const items = prop[field];
+      if (!Array.isArray(items)) continue;
+      items.forEach((item, i) => {
+        pushPrefix(problems, name, `${field}[${i}]`, item);
+        pushFlags(problems, name, `${field}[${i}]`, item);
+      });
+    }
+
+    for (const field of ['admonitions', 'includes']) {
+      const items = prop[field];
+      if (!Array.isArray(items)) continue;
+      items.forEach((item, i) => pushFlags(problems, name, `${field}[${i}]`, item));
+    }
+  }
+  return problems;
+}
+
+module.exports = findAudienceScopeProblems;
+module.exports.findAudienceScopeProblems = findAudienceScopeProblems;
+module.exports.findSuspiciousPrefix = findSuspiciousPrefix;
+module.exports.findSuspiciousFlags = findSuspiciousFlags;

package/tools/property-extractor/helpers/index.js

@@ -17,6 +17,9 @@ module.exports = {
   normalizePropertyAnchors: require('./normalizePropertyAnchors.js'),
   canonicalizePropertyXrefs: require('./canonicalizePropertyXrefs.js'),
   seeAlsoView: require('./seeAlsoView.js'),
+  audienceScope: require('./audienceScope.js'),
+  applyPropertyLinks: require('./applyPropertyLinks.js'),
+  findAudienceScopeProblems: require('./findAudienceScopeProblems.js'),
   capitalize: require('./capitalize.js'),
   length: require('./length.js'),
 };

package/tools/property-extractor/helpers/seeAlsoView.js

@@ -1,12 +1,14 @@
 'use strict';
 
+const parseAudience = require('./audienceScope.js');
+
 /**
  * Normalizes a property's related-topics data into one shape for the
  * templates to render, regardless of which field or convention the override
  * author used:
  *
  *   - see_also (current): array of items, each either a plain string (shown
- *     everywhere) or {content, cloud_only, self_hosted_only} (shown only in
+ *     everywhere) or {content, cloud_only, self_managed_only} (shown only in
  *     the named build). Schema-validated — see docs-data/property-overrides.schema.json.
  *   - related_topics (deprecated, still read for back-compat with existing
  *     override files): array of strings, optionally prefixed with
@@ -14,8 +16,11 @@
  *     behaviour. That prefix was free text with no validation; see_also
  *     replaces it with data a schema can check.
  *
+ * Both spellings are read by the shared helpers/audienceScope.js parser, which
+ * every audience-scoped override field uses, so they cannot drift apart.
+ *
  * @param {object} property - A property record, as extracted or overridden.
- * @returns {Array<{content: string, cloudOnly: boolean, selfHostedOnly: boolean}>}
+ * @returns {Array<{content: string, cloudOnly: boolean, selfManagedOnly: boolean}>}
  */
 function normalizeSeeAlso(property) {
   if (!property) return [];
@@ -26,26 +31,7 @@ function normalizeSeeAlso(property) {
       : [];
 
   return rawItems
-    .map((item) => {
-      if (typeof item === 'string') {
-        const trimmed = item.trim();
-        if (trimmed.startsWith('cloud-only:')) {
-          return { content: trimmed.slice('cloud-only:'.length).trim(), cloudOnly: true, selfHostedOnly: false };
-        }
-        if (trimmed.startsWith('self-managed-only:')) {
-          return { content: trimmed.slice('self-managed-only:'.length).trim(), cloudOnly: false, selfHostedOnly: true };
-        }
-        return { content: trimmed, cloudOnly: false, selfHostedOnly: false };
-      }
-      if (item && typeof item === 'object' && typeof item.content === 'string') {
-        return {
-          content: item.content.trim(),
-          cloudOnly: item.cloud_only === true,
-          selfHostedOnly: item.self_hosted_only === true,
-        };
-      }
-      return null;
-    })
+    .map((item) => parseAudience(item))
     .filter((item) => item && item.content);
 }
 
@@ -56,7 +42,7 @@ function normalizeSeeAlso(property) {
  * once instead of duplicated per item.
  *
  * sectionType is 'cloud' only when every item is cloud-only, 'self-managed'
- * only when every item is self-hosted-only, and 'normal' otherwise (a mix of
+ * only when every item is self-managed-only, and 'normal' otherwise (a mix of
  * conditional and/or unconditional items, each wrapped individually).
  *
  * @param {object} property - A property record, as extracted or overridden.
@@ -67,7 +53,7 @@ function seeAlsoView(property) {
   let sectionType = 'normal';
   if (items.length > 0) {
     if (items.every((item) => item.cloudOnly)) sectionType = 'cloud';
-    else if (items.every((item) => item.selfHostedOnly)) sectionType = 'self-managed';
+    else if (items.every((item) => item.selfManagedOnly)) sectionType = 'self-managed';
   }
   return { items, sectionType };
 }

package/tools/property-extractor/property_extractor.py

@@ -1243,15 +1243,43 @@ def _normalize_admonitions(admonitions):
                 continue
             if entry["title"]:
                 normalized_entry["title"] = entry["title"]
+        # The entry is rebuilt rather than copied, so every field the templates
+        # read has to be carried across explicitly. These two scope the whole
+        # admonition block to one docs build; setting both would wrap it in
+        # ifdef and ifndef at once so it rendered in neither, which the schema
+        # rejects and the generator drops with a warning.
+        if entry.get("cloud_only") is True:
+            normalized_entry["cloud_only"] = True
+        # self_hosted_only is the deprecated spelling of self_managed_only, read
+        # so an override written against the older schema still scopes, and
+        # normalized to the current name so only one spelling reaches the
+        # templates.
+        if entry.get("self_managed_only") is True or entry.get("self_hosted_only") is True:
+            normalized_entry["self_managed_only"] = True
         normalized.append(normalized_entry)
     return normalized
 
 
 def _apply_override_to_existing_property(property_dict, override, overrides_file_path):
     """Apply overrides to an existing property."""
-    # Apply description override
+    # Apply description override. Either a plain string or, when a paragraph has
+    # to be scoped to one docs build, an array of paragraphs; the generator
+    # flattens the array into AsciiDoc so the audience conditional never has to
+    # be hand-written into the JSON string.
     if "description" in override:
         property_dict["description"] = override["description"]
+
+    # Declared links: {"<text in the prose>": "<target>"}. Carried through as
+    # data and turned into AsciiDoc by the generator, which is what keeps the
+    # description itself plain prose the overrides audit can compare to source.
+    if "links" in override:
+        property_dict["links"] = override["links"]
+
+    # Shared partials pulled into the property entry (the "internal use only"
+    # warning, the HTTP Proxy breaking-change notice). Carried as data so the
+    # description stays prose the overrides audit can compare against source.
+    if "includes" in override:
+        property_dict["includes"] = override["includes"]
     
     # Apply version override (introduced in version)
     if "version" in override:
@@ -1282,7 +1310,7 @@ def _apply_override_to_existing_property(property_dict, override, overrides_file
             logger.warning(f"related_topics for property must be an array")
 
     # Apply see_also override. Structural shape (plain string, or an object
-    # naming exactly one of cloud_only/self_hosted_only) is enforced by
+    # naming exactly one of cloud_only/self_managed_only) is enforced by
     # docs-data/property-overrides.schema.json via `doc-tools validate
     # property-overrides`, not here — this just passes the data through for
     # seeAlsoView.js to normalize at render time.

package/tools/property-extractor/templates/property.hbs

@@ -27,10 +27,34 @@ endif::[]
 
 No description available.
 
+{{/if}}
+{{#if includes}}
+{{#each includes}}
+
+{{#if cloud_only}}
+ifdef::env-cloud[]
+{{/if}}
+{{#if self_managed_only}}
+ifndef::env-cloud[]
+{{/if}}
+include::{{{target}}}
+{{#if cloud_only}}
+endif::[]
+{{/if}}
+{{#if self_managed_only}}
+endif::[]
+{{/if}}
+{{/each}}
 {{/if}}
 {{#if admonitions}}
 {{#each admonitions}}
 
+{{#if cloud_only}}
+ifdef::env-cloud[]
+{{/if}}
+{{#if self_managed_only}}
+ifndef::env-cloud[]
+{{/if}}
 {{#if title}}
 .{{{title}}}
 {{/if}}
@@ -38,6 +62,12 @@ No description available.
 ====
 {{{text}}}
 ====
+{{#if cloud_only}}
+endif::[]
+{{/if}}
+{{#if self_managed_only}}
+endif::[]
+{{/if}}
 {{/each}}
 {{/if}}
 {{#if is_enterprise}}
@@ -222,7 +252,7 @@ endif::[]
 ifdef::env-cloud[]
 * {{{content}}}
 endif::[]
-{{else if selfHostedOnly}}
+{{else if selfManagedOnly}}
 ifndef::env-cloud[]
 * {{{content}}}
 endif::[]
@@ -236,7 +266,7 @@ endif::[]
 ifdef::env-cloud[]
 {{{content}}}
 endif::[]
-{{else if selfHostedOnly}}
+{{else if selfManagedOnly}}
 ifndef::env-cloud[]
 {{{content}}}
 endif::[]

package/tools/property-extractor/templates/topic-property.hbs

@@ -25,10 +25,34 @@
 
 No description available.
 
+{{/if}}
+{{#if includes}}
+{{#each includes}}
+
+{{#if cloud_only}}
+ifdef::env-cloud[]
+{{/if}}
+{{#if self_managed_only}}
+ifndef::env-cloud[]
+{{/if}}
+include::{{{target}}}
+{{#if cloud_only}}
+endif::[]
+{{/if}}
+{{#if self_managed_only}}
+endif::[]
+{{/if}}
+{{/each}}
 {{/if}}
 {{#if admonitions}}
 {{#each admonitions}}
 
+{{#if cloud_only}}
+ifdef::env-cloud[]
+{{/if}}
+{{#if self_managed_only}}
+ifndef::env-cloud[]
+{{/if}}
 {{#if title}}
 .{{{title}}}
 {{/if}}
@@ -36,6 +60,12 @@ No description available.
 ====
 {{{text}}}
 ====
+{{#if cloud_only}}
+endif::[]
+{{/if}}
+{{#if self_managed_only}}
+endif::[]
+{{/if}}
 {{/each}}
 {{/if}}
 {{#if is_enterprise}}
@@ -179,7 +209,7 @@ endif::[]
 ifdef::env-cloud[]
 * {{{content}}}
 endif::[]
-{{else if selfHostedOnly}}
+{{else if selfManagedOnly}}
 ifndef::env-cloud[]
 * {{{content}}}
 endif::[]
@@ -193,7 +223,7 @@ endif::[]
 ifdef::env-cloud[]
 {{{content}}}
 endif::[]
-{{else if selfHostedOnly}}
+{{else if selfManagedOnly}}
 ifndef::env-cloud[]
 {{{content}}}
 endif::[]