Display error with API Documentation for the AWS Lambda Function Resource

[toriancrane]

When accessing the AWS Lambda Function resource page, there is a section called "CloudWatch Logging and Permissions" near the top of the page that I believe should be nested under the "Example Usage" section.

It is the first item on the right hand navigation menu.

It also seems to be missing the the language selector/tabbing functionality.

[thomas11]

Thank you for reporting this, @toriancrane. I agree it doesn't look quite right. I've asked some folks internally and will report back.

[thomas11]

Likely part of pulumi/pulumi-terraform-bridge#1291. The examples are not detected correctly, which is also why the language chooser is missing.

[guineveresaenger]

Summary of Internal Discussion:

• we should likely take a more straightforward approach and take upstream docs in the order they appear, providing language choosers for every code snippet. Joe also had some comments in this issue.
• this means streamlining some of the "Example Usage" logic that is scattered across the bridge and the docsgen templates.

Findings so far:

Our assumptions for upstream docs are too specialized and do not match reality.

• we assume code snippets only exist in an "Example Usage" section
  • in fact we hard code an expectation that an "Example Usage" section exists with that name which is potentially brittle
  • additionally if a subsection of "Example Usage" does not have code in it, we get odd behavior
• we assume if there are more examples that they are prefixed with an H3 markdown header
• we base ordering, docsgen, metrics, and display logic on the above assumption

---

I spent some time hunting down how an "examples section" is achieved in the Terraform Bridge). The hope was that by expanding the {{%% examples %%}} shortcode in the bridge, either by wrapping all of the resource's docs in the shortcode, or wrapping each example individually, to include H2 headings we could achieve code wrappers for everything. Unfortunately, this is not possible, as docsgen creates a <pulumi-examples> div using duplicate logic based on the presence of a ## Example Usage header. Additionally, it turns out we have code snippets in the Supporting Types descriptions as well which behave much like the CloudWatch snippet in Lambda and should be included in a fix as well.

The bridge code that translates examples is the same code finds and translates all code snippets, but only marks H3 sections as an "example" via {{%% examples %%}} and {{%% example %%}} short code, resulting in the missing chooser. This also incidentally colors the translation metrics, as code that isn't in any "Example Usage" section counts towards example conversion metrics.

Next, I'll look into the logic surrounding this template - due to some duplicate logic we'll have to clean this up in parallel with the bridge.

The templating logic seems also responsible for some of the mismatching of example code to titles, and odd ordering of headers (the bridge order looks consistent across resources) when upstream does not match our expectations.

Unfortunately, it also appears that there is registry code that relies on an examples section so we may need some cleanup.

Suggestions

Long-term
The ultimate goal here, I think, should be to remove the special templating behavior for "Example Usage" and re-write templates and logic to wrap all code found in an individual language chooser. This would result in a display that closely follows upstream presentation and order. This would be a change noticeable mostly in our biggest providers (aws, gcp, kubernetes) as many smaller provider don't have nested examples in this way.

1. Remove/rewrite Example Usage templating behavior; implement a smaller, flexible wrapper template for all code snippets, keep upstream ordering. Possible to keep the div but base it purely on header order.
2. Clean up bridge code to remove shortcodes and simplify the nested docs logic by flattening each H2 and H3 section
3. Clean up registry code that relies on having an Examples section if necessary.

Immediate
For this particular issue on the lambda docs page, we have a potential quick fix: we can patch the upstream docs so that the "CloudWatch Logging" section can be interpreted as part of the Examples section. We don't know if having this section be an example is the original upstream intent, so this fix is not ideal. But since this is such a frequently-visited page, I would recommend we do this today, while leaving this issue open and continue to implement the more long-term and general fix.