@redpanda-data/docs-extensions-and-macros 4.12.6 → 4.13.1

package/macros/USER_GUIDE.adoc

@@ -0,0 +1,220 @@
+= AsciiDoc Macros User Guide
+:toc:
+:toclevels: 3
+
+Complete guide to using AsciiDoc macros in your documentation.
+
+== Getting started
+
+=== Installation
+
+Install the package:
+
+[,bash]
+----
+npm i @redpanda-data/docs-extensions-and-macros
+----
+
+=== Configuration
+
+Register macros in your Antora playbook under `asciidoc.extensions`:
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/glossary'
+    - '@redpanda-data/docs-extensions-and-macros/macros/config-ref'
+    - '@redpanda-data/docs-extensions-and-macros/macros/helm-ref'
+----
+
+IMPORTANT: Use `asciidoc.extensions` for macros, not `antora.extensions`.
+
+== Using macros
+
+=== glossterm - Glossary terms
+
+Reference glossary terms with tooltips:
+
+[,asciidoc]
+----
+The glossterm:partition[partition] stores data.
+glossterm:broker[broker,A server that handles requests]
+----
+
+*Syntax:* `glossterm:term[definition]`
+
+* `term` - The term to reference (required)
+* `definition` - Custom definition (optional, uses global glossary by default)
+
+=== config_ref - Configuration references
+
+Link to configuration properties:
+
+[,asciidoc]
+----
+config_ref:log.retention.ms,true,tunable-properties[]
+config_ref:cleanup.policy,false[]
+----
+
+*Syntax:* `config_ref:property,isLink,path[]`
+
+* `property` - Configuration property name (required)
+* `isLink` - Whether to create a link (true/false, required)
+* `path` - Document path for link (required if isLink is true)
+
+=== helm_ref - Helm value references
+
+Link to Helm chart values:
+
+[,asciidoc]
+----
+helm_ref:storage.tieredConfig.cloud_storage_enabled[]
+helm_ref:[]
+----
+
+*Syntax:* `helm_ref:value[]`
+
+* `value` - Helm value path (optional, links to values.yaml overview if omitted)
+
+=== components_by_category - Component display
+
+Display Redpanda Connect components by category:
+
+[,asciidoc]
+----
+components_by_category::inputs[]
+components_by_category::outputs[]
+components_by_category::processors[]
+----
+
+*Syntax:* `components_by_category::[type]`
+
+* `type` - Component type (inputs, outputs, processors, etc.)
+
+=== component_table - Component table
+
+Generate searchable component table:
+
+[,asciidoc]
+----
+component_table::[]
+----
+
+Generates a searchable table of all components with filters.
+
+=== component_type_dropdown - Type switcher
+
+Create dropdown for switching between component types:
+
+[,asciidoc]
+----
+component_type_dropdown::[]
+----
+
+Generates a dropdown to switch between different implementations of the same component.
+
+== Configuration options
+
+=== Glossary configuration
+
+Configure glossary behavior in playbook:
+
+[,yaml]
+----
+asciidoc:
+  attributes:
+    glossary-tooltip: data-tooltip  # Enable tooltips
+    glossary-page: glossary.adoc    # Link target
+    glossary-links: true             # Enable links
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/glossary'
+----
+
+*Options:*
+
+* `glossary-tooltip` - Tooltip implementation (title, true, or data-attribute-name)
+* `glossary-page` - Page to link glossary terms to
+* `glossary-links` - Enable/disable links (default: true)
+* `glossary-term-role` - CSS role for terms (default: glossary-term)
+
+== Troubleshooting
+
+=== Macro not rendering
+
+*Problem:* Macro appears as plain text
+
+*Solutions:*
+
+* Verify macro is registered under `asciidoc.extensions`
+* Check macro syntax is correct
+* Ensure package is installed
+* Try rebuilding: `npx antora playbook.yml`
+
+=== Glossary terms not found
+
+*Problem:* Glossary definitions missing
+
+*Solutions:*
+
+* Define terms in shared component or local `antora.yml`
+* Check term spelling matches exactly
+* Provide inline definition as fallback
+
+=== Links not working
+
+*Problem:* config_ref or helm_ref links broken
+
+*Solutions:*
+
+* Verify target page exists
+* Check path is relative to reference module
+* Ensure property/value name is correct
+
+=== Component macros empty
+
+*Problem:* components_by_category shows no components
+
+*Solutions:*
+
+* Ensure component aggregator extension is enabled
+* Check component data is generated
+* Verify component type is correct
+
+== Best practices
+
+=== Use glossary terms consistently
+
+[,asciidoc]
+----
+✓ Good: glossterm:partition[]
+✗ Bad:  partition (without macro)
+----
+
+=== Provide fallback definitions
+
+[,asciidoc]
+----
+glossterm:custom-term[A definition in case term isn't in glossary]
+----
+
+=== Link to configuration when relevant
+
+[,asciidoc]
+----
+To configure retention, set config_ref:log.retention.ms,true,tunable-properties[].
+----
+
+=== Keep macro usage readable
+
+[,asciidoc]
+----
+✓ Good: Configure config_ref:retention.ms,true,topic-properties[].
+✗ Bad:  config_ref:retention.ms,true,topic-properties[]config_ref:cleanup.policy,true,topic-properties[].
+----
+
+== Related documentation
+
+* link:REFERENCE.adoc[Macros reference] - Complete macro documentation
+* link:DEVELOPMENT.adoc[Development guide] - How to create new macros
+* https://docs.asciidoctor.org/asciidoc/latest/macros/[AsciiDoc Macro Syntax]

package/macros/rp-connect-components.js

@@ -273,10 +273,10 @@ module.exports.register = function (registry, context) {
    *
    * @returns {Object} - An object with two properties:
    *   - `certified`: An array of SQL drivers with 'certified' support level. Each driver contains:
-   *     - `commercialName`: The trimmed commercial name of the driver (e.g., 'PostgreSQL').
+   *     - `commercialName`: The trimmed commercial name of the driver (for example, 'PostgreSQL').
    *     - `isCloudSupported`: A boolean indicating whether the driver supports cloud.
    *   - `community`: An array of SQL drivers with 'community' support level. Each driver contains:
-   *     - `commercialName`: The trimmed commercial name of the driver (e.g., 'Trino').
+   *     - `commercialName`: The trimmed commercial name of the driver (for example, 'Trino').
    *     - `isCloudSupported`: A boolean indicating whether the driver supports cloud.
    *
    * Example return structure:
@@ -330,7 +330,7 @@ module.exports.register = function (registry, context) {
    * @param {Object} connectors - An object containing the connector data, where each key is a connector name and
    *   each value contains details about its types, licensing, and cloud support.
    *   {
-   *     types: Map - A map of connector types (e.g., Input, Output, Processor), with associated commercial names.
+   *     types: Map - A map of connector types (for example, Input, Output, Processor), with associated commercial names.
    *     isLicensed: 'Yes' or 'No' - Indicates if the connector requires an enterprise license.
    *     isCloudConnectorSupported: true or false - Indicates if any type for this connector supports Redpanda Cloud.
    *   }
@@ -340,7 +340,7 @@ module.exports.register = function (registry, context) {
    *     community: Array<{ commercialName: string, isCloudSupported: boolean }>
    *   }
    * @param {boolean} isCloud - A flag indicating whether to filter by cloud support. If true, only cloud-supported connectors are shown.
-   * @param {boolean} showAllInfo - A flag indicating whether to show all information or limit the data displayed (e.g., for cloud-only views).
+   * @param {boolean} showAllInfo - A flag indicating whether to show all information or limit the data displayed (for example, for cloud-only views).
    *
    * @returns {string} - A string containing the generated HTML for the connectors table rows.
    *   The output is a string of HTML rows with the following columns:
@@ -831,7 +831,7 @@ module.exports.register = function (registry, context) {
               // Generic fallback for words ending in 's Selected'
               return pluralText.replace(/s Selected$/, ' Selected');
             } else if (pluralText.endsWith('ies Selected')) {
-              // Handle words ending in 'ies' (e.g., "Categories Selected" -> "Category Selected")
+              // Handle words ending in 'ies' (for example, "Categories Selected" -> "Category Selected")
               return pluralText.replace(/ies Selected$/, 'y Selected');
             } else {
               // If no pattern matches, return as-is
@@ -984,7 +984,7 @@ module.exports.register = function (registry, context) {
     self.named('component_type_dropdown');
     self.process((parent, target, attrs) => {
       const attributes = parent.getDocument().getAttributes();
-      const component = attributes['page-component-title'];  // Current component (e.g., 'Redpanda Cloud' or 'Redpanda Connect')
+      const component = attributes['page-component-title'];  // Current component (for example, 'Redpanda Cloud' or 'Redpanda Connect')
       const name = attributes['doctitle'];
       const type = attributes['type'];
       if (!name || !type) {

package/mcp/CLI_INTERFACE.adoc

@@ -0,0 +1,384 @@
+= CLI Interface Contract
+:toc:
+:toclevels: 3
+
+This document describes the CLI interface contract that the MCP server depends on. These contracts are verified by the CLI contract tests to ensure the MCP server continues to work as expected when the CLI changes.
+
+The MCP server wraps the `npx doc-tools` CLI to provide a natural language interface to Claude Code. The CLI must maintain specific commands, flags, and output formats for the MCP server to function correctly.
+
+== Command structure
+
+All commands follow the pattern:
+
+[,bash]
+----
+npx doc-tools <command> [subcommand] [flags]
+----
+
+== Top-level commands
+
+=== generate
+
+Generate various types of documentation.
+
+[,bash]
+----
+npx doc-tools generate <subcommand> [flags]
+----
+
+Subcommands are documented in the <<Generate subcommands>> section.
+
+=== get-redpanda-version
+
+Get the latest Redpanda version information.
+
+[,bash]
+----
+npx doc-tools get-redpanda-version [--beta]
+----
+
+*Output format:*
+
+[,bash]
+----
+REDPANDA_VERSION=v25.3.1
+REDPANDA_DOCKER_TAG=docker.redpanda.com/redpandadata/redpanda:v25.3.1
+REDPANDA_RELEASE_NOTES=https://github.com/redpanda-data/redpanda/releases/tag/v25.3.1
+----
+
+*Flags:*
+
+--beta:: Get the latest beta/RC version instead of stable (optional)
+
+=== get-console-version
+
+Get the latest Redpanda Console version information.
+
+[,bash]
+----
+npx doc-tools get-console-version
+----
+
+*Output format:*
+
+[,bash]
+----
+CONSOLE_VERSION=v2.7.2
+CONSOLE_DOCKER_TAG=docker.redpanda.com/redpandadata/console:v2.7.2
+CONSOLE_RELEASE_NOTES=https://github.com/redpanda-data/console/releases/tag/v2.7.2
+----
+
+=== --version
+
+Display the doc-tools version.
+
+[,bash]
+----
+npx doc-tools --version
+----
+
+*Output format:*
+
+[,bash]
+----
+<major>.<minor>.<patch>
+----
+
+Example: `1.2.3`
+
+== Generate subcommands
+
+=== property-docs
+
+Generate Redpanda configuration property documentation.
+
+[,bash]
+----
+npx doc-tools generate property-docs --tag <version> [options]
+----
+
+*Required flags:*
+
+--tag:: Redpanda version to generate docs for (for example, `v25.3.1`, `25.3.1`, or `latest`)
+
+*Optional flags:*
+
+--generate-partials:: Generate AsciiDoc partials in addition to JSON
+--cloud-support:: Include cloud support information
+--overrides:: Path to property overrides JSON file
+
+*Output:*
+
+Creates one or more of:
+
+* `modules/reference/partials/properties.json`
+* `modules/reference/partials/cluster-properties.adoc` (with `--generate-partials`)
+* `modules/reference/partials/broker-properties.adoc` (with `--generate-partials`)
+* `modules/reference/partials/tunable-properties.adoc` (with `--generate-partials`)
+* `modules/reference/partials/topic-properties.adoc` (with `--generate-partials`)
+
+=== metrics-docs
+
+Generate Redpanda metrics documentation.
+
+[,bash]
+----
+npx doc-tools generate metrics-docs --tag <version>
+----
+
+*Required flags:*
+
+--tag:: Redpanda version to generate docs for
+
+*Output:*
+
+Creates `modules/reference/pages/public-metrics-reference.adoc`
+
+=== rpk-docs
+
+Generate RPK command-line documentation.
+
+[,bash]
+----
+npx doc-tools generate rpk-docs --tag <version>
+----
+
+*Required flags:*
+
+--tag:: Redpanda version to generate docs for
+
+*Output:*
+
+Creates AsciiDoc files in `autogenerated/v<version>/rpk/`
+
+=== rpcn-connector-docs
+
+Generate Redpanda Connect connector documentation.
+
+[,bash]
+----
+npx doc-tools generate rpcn-connector-docs [options]
+----
+
+*Optional flags:*
+
+--fetch-connectors:: Fetch connector definitions from Redpanda Connect repository
+--draft-missing:: Create draft pages for missing connectors
+--update-whats-new:: Update the what's new page
+--include-bloblang:: Include Bloblang documentation
+--data-dir:: Directory containing connector data
+--old-data:: Path to previous connector data for comparison
+--csv:: Export connector data as CSV
+--overrides:: Path to overrides JSON file
+
+*Output:*
+
+Creates component documentation files in `modules/reference/pages/redpanda-connect/components/`
+
+=== helm-spec
+
+Generate Helm chart specification documentation.
+
+[,bash]
+----
+npx doc-tools generate helm-spec [options]
+----
+
+*Optional flags:*
+
+--chart-dir:: Path to Helm chart directory
+--tag:: Helm chart version
+--readme:: Include README content
+--output-dir:: Output directory for generated files
+--output-suffix:: Suffix for output files
+
+=== cloud-regions
+
+Generate cloud regions documentation.
+
+[,bash]
+----
+npx doc-tools generate cloud-regions [options]
+----
+
+*Optional flags:*
+
+--output:: Output file path
+--format:: Output format (json, yaml, adoc)
+--owner:: GitHub repository owner
+--repo:: GitHub repository name
+--path:: Path to regions file in repository
+--ref:: Git reference (branch, tag, commit)
+--template:: AsciiDoc template file
+--dry-run:: Show what would be generated without writing files
+
+=== crd-spec
+
+Generate Custom Resource Definition (CRD) specification documentation.
+
+[,bash]
+----
+npx doc-tools generate crd-spec --tag <version> [options]
+npx doc-tools generate crd-spec --branch <branch> [options]
+----
+
+*Required flags (one of):*
+
+--tag:: Redpanda Operator version tag (for released content)
+--branch:: Branch name (for in-progress content)
+
+*Optional flags:*
+
+--source-path:: Path to CRD source files
+--depth:: Maximum depth for nested properties
+--templates-dir:: Directory containing documentation templates
+--output:: Output directory
+
+=== bundle-openapi
+
+Bundle OpenAPI specifications.
+
+[,bash]
+----
+npx doc-tools generate bundle-openapi --tag <version> [options]
+----
+
+*Required flags:*
+
+--tag:: Redpanda version for API specifications
+
+*Optional flags:*
+
+--repo:: Repository to fetch from
+--surface:: API surface to bundle (admin, connect, or both)
+--out-admin:: Output path for admin API bundle
+--out-connect:: Output path for connect API bundle
+--admin-major:: Major version for admin API
+--use-admin-major-version:: Use major version in admin API bundle
+--quiet:: Suppress output messages
+
+== Output format contracts
+
+=== Version commands
+
+Version commands (`get-redpanda-version`, `get-console-version`) must output key-value pairs in the format:
+
+[,bash]
+----
+KEY=value
+----
+
+Lines starting with `#` are treated as comments and ignored by the MCP server.
+
+=== Generate commands
+
+Generate commands should:
+
+* Write to stdout for informational messages
+* Write to stderr for errors
+* Exit with code 0 on success
+* Exit with non-zero code on failure
+
+The MCP server parses stdout to extract:
+
+* File counts (for example, "Generated 342 properties")
+* File paths created
+* Success/failure status
+
+== Error handling contracts
+
+=== Missing required parameters
+
+Commands must exit with non-zero status when required parameters are missing.
+
+Example:
+
+[,bash]
+----
+$ npx doc-tools generate property-docs
+Error: Required flag --tag is missing
+$ echo $?
+1
+----
+
+=== Invalid flags
+
+Commands must exit with non-zero status when invalid flags are provided.
+
+Example:
+
+[,bash]
+----
+$ npx doc-tools generate property-docs --invalid-flag-xyz
+Error: Unknown flag: --invalid-flag-xyz
+$ echo $?
+1
+----
+
+=== Nonexistent commands
+
+The CLI must exit with non-zero status when nonexistent commands are called.
+
+Example:
+
+[,bash]
+----
+$ npx doc-tools generate nonexistent-command
+Error: Unknown command: nonexistent-command
+$ echo $?
+1
+----
+
+=== Network errors
+
+Network errors (for example, GitHub API failures) are acceptable for version commands, but:
+
+* Must write error message to stderr
+* Must exit with non-zero status
+* Error message should indicate the network issue
+
+== Version compatibility
+
+The CLI must support the `--version` flag to output the current version.
+
+Format: `<major>.<minor>.<patch>`
+
+This allows the MCP server to verify compatibility and provide helpful error messages if the CLI version is incompatible.
+
+== Stability guarantees
+
+The MCP server depends on these CLI contracts remaining stable:
+
+*Command names and subcommands* must not change without a major version bump.
+
+*Required flags* must not be removed or renamed without a major version bump.
+
+*Output formats* for version commands must remain parseable.
+
+*Exit codes* must follow Unix conventions (0 = success, non-zero = failure).
+
+*Optional flags* may be added without breaking the MCP server.
+
+*New subcommands* may be added without breaking the MCP server.
+
+== Testing
+
+The `cli-contract.test.js` test suite verifies these contracts automatically. All tests must pass before releasing a new version of doc-tools that could affect the MCP server.
+
+Test categories:
+
+* Command structure - Verifies commands and subcommands exist
+* Flag support - Verifies required and optional flags are present
+* Output format - Verifies output can be parsed correctly
+* Error handling - Verifies proper exit codes and error messages
+* Version compatibility - Verifies version information is available
+
+== Breaking changes
+
+If a breaking change to the CLI is necessary:
+
+. Update the CLI with the breaking change
+. Increment the major version in package.json
+. Update the MCP server to handle both old and new interfaces (if possible)
+. Update the CLI contract tests to verify the new interface
+. Update this document with the new contract