@redpanda-data/docs-extensions-and-macros 4.10.2 → 4.10.4

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

@@ -0,0 +1,7 @@
+module.exports = function anchorName(name) {
+  const anchor = String(name).replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+  if (!anchor) {
+    throw new Error(`Invalid property name for anchor generation: "${name}"`);
+  }
+  return anchor;
+};

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

@@ -10,4 +10,5 @@ module.exports = {
   formatPropertyValue: require('./formatPropertyValue.js'),
   renderPropertyExample: require('./renderPropertyExample.js'),
   formatUnits: require('./formatUnits.js'),
+  anchorName: require('./anchorName.js'),
 };

package/tools/property-extractor/property_extractor.py

@@ -719,6 +719,14 @@ def _apply_override_to_existing_property(property_dict, override, overrides_file
         else:
             logger.warning(f"related_topics for property must be an array")
 
+    # Apply exclude_from_docs override
+    if "exclude_from_docs" in override:
+        property_dict["exclude_from_docs"] = override["exclude_from_docs"]
+
+    # Apply category override for topic properties
+    if "category" in override:
+        property_dict["category"] = override["category"]
+
 
 def _create_property_from_override(prop_name, override, overrides_file_path):
     """Create a new property from override specification."""
@@ -757,6 +765,14 @@ def _create_property_from_override(prop_name, override, overrides_file_path):
                        "example", "example_file", "example_yaml", "related_topics", 
                        "is_deprecated", "visibility"]:
             new_property[key] = value
+
+    # Add exclude_from_docs if specified
+    if "exclude_from_docs" in override:
+        new_property["exclude_from_docs"] = override["exclude_from_docs"]
+
+    # Add category if specified
+    if "category" in override:
+        new_property["category"] = override["category"]
     
     return new_property
 
@@ -877,15 +893,18 @@ def add_config_scope(properties):
         if prop.get("is_topic_property", False):
             prop["config_scope"] = "topic"
         else:
-            # For override-created properties, preserve existing config_scope if set
-            if prop.get("defined_in") == "override" and prop.get("config_scope") is not None:
-                # Keep the existing config_scope from override
+            # Skip config_scope assignment if it's already been set by an override
+            if prop.get("config_scope") is not None:
+                # Keep the existing config_scope from override or previous assignment
                 pass
             else:
                 defined_in = prop.get("defined_in", "")
                 if defined_in == "src/v/config/configuration.cc":
                     prop["config_scope"] = "cluster"
-                elif defined_in == "src/v/config/node_config.cc":
+                elif defined_in in ["src/v/config/node_config.cc", 
+                                    "src/v/pandaproxy/rest/configuration.cc",
+                                    "src/v/kafka/client/configuration.cc", 
+                                    "src/v/pandaproxy/schema_registry/configuration.cc"]:
                     prop["config_scope"] = "broker"
                 else:
                     prop["config_scope"] = None
@@ -1644,7 +1663,50 @@ def extract_topic_properties(source_path):
             # Skip no-op properties
             if prop_data.get("is_noop", False):
                 continue
