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.

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

Enums lack a list of members and their descriptions #3724

Closed
Tracked by #3906
jkodroff opened this issue Jan 4, 2024 · 0 comments · Fixed by pulumi/pulumi#15415
Closed
Tracked by #3906

Enums lack a list of members and their descriptions #3724

jkodroff opened this issue Jan 4, 2024 · 0 comments · Fixed by pulumi/pulumi#15415
Assignees
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. kind/bug Some behavior is incorrect or out of spec resolution/fixed This issue was fixed
Milestone

Comments

@jkodroff
Copy link
Member

jkodroff commented Jan 4, 2024

What happened?

In the registry, enums have no information:

image

Despite the fact that the schema does have information on these types:

 "aws-native:s3:BucketAccessControl": {
            "description": "A canned access control list (ACL) that grants predefined permissions to the bucket.",
            "type": "string",
            "enum": [
                {
                    "name": "AuthenticatedRead",
                    "value": "AuthenticatedRead"
                },
                {
                    "name": "AwsExecRead",
                    "value": "AwsExecRead"
                },
                {
                    "name": "BucketOwnerFullControl",
                    "value": "BucketOwnerFullControl"
                },
                {
                    "name": "BucketOwnerRead",
                    "value": "BucketOwnerRead"
                },
                {
                    "name": "LogDeliveryWrite",
                    "value": "LogDeliveryWrite"
                },
                {
                    "name": "Private",
                    "value": "Private"
                },
                {
                    "name": "PublicRead",
                    "value": "PublicRead"
                },
                {
                    "name": "PublicReadWrite",
                    "value": "PublicReadWrite"
                }
            ]
        },

This is consistent for both native and bridged providers. Example: https://www.pulumi.com/registry/packages/aws/api-docs/ec2/instance/#instancetype

There should be an obvious visible indicator that a supporting type is an enum. At the very least, we should call it out in text.

Example

n/a

Output of pulumi about

n/a

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).

@jkodroff jkodroff added kind/bug Some behavior is incorrect or out of spec needs-triage Needs attention from the triage team labels Jan 4, 2024
@github-project-automation github-project-automation bot moved this to 🤔 Triage in Docs 📚 Jan 4, 2024
@toriancrane toriancrane added area/docs Hand-written documentation. For api docs, see area/api-docs. and removed kind/bug Some behavior is incorrect or out of spec labels Jan 5, 2024
@toriancrane toriancrane moved this from 🤔 Triage to 🎬 Ready in Docs 📚 Jan 5, 2024
@toriancrane toriancrane added kind/bug Some behavior is incorrect or out of spec and removed needs-triage Needs attention from the triage team labels Jan 5, 2024
@toriancrane toriancrane self-assigned this Jan 5, 2024
@sean1588 sean1588 self-assigned this Feb 8, 2024
@sean1588 sean1588 added this to the 0.100 milestone Feb 8, 2024
github-merge-queue bot pushed a commit to pulumi/pulumi that referenced this issue Feb 12, 2024
Fixes: pulumi/registry#3724
Fixes: pulumi/registry#2966

This PR is to resolve the enum rendering issue. The enums were not being
rendered on the page at all due to a misconfigured language choosable
(i.e. `<pulumi-choosable>`) that wraps the enum section. I found out
this had to do with the lang property being set as `nodejs` when instead
the choosable expects `javascript` or `typescript` as the valid values.
I then followed the pattern of what we seem to be doing for the other
pulumi-choosables which have this issue, which is to have an if
statement that sets it to `javascript,typescript` if `nodejs` is given.

This is how the rendering looks now. I have not adjusted any layouts of
the template or anything along those lines, only fixed the choosable. I
am wondering if this is actually what was intended for these, as we have
a display name in the left column that is ~useless IMO and the right
column has the value. I am assuming this was done to match the
formatting of the other nested types that are displayed since these
enums are treated as such. Though I don't think it is optimal for what
we are trying to present given that we do not have descriptions for any
of the individual enum values and what they represent.

Should we consider doing something like having a separate enum section
that is more purpose built for the data we can display where we just
have the enum type in the left column, followed by the valid enum values
in the right column. For example:

| Instance Type | a1.2xlarge, a1.4xlarge , a1.large.... |


Should we consider moving to something like this or continue following
the current pattern we have? Thoughts welcome!

Also, we can consider shipping this as it is as it is still an
improvement over what we have now and file a follow up issue to
re-assess the way this is presented.

This is the current render that this PR fix will produce:

<img width="795" alt="Screen Shot 2024-02-09 at 8 35 21 AM"
src="https://github.com/pulumi/pulumi/assets/16751381/352462b7-720c-4495-bdfe-f62cfdd946c0">
@pulumi-bot pulumi-bot added the resolution/fixed This issue was fixed label Feb 12, 2024
@github-project-automation github-project-automation bot moved this from 🎬 Ready to 🏁 Done in Docs 📚 Feb 12, 2024
@interurban interurban added the area/api-docs Generated API docs, generated from providers. For hand-written docs, see area/docs. label Feb 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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. kind/bug Some behavior is incorrect or out of spec resolution/fixed This issue was fixed
Projects
Archived in project
Development

Successfully merging a pull request may close this issue.

5 participants