Text from Type description subheadings dropped.

[guineveresaenger]

See pulumi/pulumi-aws#4921 as a typical presentation of this issue.

I've copied the summary of what is happening in docsgen from a comment there here:

The reason this information is missing is most likely due to the fact that this NOTE is not attached to the rule documentation text, but rather to the subheading where rule's nested types are explained.
Here's where we're getting the Description for rule:

But the NOTE is actually further down, in the subheading for rule:

I believe this is less of a function of NOTE (although there is some opinionated behavior around NOTEs in the bridge) and more a function of the source of the information not being associated correctly. We never parse top-level text from nested block headings into the type Description.

See also: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_function#vpc_config vs https://www.pulumi.com/registry/packages/aws/api-docs/lambda/function/#functionvpcconfig - you notice additionally that in the TF docs many of the the configuration block headers have nice intro paragraphs, none of which show up in the Pulumi docs. I believe that has the same cause.

To fix this for all such occasions, we should either:

• refactor the parseArgReferenceSection to walk a markdown doc tree instead of parse line-by line, which should make the docsPath robust enough that if we discover descriptions for the same sub-type in two different locations in the document, we can append to the same docsPath type description.
• find a way to add section-level text to a subheading (this would be more feasible/reasonable if we use the PlainDocsParser approach).