@redpanda-data/docs-extensions-and-macros 5.37.0 → 5.37.2

package/extensions/render-property-descriptions.js

@@ -32,7 +32,9 @@
 
 const loadAsciiDoc = require('@antora/asciidoc-loader')
 const bigIntJson = require('../cli-utils/big-int-json')
-const { buildPageIndex, propertyAnchor } = require('../macros/prop')
+// compareTags is the one set-available-attachment-versions.js uses to pick the
+// tooltip dataset, so the build-time choice and the runtime fetch cannot disagree.
+const { buildPageIndex, propertyAnchor, compareTags } = require('../macros/prop')
 const { raiseListenerLimit } = require('./util/raise-listener-limit')
 
 const PROPERTIES_JSON_RX = /^redpanda-properties-(v\d+\.\d+\.\d+(?:-[\w.]+)?)\.json$/
@@ -57,7 +59,7 @@ module.exports.register = function () {
   // without that every <<anchor>> silently degraded to plain text.
   const anchorIndexes = new Map()
   this.once('contentClassified', ({ contentCatalog }) => {
-    for (const attachment of propertyAttachments(contentCatalog)) {
+    for (const attachment of newestPropertyAttachments(contentCatalog)) {
       const properties = readProperties(attachment, logger)
       if (!properties) continue
       const key = `${attachment.src.component}@${attachment.src.version || ''}`
@@ -72,7 +74,7 @@ module.exports.register = function () {
   // class="xref unresolved" while the same xref resolved fine on a real page.
   // Attachments are still published after this event.
   this.once('documentsConverted', ({ contentCatalog, siteAsciiDocConfig }) => {
-    const attachments = propertyAttachments(contentCatalog)
+    const attachments = newestPropertyAttachments(contentCatalog)
     if (!attachments.length) return
 
     for (const attachment of attachments) {
@@ -135,13 +137,13 @@ module.exports.register = function () {
       logger.info(`${where}: rendered ${rendered} property descriptions to HTML${failed ? `, ${failed} failed` : ''}`)
       if (unresolved.size) {
         logger.warn(
-          `${where}: ${unresolved.size} xref target(s) in property descriptions could not be resolved, so they stay as raw macros in the published attachment: ` +
+          `${where} (${basename(attachment)}): ${unresolved.size} xref target(s) in property descriptions could not be resolved, so they stay as raw macros in the published attachment: ` +
           `${[...unresolved].sort().join(', ')}.`
         )
       }
       if (brokenAnchors.size) {
         logger.warn(
-          `${where}: ${brokenAnchors.size} <<anchor>> reference(s) in property descriptions name no documented property, so they render as plain text: ` +
+          `${where} (${basename(attachment)}): ${brokenAnchors.size} <<anchor>> reference(s) in property descriptions name no documented property, so they render as plain text: ` +
           `${[...brokenAnchors].sort().join(', ')}. Property anchors replace dots with hyphens, so redpanda.storage.mode is <<redpanda-storage-mode>>. ` +
           'Fix them in the description or in docs-data/property-overrides.json.'
         )
@@ -160,6 +162,36 @@ function propertyAttachments (contentCatalog) {
   )
 }
 
+function tagOf (file) {
+  return basename(file).match(PROPERTIES_JSON_RX)[1]
+}
+
+
+/**
+ * The newest property dataset per component version, and only that one.
+ *
+ * A branch can ship more than one: doc-tools retains the 2 newest property
+ * JSONs on purpose, because the next generation run needs the older one as its
+ * --diff baseline. Only the newest is ever read as a dataset -- the docs UI
+ * resolves tooltips against available-properties-tag, which
+ * set-available-attachment-versions sets to the newest -- so rendering the
+ * older one is not just wasted work. This extension rewrites
+ * entry.description to resolve xrefs and then replaces the attachment
+ * contents, so converting a baseline would make the next diff report a
+ * description change for every property in it, and every dead <<anchor>> in a
+ * superseded dataset would be reported a second time against a file nobody
+ * publishes.
+ */
+function newestPropertyAttachments (contentCatalog) {
+  const newest = new Map()
+  for (const file of propertyAttachments(contentCatalog)) {
+    const key = `${file.src.component}@${file.src.version || ''}`
+    const held = newest.get(key)
+    if (!held || compareTags(tagOf(file), tagOf(held)) > 0) newest.set(key, file)
+  }
+  return [...newest.values()]
+}
+
 /**
  * Parse one dataset, or report why it is unusable and return undefined. Left
  * as-is on failure: the prop macro reports an unusable dataset with the detail,

package/extensions/util/scan-content-urls.js

@@ -13,6 +13,8 @@
  *
  * A block closes only on a delimiter of the same length as the one that opened
  * it; a longer run, such as the row of dashes in a rendered table, is content.
+ * - indented literal paragraphs: an indented line that opens a block is
+ *   rendered verbatim, so a URL on it is text and not a link
  * - line comments (//), which Asciidoctor drops entirely
  * - inline code spans (`...`)
  *
@@ -60,6 +62,23 @@ const ATTRIBUTE_REFERENCE_RX = /\{[a-zA-Z0-9_][a-zA-Z0-9_-]*\}/
 // prose cannot swallow the rest of the document.
 const MAX_WRAPPED_LABEL_LENGTH = 500
 
+// An indented line that opens a block is a literal paragraph: Asciidoctor
+// renders it verbatim, so any URL on it is text rather than a link. This is
+// where connector descriptions put their shell examples, which is how the
+// three comma-joined gcloud scope strings in google_drive_list_labels were
+// read as one URL and reported broken.
+const INDENTED_RX = /^[ \t]+\S/
+// Indentation does not make a literal paragraph out of a list item, a table
+// cell or a description list: Asciidoctor still parses those, so their links
+// are real. Verified against @asciidoctor/core, marker by marker (-, *, **,
+// ., .., 1., a., |, term::).
+const INDENTED_PARSED_RX = /^[ \t]+(?:[*.-]+[ \t]|\d+\.[ \t]|[a-zA-Z]\.[ \t]|\||\S.*::(?:[ \t]|$))/
+// Lines a block can start after, so an indented line that follows one opens a
+// literal paragraph: a list continuation (+), a block attribute list
+// ([source,yaml]) or a block title (.Title). A blank line and the close of a
+// delimited block do the same and are handled in the scan loop.
+const BLOCK_START_RX = /^(?:\+|\[.*\]|\.\S.*)$/
+
 // A delimiter run, plus the info string a fence may carry. Comment blocks
 // (////) come first in the alternation so a //// line is not mistaken for the
 // start of a line comment.
@@ -108,22 +127,48 @@ function closesBlock (delimiter, open) {
   return delimiter.char === open.char && delimiter.length === open.length && !delimiter.info
 }
 
+/**
+ * True when an indented line at the start of a block opens a literal
+ * paragraph, rather than continuing a construct Asciidoctor still parses.
+ */
+function opensLiteralParagraph (line) {
+  return INDENTED_RX.test(line) && !INDENTED_PARSED_RX.test(line)
+}
+
 function scanContentUrls (content) {
   const matches = []
   const lines = content.split('\n')
   let offset = 0
   let openDelimiter = null
+  // A literal paragraph runs from the indented line that opened it to the next
+  // blank line, and takes any unindented lines in between with it.
+  let inLiteralParagraph = false
+  // A block can start at the top of the file, and again after every line that
+  // ended the last one.
+  let atBlockStart = true
   for (const rawLine of lines) {
     const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine
     const delimiter = blockDelimiter(line)
     if (openDelimiter) {
       // Inside a block, only its own matching delimiter gets out. Anything
       // else on this line is content and is never scanned.
-      if (delimiter && closesBlock(delimiter, openDelimiter)) openDelimiter = null
+      if (delimiter && closesBlock(delimiter, openDelimiter)) {
+        openDelimiter = null
+        atBlockStart = true
+      }
     } else if (delimiter) {
       openDelimiter = delimiter
-    } else if (!LINE_COMMENT_RX.test(line)) {
-      scanLine(line, offset, matches, content)
+      inLiteralParagraph = false
+    } else {
+      const blank = !line.trim()
+      if (inLiteralParagraph) {
+        if (blank) inLiteralParagraph = false
+      } else if (atBlockStart && opensLiteralParagraph(line)) {
+        inLiteralParagraph = true
+      } else if (!LINE_COMMENT_RX.test(line)) {
+        scanLine(line, offset, matches, content)
+      }
+      atBlockStart = blank || BLOCK_START_RX.test(line)
     }
     offset += rawLine.length + 1
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.37.0",
+  "version": "5.37.2",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",