-                
+
+            # Assign category based on property name pattern or mapping
+            def infer_category(name):
+                retention = [
+                    "cleanup.policy", "compaction.strategy", "delete.retention.ms", "max.compaction.lag.ms",
+                    "min.cleanable.dirty.ratio", "min.compaction.lag.ms", "retention.bytes", "retention.ms"
+                ]
+                segment = [
+                    "compression.type", "max.message.bytes", "message.timestamp.type", "segment.bytes", "segment.ms"
+                ]
+                performance = [
+                    "flush.bytes", "flush.ms", "redpanda.leaders.preference", "replication.factor", "write.caching"
+                ]
+                tiered = [
+                    "initial.retention.local.target.bytes", "initial.retention.local.target.ms", "redpanda.remote.delete",
+                    "redpanda.remote.read", "redpanda.remote.recovery", "redpanda.remote.write", "retention.local.target.bytes",
+                    "retention.local.target.ms"
+                ]
+                remote_replica = ["redpanda.remote.readreplica"]
+                iceberg = [
+                    "redpanda.iceberg.delete", "redpanda.iceberg.invalid.record.action", "redpanda.iceberg.mode",
+                    "redpanda.iceberg.partition.spec", "redpanda.iceberg.target.lag.ms"
+                ]
+                schema_registry = [
+                    "redpanda.key.schema.id.validation", "redpanda.key.subject.name.strategy", "redpanda.value.schema.id.validation",
+                    "redpanda.value.subject.name.strategy", "confluent.key.schema.validation", "confluent.key.subject.name.strategy",
+                    "confluent.value.schema.validation", "confluent.value.subject.name.strategy"
+                ]
+                if name in retention:
+                    return "retention-compaction"
+                if name in segment:
+                    return "segment-message"
+                if name in performance:
+                    return "performance-cluster"
+                if name in tiered:
+                    return "tiered-storage"
+                if name in remote_replica:
+                    return "remote-read-replica"
+                if name in iceberg:
+                    return "iceberg-integration"
+                if name in schema_registry:
+                    return "schema-registry"
+                return "other"
+
             converted_properties[prop_name] = {
                 "name": prop_name,
                 "description": prop_data.get("description", ""),
@@ -1654,7 +1716,8 @@ def extract_topic_properties(source_path):
                 "corresponding_cluster_property": prop_data.get("corresponding_cluster_property", ""),
                 "acceptable_values": prop_data.get("acceptable_values", ""),
                 "is_deprecated": False,
-                "is_topic_property": True
+                "is_topic_property": True,
+                "category": infer_category(prop_name)
             }
             
         logging.info(f"Extracted {len(converted_properties)} topic properties (excluding {len([p for p in topic_properties.values() if p.get('is_noop', False)])} no-op properties)")

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

