Accurate property and resource references in descriptions

[danielrbradley]

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

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:

• Revisit schema inflectors  pulumi-terraform-bridge#1918

Bridged providers currently keep rebuilding the schema for every target language. That is pulumi-tfgen-azure python --out sdk/python/ will regenerate the schema from scratch, including converting examples, when pulumi-tfgen-azure schema --out provider/cmd/pulumi-resource-azure has already done the work of generating schema.json.

The reason for this is that schema rendering and doc comment rendering are DIFFERENT and not byte-for-byte the same. The differences boil down to inflecting code references:

-        Please refer to VpcSubnet to manage the subnets under a Linode VPC.
+        Please refer to linode.VpcSubnet to manage the subnets under a Linode VPC.

-	// Controls whether traffic is accepted or dropped by this rule (`ACCEPT`, `DROP`). Overrides the Firewall’s inboundPolicy if this is an inbound rule, or the outboundPolicy if this is an outbound rule.
+	// Controls whether traffic is accepted or dropped by this rule (`ACCEPT`, `DROP`). Overrides the Firewall’s inbound_policy if this is an inbound rule, or the outbound_policy if this is an outbound rule.

Impact

1. Significantly reduce our provider build times (only render docs once instead of 6 times)
2. Move local SDK generation closer to a reality (as we could avoid having to use tfgen)
3. Improve our docs by including accurate language-specific names
4. Remove tfgen's dependency on each language's codegen

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]" or data-pulumi-naming="property:[PROP_PATH]"

Examples

Note: the registry description for VPC doesn't vary by language

-        Please refer to VpcSubnet to manage the subnets under a Linode VPC.
+        Please refer to <span data-pulumi-naming="resource:linode:index/vpcSubnet:VpcSubnet">VpcSubnet</span> to manage the subnets under a Linode VPC.

Note: the registry description for the Firewall Action property doesn't vary by language

-	// Overrides the Firewall’s inboundPolicy if this is an inbound rule, or the outboundPolicy if this is an outbound rule.
+	// Overrides the Firewall’s <span data-pulumi-naming="property:inboundPolicy">inboundPolicy</span> if this is an inbound rule, or the <span data-pulumi-naming="property:outboundPolicy">outboundPolicy</span> if this is an outbound rule.

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

• Codegen
• Registrygen

[t0yv0]

Nit: build times won't be affected as much since example generation is cached. Otherwise would be quite beneficial.