@redpanda-data/docs-extensions-and-macros 4.11.1 → 4.12.0

package/tools/property-extractor/requirements.txt

@@ -2,3 +2,4 @@ tree_sitter==0.21.1
 setuptools>=42.0.0
 pyyaml>=6.0
 requests>=2.32.5
+pytest>=7.0.0

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

@@ -0,0 +1,161 @@
+{{#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}}
+{{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}}
+
+ifndef::env-cloud[]
+*Restored during xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]:* {{#if (ne gets_restored false)}}Yes{{else}}No{{/if}}
+endif::[]
+{{#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}}
+{{#with (allTopicsConditional related_topics) as |sectionType|}}
+
+{{#if (eq sectionType "cloud")}}
+ifdef::env-cloud[]
+*Related topics:*
+
+{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+endif::[]
+{{else if (eq sectionType "self-managed")}}
+ifndef::env-cloud[]
+*Related topics:*
+
+{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+endif::[]
+{{else}}
+*Related topics:*
+
+{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+{{#if (eq type "cloud")}}
+ifdef::env-cloud[]
+* {{{value}}}
+endif::[]
+{{else if (eq type "self-managed")}}
+ifndef::env-cloud[]
+* {{{value}}}
+endif::[]
+{{else}}
+* {{{value}}}
+{{/if}}
+{{/with}}
+{{/each}}
+{{/if}}
+{{/with}}
+{{/if}}
+{{#if aliases}}
+
+// tag::self-managed-only[]
+*Aliases:* {{join aliases ", "}}
+// end::self-managed-only[]
+{{/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.hbs

@@ -7,6 +7,9 @@
 {{#if is_deprecated}}
 // tag::deprecated[]
 {{/if}}
+{{#if is_experimental_property}}
+// tag::experimental[]
+{{/if}}
 {{#if cloud_supported}}
 // tag::redpanda-cloud[]
 {{/if}}
@@ -28,7 +31,26 @@ No description available.
 {{#if is_enterprise}}
 
 ifndef::env-cloud[]
-*Enterprise license required*: `{{enterprise_value}}` (for license details, see xref:get-started:licensing/index.adoc[Redpanda Licensing])
+.Enterprise license required
+[NOTE]
+====
+{{#if enterprise_constructor}}
+{{#if (eq enterprise_constructor "simple")}}
+This property requires an Enterprise license to use.
+{{else if (eq enterprise_constructor "restricted_only")}}
+The following values require an Enterprise license: {{#each enterprise_restricted_value}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
+{{else if (eq enterprise_constructor "restricted_with_sanctioned")}}
+*License-based defaults:*
+
+* *Community:* {{#each enterprise_sanctioned_value}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}} (if no Enterprise license is present)
+* *Enterprise:* {{#each enterprise_restricted_value}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}} (if an Enterprise license is present)
+{{/if}}
+{{else}}
+Enterprise license required: `{{enterprise_value}}`
+{{/if}}
+
+For license details, see xref:get-started:licensing/index.adoc[Redpanda Licensing].
+====
 endif::[]
 {{/if}}
 {{#if cloud_byoc_only}}
@@ -38,115 +60,148 @@ NOTE: This property is available only in Redpanda Cloud BYOC deployments.
 endif::[]
 
 {{/if}}
-{{#if units}}
 
-*Unit:* {{units}}
+[cols="1e,2a"]
+|===
+| Property | Value
+
+| Type
+| `{{type}}`{{#if (or enum items.enum)}} (enum){{/if}}
+
+{{#if enum}}
+| Accepted values
+| {{#each enum}}`{{this}}`{{#if (isEnterpriseEnum this ../x-enum-metadata)}} (Enterprise){{else}}{{#if ../is_enterprise}}{{#if (includes ../enterprise_restricted_value this)}} (Enterprise){{/if}}{{/if}}{{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+{{else}}{{#if items.enum}}
+| Accepted values
+| {{#each items.enum}}`{{this}}`{{#if (isEnterpriseEnum this ../items.x-enum-metadata)}} (Enterprise){{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+{{/if}}{{/if}}
+{{#if (and minimum maximum)}}
+
+| Range
+| [`{{minimum}}`, `{{maximum}}`]
 {{else}}
-{{#if (formatUnits name)}}
+{{#if minimum}}
 
-*Unit:* {{formatUnits name}}
-{{/if}}
+| Minimum
+| `{{minimum}}`
 {{/if}}
-{{#if (ne defined_in "src/v/config/node_config.cc")}}
-{{#if (ne needs_restart undefined)}}
+{{#if maximum}}
 
-*Requires restart:* {{#if needs_restart}}Yes{{else}}No{{/if}}
+| Maximum
+| `{{maximum}}`
 {{/if}}
 {{/if}}
 
+| Default
+|{{#if is_enterprise}}{{#if enterprise_default_description}}{{{enterprise_default_description}}}{{else}}
+ifdef::env-cloud[]
+Available in the Redpanda Cloud Console
+endif::[]
 ifndef::env-cloud[]
-*Restored during xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]:* {{#if (ne gets_restored false)}}Yes{{else}}No{{/if}}
+`{{formatPropertyValue default type}}`{{#if default_human_readable}} ({{default_human_readable}}){{/if}}
+endif::[]{{/if}}{{else}}
+ifdef::env-cloud[]
+Available in the Redpanda Cloud Console
 endif::[]
-{{#if visibility}}
-
-// tag::self-managed-only[]
-*Visibility:* `{{visibility}}`
-// end::self-managed-only[]
-{{/if}}
-{{#if type}}
+ifndef::env-cloud[]
+`{{formatPropertyValue default type}}`{{#if default_human_readable}} ({{default_human_readable}}){{/if}}
+endif::[]{{/if}}
 
-*Type:* {{type}}
-{{/if}}
-{{#if (and minimum maximum)}}
+| Nullable
+| {{#if nullable}}Yes{{else}}No{{/if}}
+{{#if units}}
 
-*Accepted values:* [`{{minimum}}`, `{{maximum}}`]
+| Unit
+| {{units}}
 {{else}}
-{{#if minimum}}
+{{#if (formatUnits name)}}
 
-*Minimum value:* `{{minimum}}`
+| Unit
+| {{formatUnits name}}
 {{/if}}
-{{#if maximum}}
+{{/if}}
+{{#if (ne defined_in "src/v/config/node_config.cc")}}
+{{#if (ne needs_restart undefined)}}
 
-*Maximum value:* `{{maximum}}`
+| Requires restart
+| {{#if needs_restart}}Yes{{else}}No{{/if}}
 {{/if}}
 {{/if}}
-{{#if (ne default undefined)}}
 
-ifdef::env-cloud[]
-*Default:* Available in the Redpanda Cloud Console
-endif::[]
 ifndef::env-cloud[]
-*Default:* `{{formatPropertyValue default type}}`
+| Restored on xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]
+| {{#if (ne gets_restored false)}}Yes{{else}}No{{/if}}
 endif::[]
+{{#if visibility}}
+
+// tag::self-managed-only[]
+| Visibility
+| `{{visibility}}`
+// end::self-managed-only[]
 {{/if}}
+{{#if aliases}}
 
-*Nullable:* {{#if nullable}}Yes{{else}}No{{/if}}
+// tag::self-managed-only[]
+| Aliases
+| {{join aliases ", "}}
+// end::self-managed-only[]
+{{/if}}
 {{#if example}}
 
-{{{renderPropertyExample this}}}
+| Example
+| {{{example}}}
 {{/if}}
 {{#if related_topics}}
 {{#with (allTopicsConditional related_topics) as |sectionType|}}
 
 {{#if (eq sectionType "cloud")}}
 ifdef::env-cloud[]
-*Related topics:*
-
+| Related topics
+|
 {{#each ../related_topics}}
 {{#with (parseRelatedTopic this)}}
-* {{{value}}}
+{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
 {{/with}}
 {{/each}}
 endif::[]
 {{else if (eq sectionType "self-managed")}}
 ifndef::env-cloud[]
-*Related topics:*
-
+| Related topics
+|
 {{#each ../related_topics}}
 {{#with (parseRelatedTopic this)}}
-* {{{value}}}
+{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
 {{/with}}
 {{/each}}
 endif::[]
 {{else}}
-*Related topics:*
-
+| Related topics
+|
 {{#each ../related_topics}}
 {{#with (parseRelatedTopic this)}}
 {{#if (eq type "cloud")}}
 ifdef::env-cloud[]
-* {{{value}}}
+{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
 endif::[]
 {{else if (eq type "self-managed")}}
 ifndef::env-cloud[]
-* {{{value}}}
+{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
 endif::[]
 {{else}}
-* {{{value}}}
+{{#if (gt ../../related_topics.length 1)}}* {{/if}}{{{value}}}
 {{/if}}
 {{/with}}
 {{/each}}
 {{/if}}
 {{/with}}
 {{/if}}
-{{#if aliases}}
 
-// tag::self-managed-only[]
-*Aliases:* {{join aliases ", "}}
-// end::self-managed-only[]
-{{/if}}
+|===
 
 ---
+{{#if is_experimental_property}}
+// end::experimental[]
+{{/if}}
 {{#if cloud_supported}}
 // end::redpanda-cloud[]
 {{/if}}
@@ -158,4 +213,4 @@ endif::[]
 {{/if}}
 {{#if category}}
 // end::category-{{category}}[]
-{{/if}}
+{{/if}}

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

@@ -0,0 +1,148 @@
+{{#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}}
+
+*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 only available in Redpanda Cloud BYOC deployments.
+endif::[]
+{{/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}}
+
+*Nullable:* {{#if nullable}}Yes{{else}}No{{/if}}
+
+ifndef::env-cloud[]
+*Restored during xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]:* {{#if (ne gets_restored false)}}Yes{{else}}No{{/if}}
+endif::[]
+{{#if example}}
+
+{{{renderPropertyExample this}}}
+{{/if}}
+{{#if related_topics}}
+{{#with (allTopicsConditional related_topics) as |sectionType|}}
+
+{{#if (eq sectionType "cloud")}}
+ifdef::env-cloud[]
+*Related topics:*
+
+{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+endif::[]
+{{else if (eq sectionType "self-managed")}}
+ifndef::env-cloud[]
+*Related topics:*
+
+{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+* {{{value}}}
+{{/with}}
+{{/each}}
+endif::[]
+{{else}}
+*Related topics:*
+
+{{#each ../related_topics}}
+{{#with (parseRelatedTopic this)}}
+{{#if (eq type "cloud")}}
+ifdef::env-cloud[]
+* {{{value}}}
+endif::[]
+{{else if (eq type "self-managed")}}
+ifndef::env-cloud[]
+* {{{value}}}
+endif::[]
+{{else}}
+* {{{value}}}
+{{/if}}
+{{/with}}
+{{/each}}
+{{/if}}
+{{/with}}
+{{/if}}
+{{#if aliases}}
+
+// tag::self-managed-only[]
+*Aliases:* {{join aliases ", "}}
+// end::self-managed-only[]
+{{/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}}