@@ -1,7 +1 @@
-=== `{{name}}`
-
-{{#if description}}
-{{{description}}}
-{{else}}
-No description available.
-{{/if}}
+- `{{name}}`

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

@@ -1,62 +1,88 @@
+{{#if category}}
+// tag::category-{{category}}[]
+{{/if}}
+{{#if exclude_from_docs}}
+// tag::exclude-from-docs[]
+{{/if}}
+{{#if is_deprecated}}
+// tag::deprecated[]
+{{/if}}
+{{#if cloud_supported}}
+// tag::redpanda-cloud[]
+{{/if}}
 === {{name}}
-
 {{#if version}}
+
+ifndef::env-cloud[]
 *Introduced in {{version}}*
+endif::[]
 {{/if}}
-
 {{#if description}}
+
 {{{description}}}
 {{else}}
+
 No description available.
 {{/if}}
-
 {{#if is_enterprise}}
+
 ifndef::env-cloud[]
 *Enterprise license required*: `{{enterprise_value}}` (for license details, see xref:get-started:licensing/index.adoc[Redpanda Licensing])
 endif::[]
-
 {{/if}}
-
+{{#if cloud_byoc_only}}
+ifdef::env-cloud[]
+NOTE: This property is available only in Redpanda Cloud BYOC deployments.
+endif::[]
+{{/if}}
 {{#if units}}
-*Unit:* {{units}}
 
+*Unit:* {{units}}
 {{else}}
 {{#if (formatUnits name)}}
-*Unit:* {{formatUnits name}}
 
+*Unit:* {{formatUnits name}}
 {{/if}}
 {{/if}}
 {{#if (ne defined_in "src/v/config/node_config.cc")}}
 {{#if (ne needs_restart undefined)}}
-*Requires restart:* {{#if needs_restart}}Yes{{else}}No{{/if}}
 
+*Requires restart:* {{#if needs_restart}}Yes{{else}}No{{/if}}
 {{/if}}
 {{/if}}
 {{#if visibility}}
-*Visibility:* `{{visibility}}`
 
+// tag::self-managed-only[]
+*Visibility:* `{{visibility}}`
+// end::self-managed-only[]
 {{/if}}
 {{#if type}}
-*Type:* {{type}}
 
+*Type:* {{type}}
 {{/if}}
 {{#if (and minimum maximum)}}
-*Accepted values:* [`{{minimum}}`, `{{maximum}}`]
 
+*Accepted values:* [`{{minimum}}`, `{{maximum}}`]
 {{else}}
 {{#if minimum}}
-*Minimum value:* `{{minimum}}`
 
+*Minimum value:* `{{minimum}}`
 {{/if}}
 {{#if maximum}}
-*Maximum value:* `{{maximum}}`
 
+*Maximum value:* `{{maximum}}`
 {{/if}}
 {{/if}}
 {{#if (ne default undefined)}}
-*Default:* `{{formatPropertyValue default type}}`
 
+ifdef::env-cloud[]
+*Default:* Available in the Redpanda Cloud Console
+endif::[]
+ifndef::env-cloud[]
+*Default:* `{{formatPropertyValue default type}}`
+endif::[]
 {{/if}}
+
 *Nullable:* {{#if nullable}}Yes{{else}}No{{/if}}
 {{#if example}}
 
@@ -72,13 +98,21 @@ endif::[]
 {{/if}}
 {{#if aliases}}
 
+// tag::self-managed-only[]
 *Aliases:* {{join aliases ", "}}
+// end::self-managed-only[]
 {{/if}}
-{{#if is_deprecated}}
 
-[WARNING]
-====
-This property is deprecated.
-====
-{{/if}}
 ---
+{{#if cloud_supported}}
+// end::redpanda-cloud[]
+{{/if}}
+{{#if is_deprecated}}
+// end::deprecated[]
+{{/if}}
+{{#if exclude_from_docs}}
+// end::exclude-from-docs[]
+{{/if}}
+{{#if category}}
+// end::category-{{category}}[]
+{{/if}}

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

@@ -0,0 +1,13 @@
+[cols="1a,1a"]
+|===
+| Topic property | Corresponding cluster property
+
+{{#each topicProperties}}
+| <<{{anchorName name}},`{{name}}`>>
+| xref:./cluster-properties.adoc#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`]
+{{/each}}
+|===
+
+{{!-- Helper to generate anchor names --}}
+{{!-- Usage: anchorName propertyName --}}
+{{!-- Example: cleanup.policy -> cleanuppolicy --}}

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

@@ -1,3 +1,15 @@
+{{#if category}}
+// tag::category-{{category}}[]
+{{/if}}
+{{#if exclude_from_docs}}
+// tag::exclude-from-docs[]
+{{/if}}
+{{#if is_deprecated}}
+// tag::deprecated[]
+{{/if}}
+{{#if cloud_supported}}
+// tag::redpanda-cloud[]
+{{/if}}
 === {{name}}
 {{#if version}}
 
@@ -16,6 +28,11 @@ ifndef::env-cloud[]
 *Enterprise license required*: `{{enterprise_value}}` (for license details, see xref:get-started:licensing/index.adoc[Redpanda Licensing])
 endif::[]
 {{/if}}
+{{#if cloud_byoc_only}}
+ifdef::env-cloud[]
+NOTE: This property is only available in Redpanda Cloud BYOC deployments.
+endif::[]
+{{/if}}
 {{#if type}}
 
 *Type:* {{type}}
@@ -42,9 +59,19 @@ endif::[]
 {{/if}}
 {{/if}}
 {{#if (ne default undefined)}}
+{{#if cloud_supported}}
+
+ifdef::env-cloud[]
+*Default:* Available in the Redpanda Cloud Console
+endif::[]
+ifndef::env-cloud[]
+*Default:* `{{formatPropertyValue default type}}`
+endif::[]
+{{else}}
 
 *Default:* `{{formatPropertyValue default type}}`
 {{/if}}
+{{/if}}
 
 *Nullable:* {{#if nullable}}Yes{{else}}No{{/if}}
 {{#if example}}
@@ -61,13 +88,21 @@ endif::[]
 {{/if}}
 {{#if aliases}}
 
+// tag::self-managed-only[]
 *Aliases:* {{join aliases ", "}}
+// end::self-managed-only[]
 {{/if}}
-{{#if is_deprecated}}
 
-[WARNING]
-====
-This property is deprecated.
-====
-{{/if}}
 ---
+{{#if cloud_supported}}
+// end::redpanda-cloud[]
+{{/if}}
+{{#if is_deprecated}}
+// end::deprecated[]
+{{/if}}
+{{#if exclude_from_docs}}
+// end::exclude-from-docs[]
+{{/if}}
+{{#if category}}
+// end::category-{{category}}[]
+{{/if}}

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

@@ -1,104 +0,0 @@
-{{#if cloud_supported}}
-// tag::redpanda-cloud[]
-{{/if}}
-=== {{name}}
-{{#if version}}
-
-*Introduced in {{version}}*
-{{/if}}
-{{#if description}}
-
-{{{description}}}
-{{else}}
-
-No description available.
-{{/if}}
-{{#if is_enterprise}}
-
-ifndef::env-cloud[]
-*Enterprise license required*: `{{enterprise_value}}` (for license details, see xref:get-started:licensing/index.adoc[Redpanda Licensing])
-endif::[]
-{{/if}}
-{{#if cloud_byoc_only}}
-ifdef::env-cloud[]
-NOTE: This property is available only in Redpanda Cloud BYOC deployments.
-endif::[]
-{{/if}}
-{{#if units}}
-
-*Unit:* {{units}}
-{{else}}
-{{#if (formatUnits name)}}
-
-*Unit:* {{formatUnits name}}
-{{/if}}
-{{/if}}
-{{#if (ne defined_in "src/v/config/node_config.cc")}}
-{{#if (ne needs_restart undefined)}}
-
-*Requires restart:* {{#if needs_restart}}Yes{{else}}No{{/if}}
-{{/if}}
-{{/if}}
-{{#if visibility}}
-
-// tag::self-managed-only[]
-*Visibility:* `{{visibility}}`
-// end::self-managed-only[]
-{{/if}}
-{{#if type}}
-
-*Type:* {{type}}
-{{/if}}
-{{#if (and minimum maximum)}}
-
-*Accepted values:* [`{{minimum}}`, `{{maximum}}`]
-{{else}}
-{{#if minimum}}
-
-*Minimum value:* `{{minimum}}`
-{{/if}}
-{{#if maximum}}
-
-*Maximum value:* `{{maximum}}`
-{{/if}}
-{{/if}}
-{{#if (ne default undefined)}}
-
-ifdef::env-cloud[]
-*Default:* Available in the Redpanda Cloud Console
-endif::[]
-ifndef::env-cloud[]
-*Default:* `{{formatPropertyValue default type}}`
-endif::[]
-{{/if}}
-
-*Nullable:* {{#if nullable}}Yes{{else}}No{{/if}}
-{{#if example}}
-
-{{{renderPropertyExample this}}}
-{{/if}}
-{{#if related_topics}}
-
-*Related topics:*
-
-{{#each related_topics}}
-* {{{this}}}
-{{/each}}
-{{/if}}
-{{#if aliases}}
-
-// tag::self-managed-only[]
-*Aliases:* {{join aliases ", "}}
-// end::self-managed-only[]
-{{/if}}
-{{#if is_deprecated}}
-
-[WARNING]
-====
-This property is deprecated.
-====
-{{/if}}
----
-{{#if cloud_supported}}
-// end::redpanda-cloud[]
-{{/if}}

package/tools/property-extractor/templates/property-page-with-includes.hbs

@@ -1,17 +0,0 @@
-= {{pageTitle}}
-{{#if pageAliases}}
-:page-aliases: {{join pageAliases ", "}}
-{{/if}}
-:description: {{description}}
-
-{{{intro}}}
-
-{{#if sectionTitle}}
-== {{sectionTitle}}
-{{/if}}
-
-{{#if sectionIntro}}
-{{{sectionIntro}}}
-{{/if}}
-
-include::reference:partial$properties/{{filename}}.adoc[]

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

@@ -1,22 +0,0 @@
-= {{pageTitle}}
-{{#if pageAliases}}
-:page-aliases: {{join pageAliases ", "}}
-{{/if}}
-:description: {{description}}
-
-{{{intro}}}
-
-{{#if sectionTitle}}
-== {{sectionTitle}}
-{{/if}}
-
-{{#if sectionIntro}}
-{{{sectionIntro}}}
-{{/if}}
-
-{{#each groups}}
-{{#each this.properties}}
-{{> (lookup ../this "template")}}
-
-{{/each}}
-{{/each}}

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

@@ -1,97 +0,0 @@
-{{#if cloud_supported}}
-// tag::redpanda-cloud[]
-{{/if}}
-=== {{name}}
-{{#if version}}
-
-*Introduced in {{version}}*
-{{/if}}
-{{#if description}}
-
-{{{description}}}
-{{else}}
-
-No description available.
-{{/if}}
-{{#if is_enterprise}}
-
-ifndef::env-cloud[]
-*Enterprise license required*: `{{enterprise_value}}` (for license details, see xref:get-started:licensing/index.adoc[Redpanda Licensing])
-endif::[]
-{{/if}}
-{{#if cloud_byoc_only}}
-
-NOTE: This property is only available in Redpanda Cloud BYOC deployments.
-{{/if}}
-{{#if type}}
-
-*Type:* {{type}}
-{{/if}}
-{{#if acceptable_values}}
-
-*Accepted values:* {{{acceptable_values}}}
-{{/if}}
-{{#if corresponding_cluster_property}}
-
-*Related cluster property:* xref:reference:cluster-properties.adoc#{{corresponding_cluster_property}}[{{corresponding_cluster_property}}]
-{{/if}}
-{{#if (and minimum maximum)}}
-
-*Accepted values:* [`{{minimum}}`, `{{maximum}}`]
-{{else}}
-{{#if minimum}}
-
-*Minimum value:* `{{minimum}}`
-{{/if}}
-{{#if maximum}}
-
-*Maximum value:* `{{maximum}}`
-{{/if}}
-{{/if}}
-{{#if (ne default undefined)}}
-{{#if cloud_supported}}
-
-ifdef::env-cloud[]
-*Default:* Available in the Redpanda Cloud Console
-endif::[]
-ifndef::env-cloud[]
-*Default:* `{{formatPropertyValue default type}}`
-endif::[]
-{{else}}
-
-*Default:* `{{formatPropertyValue default type}}`
-{{/if}}
-{{/if}}
-
-// tag::self-managed-only[]
-*Nullable:* {{#if nullable}}Yes{{else}}No{{/if}}
-// end::self-managed-only[]
-{{#if example}}
-
-{{{renderPropertyExample this}}}
-{{/if}}
-{{#if related_topics}}
-
-*Related topics:*
-
-{{#each related_topics}}
-* {{{this}}}
-{{/each}}
-{{/if}}
-{{#if aliases}}
-
-// tag::self-managed-only[]
-*Aliases:* {{join aliases ", "}}
-// end::self-managed-only[]
-{{/if}}
-{{#if is_deprecated}}
-
-[WARNING]
-====
-This property is deprecated.
-====
-{{/if}}
----
-{{#if cloud_supported}}
-// end::redpanda-cloud[]
-{{/if}}