@redpanda-data/docs-extensions-and-macros 4.12.5 → 4.13.0

package/tools/property-extractor/transformers.py

@@ -23,7 +23,7 @@ INPUT FORMAT (from parser):
 - info["declaration"]: Full C++ type declaration
 - info["params"]: List of parsed constructor parameters
 - info["name_in_file"]: C++ variable name
-- info["type"]: Property template type (e.g., "property", "enterprise_property")
+- info["type"]: Property template type (for example, "property", "enterprise_property")
 
 OUTPUT FORMAT (PropertyBag):
 - Complete JSON schema-compatible property definition
@@ -511,7 +511,7 @@ def get_meta_value(info, key, default=None):
     
     Args:
         info (dict): Property info dictionary to search for metadata
-        key (str): Metadata key to extract (e.g., "needs_restart", "visibility")
+        key (str): Metadata key to extract (for example, "needs_restart", "visibility")
         default (any): Default value if key not found or metadata missing
         
     Returns:
@@ -1254,7 +1254,7 @@ class TypeTransformer:
             
             Parameters:
                 text (str): The string to search for the template.
-                template_name (str): The template name (e.g., "std::vector" or "property").
+                template_name (str): The template name (for example, "std::vector" or "property").
             
             Returns:
                 str or None: The substring inside the outermost angle brackets for the matched template (excluding the brackets),
@@ -2068,7 +2068,7 @@ class EnterpriseTransformer:
         if len(val) >= 2 and val[0] == '"' and val[-1] == '"':
             val = val[1:-1]
         # Strip C++ namespace qualifiers from enum values
-        # e.g., model::partition_autobalancing_mode::continuous → continuous
+        # for example, model::partition_autobalancing_mode::continuous → continuous
         if '::' in val:
             val = val.split('::')[-1]
         return val
@@ -2286,7 +2286,7 @@ class ValidatorEnumExtractor:
     Analyzes validator functions to extract enum constraints for array-typed properties.
     For example, if sasl_mechanisms uses validate_sasl_mechanisms, this transformer:
     1. Finds the validator function in validators.cc
-    2. Identifies the constraint array (e.g., supported_sasl_mechanisms)
+    2. Identifies the constraint array (for example, supported_sasl_mechanisms)
     3. Resolves that array to get the actual enum values
     4. Adds them to property['items']['enum']
 
@@ -2294,7 +2294,7 @@ class ValidatorEnumExtractor:
     1. Detects array properties (type="array") with validator parameters
     2. Extracts validator function name from params
     3. Parses validator to find constraint array
-    4. Resolves array to get enum values (e.g., ["SCRAM", "GSSAPI", "OAUTHBEARER", "PLAIN"])
+    4. Resolves array to get enum values (for example, ["SCRAM", "GSSAPI", "OAUTHBEARER", "PLAIN"])
     5. Sets property['items']['enum'] with the discovered values
 
     DOWNSTREAM USAGE:
@@ -2408,7 +2408,7 @@ class RuntimeValidationEnumExtractor:
     PROCESSING:
     1. Detects string properties (not arrays) without validator parameters
     2. Searches the source file for validation functions that reference the property
-    3. Parses comparison patterns (e.g., property != constant1 && property != constant2)
+    3. Parses comparison patterns (for example, property != constant1 && property != constant2)
     4. Resolves constants to actual string values
     5. Sets property['enum'] with discovered values
 

package/tools/property-extractor/type_definition_extractor.py

@@ -281,7 +281,7 @@ class TypeDefinitionExtractor:
                 if cc_path.exists():
                     files_to_search.append(cc_path)
 
-                # Also look for parent directory's main .cc file (e.g., model/model.cc)
+                # Also look for parent directory's main .cc file (for example, model/model.cc)
                 parent_dir = file_path.parent
                 parent_cc = parent_dir / f"{parent_dir.name}.cc"
                 if parent_cc.exists() and parent_cc != cc_path:
@@ -364,7 +364,7 @@ class TypeDefinitionExtractor:
         Resolve a C++ type alias to a JSON schema type.
 
         Args:
-            alias_type (str): The C++ type expression (e.g., "named_type<int32_t, ...>")
+            alias_type (str): The C++ type expression (for example, "named_type<int32_t, ...>")
 
         Returns:
             str: JSON schema type (integer, string, etc.) or None if unknown
@@ -525,7 +525,7 @@ class TypeDefinitionExtractor:
                     # Convert C++ type to JSON schema type
                     json_type = self._cpp_type_to_json_type(return_type)
 
-                    # Use method name as field name (e.g., host() becomes "host")
+                    # Use method name as field name (for example, host() becomes "host")
                     properties[method_name] = {"type": json_type}
                     continue
 
@@ -555,7 +555,7 @@ class TypeDefinitionExtractor:
             position (int): Position in the file
 
         Returns:
-            str: Namespace (e.g., "model" or "config::tls")
+            str: Namespace (for example, "model" or "config::tls")
         """
         # Look backwards from position to find namespace declaration
         preceding = content[:position]

package/tools/redpanda-connect/README.adoc

@@ -525,7 +525,7 @@ Overrides support:
 
 * *Manual override maintenance*: Custom descriptions must be maintained in overrides.json
 * *Example quality*: Auto-generated examples may not represent best practices
-* *Duplicate YAML keys*: Some examples contain multiple configurations in one block, creating invalid YAML with duplicate top-level keys (e.g., multiple `processors:` keys)
+* *Duplicate YAML keys*: Some examples contain multiple configurations in one block, creating invalid YAML with duplicate top-level keys (for example, multiple `processors:` keys)
 * *CSV catalog dependency*: Relies on manually maintained CSV in Connect repository
 * *Version detection timing*: Must be called during Antora build to access component attributes
 

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

@@ -195,7 +195,7 @@ function resolveReferences(obj, root) {
  *
  * @param {Object} options - Configuration options for documentation generation.
  * @param {string} options.data - Path to the connector data file (JSON or YAML).
- * @param {string} [options.overrides] - Optional path to a JSON file with override data. Supports $ref references in JSON Pointer format (e.g., "#/definitions/client_certs").
+ * @param {string} [options.overrides] - Optional path to a JSON file with override data. Supports $ref references in JSON Pointer format (for example, "#/definitions/client_certs").
  * @param {string} options.template - Path to the main Handlebars template.
  * @param {string} [options.templateIntro] - Path to the intro partial template (used in full draft mode).
  * @param {string} [options.templateFields] - Path to the fields partial template.
@@ -253,7 +253,7 @@ async function generateRpcnConnectorDocs(options) {
   markBeta(dataObj);
 
   // Apply overrides if provided
-  if (overrides) {
+  if (overrides && fs.existsSync(overrides)) {
     const ovRaw = fs.readFileSync(overrides, 'utf8');
     const ovObj = JSON.parse(ovRaw);
     // Resolve any $ref references in the overrides
@@ -281,9 +281,11 @@ async function generateRpcnConnectorDocs(options) {
         }
       }
     }
+  } else if (overrides) {
+    console.log(`Overrides file not found: ${overrides} (skipping)`);
   }
 
-  // Compile the “main” template (used when writeFullDrafts = true)
+  // 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”