Improve Examples / Docs for the ConfigFile.Transformations input

[RobbieMcKinstry]

What happened?

While triaging a user-issue, I discovered the documentation/examples on using the Transformations input on the ConfigFile resource is lacking. In TypeScript, the resource is typed as any[]. Since this is untyped, it's unclear how each element is typed.

The From Kubernetes docs page does a little bit better of a job explaining, but it's not as discoverable. It provides this example code:

guestbook, err := yaml.NewConfigFile(ctx, "guestbook", &yaml.ConfigFileArgs{
    File: "guestbook-all-in-one.yaml",
    Transformations: []yaml.Transformation{func(state map[string]interface{}, opts ...pulumi.ResourceOption) {
    // ...
    }
})

This helps because it shows each element of the Transformations array is a callback function with two args. The key question I had when looking at the docs was what exactly am I given as arguments? In particular, the state argument is foggy to me: are the values in the map Resources or do they occupy the enum (map[string]{}interface | string)? A well-typed example in TypeScript would go a long way. Users shouldn't need to navigate to the Go example to understand the typing relation, in general.

After looking at the Go example, I figured it out, but it took a hot sec. 👍🏻

Steps to reproduce

1. Visit the registry docs for ConfigFile and look at the inputs.
2. Observe there are no examples for Transformations.
3. Try to ascertain the shape of the parameters from just the docs.

Expected Behavior

I probably would have expected an example + a type signature more specific than []any

Actual Behavior

Observed []any.

Output of pulumi about

No response

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]

Hi Robbie -

thank you for pointing out this missing area and detailed improvement suggestions. ❤️ I'll forward it to the correct folks - hope you don't mind it re-classed as an enhancement.

[guineveresaenger]

Additional note: https://github.com/pulumi/pulumi-kubernetes/tree/master/provider/pkg/gen/examples is the place to add examples. 🎉