Bridge does not support all valid Markdown list formats

[VenelinMartinov]

What happened?

For pulumi/pulumi-pagerduty#477 we noticed that we were picking up the wrong input description for a page with multiple inputs called "type".

After #1882 all the input descriptions have the output "type" description instead.

We've also lost a bunch of valid descriptions: https://www.pulumi.com/registry/packages/pagerduty/api-docs/service/#inputs - this is mostly empty.

Example

Upgrade diff: https://github.com/pulumi/pulumi-pagerduty/pull/476/files#diff-802c5dcd29dd2017fa41e8ba4cf0ede0e40d0176433bb47721c7cd87d812f10b

Output of pulumi about

.

Additional context

No response

Contributing

Vote on this issue by adding a 👍 reaction.
To contribute a fix for this issue, leave a comment (and link to your pull request, if you've opened one already).

[guineveresaenger]

I seem to remember that picking up output types is currently a fallback behavior when docs cannot otherwise be found. We may want to revisit that design.

As for the pagerduty issue, there's two things we should look into

1. there's a bug in top-level argument reference detection --> fix here in bridge
2. because the nested block subsections in this resource have a lot of chitchat, they are not discovered properly.
   --> provider-level fix: we can try to add a docsEditRule
   --> bridge fix: adjust the regex

[guineveresaenger]

Next data point:

Unlike all other providers, this particular provider adds spurious indents to its Argument Reference

From pagerduty.Service:

## Argument Reference

The following arguments are supported:

  * `name` - (Required) The name of the service.
  * `description` - (Optional) A human-friendly description of the service.

Compare to aws.AccountRegion:

## Argument Reference

This resource supports the following arguments:

* `enabled` - (Required) Whether the region is enabled.
* `region_name` - (Required) The region name to manage.

We rely on indents to discover nested docs paths.

Additionally the resource description cited in the original issue has...verbose titles for the nested blocks which we don't discover in the bridge.

[guineveresaenger]

So, the real fix for this issue is to make the abovementioned list indent, which is legal in GitHub flavored Markdown, be correctly handled by docs parsing.

Falling back on output descriptions is a current necessary reality in larger providers such as AWS, where Inputs/Outputs overlap quite frequently but often only one is documented, so that part works as expected - the bug is that the fallback condition should never have gotten triggered for Pagerduty.