search

pulumi / docs

All things Pulumi docs!
https://pulumi.com
Apache License 2.0
127 stars 222 forks source link

Indicate actual input types #7127

Open danielrbradley opened 2 years ago

danielrbradley commented 2 years ago

Problem description

When looking up input types it looks in the documentation it is confusing that they don't have the indicate which are pulumi.Input<T> vs raw T types.

For example these two input args:

image

are defined in the Typescript SDK as:

    data?: pulumi.Input<{[key: string]: pulumi.Input<string>}>;

    immutable?: pulumi.Input<boolean>;

Therefore the missing information in the docs is that both properties can come from another output, however, the key within the data record cannot be an output.

Suggestions for a fix

We could add a language specific type definition for each property somewhere e.g. below the simple definition or in the description, which changes based on the user's preferred language. This could also be hidden until revealed if it makes things too messy?

Property Description
data

{[key: string]: string}

Typescript: data?: pulumi.Input<{[key: string]: pulumi.Input<string>}>;		 Data contains the data.

Alternatively we could expose the whole args type definition in a language switcher with the current table display as the default. For example the headings could be:

Description Typescript Python Go C#
susanev commented 2 years ago

@danielrbradley is this a dup of https://github.com/pulumi/registry/issues/603? or are these distinct?

danielrbradley commented 2 years ago

No, this is different - rather than the token for the resource type - this is showing the actual types for args (what's passed into a resource) that will be rendered in a specific language's SDK.

This might however be better suited for the registry repo as (I guess) that's where it's implemented?

lukehoban commented 2 years ago

This is different from https://github.com/pulumi/registry/issues/603.

Note that I’m not certain we have to fix this via making the Input aspect explicit on every property. I could imagine a few other fixes:

  1. Make prompt inputs explicit (they are much more rare, so less noisy to do this)
  2. Find a way to annotate the plain or not aspect as a bit, possibly via a glyph, and have the glyph have hover text that provides more details.
  3. Include a note at the top of the table that links to docs on Inputs.
  4. etc.

We might want to be as explicit as the original suggestion here, but throwing out some other options in case that explicitness ends up being too noisy (which was the reason we intentionally didn’t do this originally - and the only reason we really now have to do this is that there exist “plain” inputs that didn’t exist before).

lukehoban commented 2 years ago

This might however be better suited for the registry repo as (I guess) that's where it's implemented?

The implementation is actually in https://github.com/pulumi/pulumi/tree/master/pkg/codegen/docs.

mikhailshilkov commented 2 years ago

Who owns the triage of docs? This issue is in "needs-triage" for a week now.

cnunciato commented 2 years ago

Agree this can be confusing. I'd probably suggest we start by seeing how noisy it'd be to have the types be explicit, since that'd probably be the most clear, and then explore alternatives if that doesn't work out.

If anyone's up for taking this on, I'd appreciate it -- otherwise, I can put it on the Content board (I'm generally triaging all website-related issues, but didn't triage this one as there was conversation happening on it), but I do have a few things queued up at the moment that'll make it hard to get to it for a little bit.