Opt-in property references through the prop macro - #668
Draft
JakeSCahill wants to merge 2 commits into
Draft
Conversation
Registers the prop macro (docs-extensions-and-macros >= 5.7.0) with property-validate: warn and converts plain-backtick cluster property mentions in prose to prop macro calls, validated against the published redpanda-properties JSON. Marked properties get hover tooltips and, with link=true, links that resolve within this component's own property pages (the macro discovers which cloud page documents each property, borrowing the streaming docs only for properties cloud does not publish).
❌ Deploy Preview for rp-cloud failed. Why did it fail? →
|
Contributor
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Four prop: conversions marked identifiers that share a name with a Redpanda property but are not that property in context, so the tooltip would have described something unrelated: - create-redpanda-catalog.adoc: sasl_mechanism is a CREATE REDPANDA CATALOG option. The property of that name is a broker setting for the HTTP Proxy client's connection to the Kafka API. - terraform-provider.adoc (x2): cluster_id is a Terraform resource argument set from data.redpanda_cluster.byoc.id, not the read-only cluster_id cluster property. - vpc-byo-aws.adoc: cloud_storage_bucket is a BYOVPC resource name in a list with management_bucket and dynamodb_table, not a property being set. - create-mmaker-source-connector.adoc: replication.factor is the MirrorMaker connector config key, listed beside replication.policy.class and offset-syncs.topic.replication.factor. In each case the sibling identifiers were correctly left as plain code, so marking only these read as inconsistent as well as wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
In plain English
Same change as the docs-repo migration (redpanda-data/docs#1896), for the cloud docs: property mentions in prose are explicitly marked with the
prop:macro and build-verified against the published property data, instead of the UI guessing based on text matching (which gave wrong tooltips to ordinary words likeadminthat are also property names). On cloud pages, marked properties link to cloud's own property reference pages — the macro discovers which cloud page documents each property and only borrows the streaming docs for properties cloud doesn't publish.Contents
propmacro registered in the local playbook withproperty-validate: warn.admin,brokers,rack,retries,superusers) deliberately left plain.config_refcalls existed in this repo, so nothing to migrate there.Full explainer:
macros/PROPERTY_AND_ENTERPRISE_REFERENCES.adocin docs-extensions-and-macros#254.