Accurate property and resource references in descriptions #16099
Labels
area/codegen
SDK-gen, program-gen, convert
area/docs
Improvements or additions to documentation
impact/quality
kind/enhancement
Improvements or new features
Hello!
Issue details
Description fields can make reference to property names or other resources. These can be named differently in different language's SDKs.
Currently, terraform bridge re-generated the schema for each language so that the SDKs will have accurate references. However, the registry still has the names specific to only one language.
We need a way to include these language-specific fields in description fields so we can have accurate documentation without having to render different schemas for each language.
Original terraform-bridge issue:
Impact
Possible Design
One possible design that could let each language implement their own inflectors would be to annotate properties which are likely to be language specific so they can be identified within the description field and updated where required.
Inserting a
<span>
tag around replacable elements would provide a backward compatible approach as spans with no classes should have no visible impact if left in the code.Attributes would then be used within the span to indicate additional information about the type of replacement to perform e.g.
data-pulumi-naming="resource:[TOKEN]"
ordata-pulumi-naming="property:[PROP_PATH]"
Examples
Note: the registry description for VPC doesn't vary by language
Note: the registry description for the Firewall Action property doesn't vary by language
Fallback
These span tags with data attributes should have no impact in the online documentation if left in, but should also be able to be replaced correctly when rendering the docs - which they currently are not.
For SDKs inline documentation, if a
<span>
tag is encountered, it should just be removed if it fails to be replaced with an SDK specific name.Affected area/feature
The text was updated successfully, but these errors were encountered: