Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Lambda Function API example missing langchooser and out of place #3498

Closed
joeduffy opened this issue Nov 11, 2023 · 2 comments
Closed

Lambda Function API example missing langchooser and out of place #3498

joeduffy opened this issue Nov 11, 2023 · 2 comments
Assignees
@interurban
Labels
area/api-docs Generated API docs, generated from providers. For hand-written docs, see area/docs. area/docs Hand-written documentation. For api docs, see area/api-docs. impact/first-48 This bug is likely to be hit during a user's first 48 hours of product evaluation kind/bug Some behavior is incorrect or out of spec resolution/duplicate This issue is a duplicate of another issue

Comments

@joeduffy
Copy link
Member

I am 50% certain this bug is already filed elsewhere but I can't find it.

If you go to this section https://www.pulumi.com/registry/packages/aws/api-docs/lambda/function/#cloudwatch-logging-and-permissions, you will see that the first "example" is 1) not underneath the Example Usage section and 2) lacks a language chooser, so that all language examples are just stacked atop one another.

I believe the root cause ultimately comes down to the source Markdown using a peer H2 for that section, alongside Example Usage, even though that H2 comes after the Example Usage one.

The result is ultimately that registrygen code-gens the wrong thing via this template. More precisely, it code-gens the right thing in that this is how everything is wired up, but I don't think that's what we want to do. The odd thing is that we did recognize and convert the code samples, it's just the way all of this docsgen gunk works is that it only recognizes a subset of those examples.

It does make me wonder ... are we just fundamentally swimming upstream with this approach? Should we instead simply preserve all H2s, in order, except for the highly structured sections like Argument and Attribute References, and preserve those in the front matter in their entirety, along with lang-choosers for every code example we encounter in the Markdown translation?
@joeduffy joeduffy added kind/bug Some behavior is incorrect or out of spec area/api-docs Generated API docs, generated from providers. For hand-written docs, see area/docs. area/docs Hand-written documentation. For api docs, see area/api-docs. impact/first-48 This bug is likely to be hit during a user's first 48 hours of product evaluation labels Nov 11, 2023
@github-actions github-actions bot added the needs-triage Needs attention from the triage team label Nov 11, 2023
@github-project-automation github-project-automation bot moved this to 🤔 Triage in Docs 📚 Nov 11, 2023
@toriancrane
Copy link
Contributor

I think you are referring to this one.

@toriancrane toriancrane added resolution/duplicate This issue is a duplicate of another issue and removed needs-triage Needs attention from the triage team labels Nov 11, 2023
@toriancrane toriancrane moved this from 🤔 Triage to 🧳 Backlog in Docs 📚 Nov 11, 2023
@joeduffy
Copy link
Member Author

Thanks Torian, that's the one, and the broader epic too.

@github-project-automation github-project-automation bot moved this from 🧳 Backlog to 🏁 Done in Docs 📚 Nov 11, 2023
@guineveresaenger guineveresaenger mentioned this issue Feb 9, 2024
Closed
@guineveresaenger guineveresaenger mentioned this issue Feb 21, 2024
Merged
iwahbe added a commit to pulumi/pulumi-terraform-bridge that referenced this issue Mar 7, 2024
@guineveresaenger @iwahbe
Emit <!--Start PulumiCodeChooser --> instead of {{% examples %}} (#…
cf13280 
…1689)

**IMPORTANT** This cannot be merged until the bridge has updated
pulumi/pulumi to a version that includes [these
changes](pulumi/pulumi@26bdac7).

After that, merging will be safe.


**Note**: pulumi/pulumi#15475 needs to be merged
first for these changes to be safe.

This PR aims to remove the nested "Example Usage" logic from the bridge,
[as discussed here](pulumi/registry#3498).

The issue this is aimed at fixing is
pulumi/pulumi-aws#2624 but there should be a
myriad of other issues that will be addressed by this change.

In a nutshell, this PR removes any `{{% example(s) }}` injection from
the `Description` fields of a resource and instead detects any and all
code conversions from TF/HCL --> pulumi languages, and surrounds them
with an HTML comment.
This is currently 
```
const (
	startPulumiCodeChooser = "<!--Start PulumiCodeChooser -->"
	endPulumiCodeChooser   = "<!--End PulumiCodeChooser -->"
)
```

Marking up any converted code blocks using the new format will serve
_only_ as a marker for registry docsgen to surround this converted code
with a language chooser.

I refrained from going full Markdown parser because I believe it would
be an even larger rewrite. Instead, we detect code fences in the
docstring input, and append text and converted code section to the
output, with the following caveats:

- If a code block is part of a Section (i.e. has a Markdown header), if
we encounter errors in code conversion, the new functionality strips the
entire section automatically. Non-headered code blocks with such an
error will also continue to be stripped.
- Using indices rather than line splitting allows us to get rid of the
awkward `<break>` placeholders for the Import section.
- The Import section no longer needs special handling in
`convertExamplesInner`: it is valid code and will be retained as such
- With a little bit of extra parsing of the code fence syntax
highlighter, we can capture a few more cases of perfectly valid json or
yaml that we have elided previously as "failure to convert from TF".
- With the removal of examples, titles (which never actually made it
into the schema) are now obsolete. We will refer to resource paths when
logging conversion failures. We have done so all along when there was no
`exampleTitle`, and this change affects only the wording of logging
output.
- The `isFrontMatter` variable was removed as well. To the best of my
knowledge, Hugo front matter does not get piped through the bridge, and
is generated by the registry instead.
- Handwritten docs continue to bypass `convertExamplesInner`, with an
added caveat that both third party and our own docs may add the old
example shortcodes. This change will allow us to [remove some of
these](https://github.com/pulumi/pulumi-aws/blob/master/docs/resource/aws_acm_certificate_validation.examples.md).
Registry docsgen will continue to support the shortcode way of doing
things, since native providers conform to that expectation separately.

---------

Co-authored-by: Ian Wahbe <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@interurban interurban

Labels
area/api-docs Generated API docs, generated from providers. For hand-written docs, see area/docs. area/docs Hand-written documentation. For api docs, see area/api-docs. impact/first-48 This bug is likely to be hit during a user's first 48 hours of product evaluation kind/bug Some behavior is incorrect or out of spec resolution/duplicate This issue is a duplicate of another issue
Projects
Docs 📚
Archived in project
Milestone
No milestone
Development

No branches or pull requests
3 participants
@interurban @joeduffy @toriancrane