Python documentation does not properly reference encapsulation classes for L1 constructs

It appears that the classes used to encapsulate properties for layer one constructs do not show up properly in the documentation. Digging into the generated code, JSII is creating the encapsulation classes as subclasses of the layer one constructs and using forward references for typing, which is causing the documentation to show something along the lines of Union[List[Union[ForwardRef, IResolveable]], IResolvable] rather than Union[List[Union[CfnNotificationRule.TargetProperty, IResolvable]], IResolvable].

Ex1 (for CfnNotificationRule.targets):

Python: https://docs.aws.amazon.com/cdk/api/latest/python/aws_cdk.aws_codestarnotifications/CfnNotificationRule.html

API: https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-codestarnotifications.CfnNotificationRule.html

Ex2 (for CfnDeliveryStream.elasticsearch_destination_configuration, CfnDeliveryStream.extended_s3_destination_configuration, CfnDeliveryStream.kinesis_stream_source_configuration, CfnDeliveryStream.redshift_destination_configuration, CfnDeliveryStream.s3_destination_configuration , CfnDeliveryStream.splunk_destination_configuration):

Python: https://docs.aws.amazon.com/cdk/api/latest/python/aws_cdk.aws_kinesisfirehose/CfnDeliveryStream.html

API: https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-kinesisfirehose.CfnDeliveryStream.html

Oddly enough, the *Props class for the layer one constructs has the correct name for the encapsulation class. However, it still does not link to the documentation for that class.

Ex (for CfnNotificationRuleProps): https://docs.aws.amazon.com/cdk/api/latest/python/aws_cdk.aws_codestarnotifications/CfnNotificationRuleProps.html

Further, the documentation for these subclasses doesn’t appear to be generated at all and I had to dig into the generated code to find information about them.

---

This is a 📕 documentation issue

[ghost]

I’ve recently added a section on using Cfn constructs to the Constructs topic in the Dev Guide.

https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_l1_using

I’d be interested in feedback (here, at the Guide repo, by clicking the feedback link on docs.aws.amazon.com…)

[github-actions[bot]]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see. If you need more assistance, please either tag a team member or open a new issue that references this one. If you wish to keep having a conversation with other community members under this issue feel free to do so.