pulumi/pkg/codegen/docs/gen.go

2616 lines
81 KiB
Go
Raw Permalink Normal View History

Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
//go:generate go run bundler.go
// Copyright 2016-2020, Pulumi Corporation.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Pulling out some of the repeated strings tokens into constants would harm readability, so we just ignore the
// goconst linter's warning.
//
sdk/go: Remove 'nolint' directives from package docs Go treats comments that match the following regex as directives. //[a-z0-9]+:[a-z0-9] Comments that are directives don't show in an entity's documentation. https://github.com/golang/go/commit/5a550b695117f07a4f2454039a4871250cd3ed09#diff-f56160fd9fcea272966a8a1d692ad9f49206fdd8dbcbfe384865a98cd9bc2749R165 Our code has `//nolint` directives that now show in the API Reference. This is because these directives are in one of the following forms, which don't get this special treatment. // nolint:foo //nolint: foo This change fixes all such directives found by the regex: `// nolint|//nolint: `. See bottom of commit for command used for the fix. Verification: Here's the output of `go doc` on some entities before and after this change. Before ``` % go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8 package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi" nolint: lll, interfacer nolint: lll, interfacer const EnvOrganization = "PULUMI_ORGANIZATION" ... var ErrPlugins = errors.New("pulumi: plugins requested") ``` After ``` % go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8 package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi" const EnvOrganization = "PULUMI_ORGANIZATION" ... var ErrPlugins = errors.New("pulumi: plugins requested") func BoolRef(v bool) *bool func Float64Ref(v float64) *float64 func IntRef(v int) *int func IsSecret(o Output) bool ``` Before ``` % go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_ package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi" func URN_(o string) ResourceOption URN_ is an optional URN of a previously-registered resource of this type to read from the engine. nolint: revive ``` After: ``` % go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_ package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi" func URN_(o string) ResourceOption URN_ is an optional URN of a previously-registered resource of this type to read from the engine. ``` Note that golangci-lint offers a 'nolintlint' linter that finds such miuses of nolint, but it also finds other issues so I've deferred that to a follow up PR. Resolves #11785 Related: https://github.com/golangci/golangci-lint/issues/892 [git-generate] FILES=$(mktemp) rg -l '// nolint|//nolint: ' | tee "$FILES" | xargs perl -p -i -e ' s|// nolint|//nolint|g; s|//nolint: |//nolint:|g; ' rg '.go$' < "$FILES" | xargs gofmt -w -s
2023-01-06 00:07:45 +00:00
//nolint:lll, goconst
package docs
import (
"bytes"
"embed"
"errors"
"fmt"
"go/format"
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
"html"
"html/template"
"path"
"sort"
"strings"
"github.com/hashicorp/hcl/v2"
"github.com/pulumi/pulumi/pkg/v3/codegen/pcl"
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
"github.com/golang/glog"
2022-04-29 22:04:15 +00:00
"github.com/pgavlin/goldmark"
2022-04-21 11:23:36 +00:00
"github.com/pulumi/pulumi-java/pkg/codegen/java"
yaml "github.com/pulumi/pulumi-yaml/pkg/pulumiyaml/codegen"
"github.com/pulumi/pulumi/pkg/v3/codegen"
"github.com/pulumi/pulumi/pkg/v3/codegen/dotnet"
go_gen "github.com/pulumi/pulumi/pkg/v3/codegen/go"
"github.com/pulumi/pulumi/pkg/v3/codegen/nodejs"
"github.com/pulumi/pulumi/pkg/v3/codegen/python"
"github.com/pulumi/pulumi/pkg/v3/codegen/schema"
"github.com/pulumi/pulumi/sdk/v3/go/common/slice"
Fix docs generator parent module computation (#15035) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Fixes #14820 Fixes #14821 Fixes a bug in docs generator parent module computation that used to lead to duplicate files panics and undesirable documentation URL layout for affected providers such as [pulumi/fortios](https://github.com/pulumiverse/pulumi-fortios/issues). Joint work with @tmeckel . ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [ ] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. --> --------- Co-authored-by: Thomas Meckel <tmeckel@users.noreply.github.com>
2024-02-20 15:44:37 +00:00
"github.com/pulumi/pulumi/sdk/v3/go/common/tokens"
2022-12-12 14:55:35 +00:00
"github.com/pulumi/pulumi/sdk/v3/go/common/util/contract"
)
//go:embed templates/*.tmpl
var packagedTemplates embed.FS
// NOTE: This lookup map can be removed when all Pulumi-managed packages
// have a DisplayName in their schema. See pulumi/pulumi#7813.
// This lookup table no longer needs to be updated for new providers
// and is considered stale.
//
// titleLookup is a map of package name to the desired display name.
func titleLookup(shortName string) (string, bool) {
v, ok := map[string]string{
"aiven": "Aiven",
"akamai": "Akamai",
"alicloud": "Alibaba Cloud",
"auth0": "Auth0",
"aws": "AWS Classic",
"awsx": "AWSx (Pulumi Crosswalk for AWS)",
"aws-apigateway": "AWS API Gateway",
"aws-miniflux": "Miniflux",
"aws-native": "AWS Native",
"aws-quickstart-aurora-mysql": "AWS QuickStart Aurora MySQL",
"aws-quickstart-aurora-postgres": "AWS QuickStart Aurora PostgreSQL",
"aws-quickstart-redshift": "AWS QuickStart Redshift",
"aws-serverless": "AWS Serverless",
"aws-quickstart-vpc": "AWS QuickStart VPC",
"aws-s3-replicated-bucket": "AWS S3 Replicated Bucket",
"azure": "Azure Classic",
"azure-justrun": "Azure Justrun",
"azure-native": "Azure Native",
"azure-quickstart-acr-geo-replication": "Azure QuickStart ACR Geo Replication",
"azure-quickstart-aks": "Azure QuickStart AKS",
"azure-quickstart-compute": "Azure QuickStart Compute",
"azure-quickstart-sql": "Azure QuickStart SQL",
"azuread": "Azure Active Directory (Azure AD)",
"azuredevops": "Azure DevOps",
"azuresel": "Azure",
"civo": "Civo",
"cloudamqp": "CloudAMQP",
"cloudflare": "Cloudflare",
"cloudinit": "cloud-init",
2023-01-05 02:13:41 +00:00
"confluentcloud": "Confluent Cloud",
"confluent": "Confluent Cloud (Deprecated)",
"consul": "HashiCorp Consul",
"coredns-helm": "CoreDNS (Helm)",
"datadog": "Datadog",
"digitalocean": "DigitalOcean",
"dnsimple": "DNSimple",
"docker": "Docker",
"docker-buildkit": "Docker BuildKit",
"eks": "Amazon EKS",
"equinix-metal": "Equinix Metal",
"f5bigip": "f5 BIG-IP",
"fastly": "Fastly",
"gcp": "Google Cloud (GCP) Classic",
"gcp-global-cloudrun": "Google Global Cloud Run",
"gcp-project-scaffold": "Google Project Scaffolding",
"google-native": "Google Cloud Native",
"github": "GitHub",
"github-serverless-webhook": "GitHub Serverless Webhook",
"gitlab": "GitLab",
"hcloud": "Hetzner Cloud",
"istio-helm": "Istio (Helm)",
"jaeger-helm": "Jaeger (Helm)",
"kafka": "Kafka",
"keycloak": "Keycloak",
"kong": "Kong",
"kubernetes": "Kubernetes",
"libvirt": "libvirt",
"linode": "Linode",
"mailgun": "Mailgun",
"minio": "MinIO",
"mongodbatlas": "MongoDB Atlas",
"mysql": "MySQL",
"newrelic": "New Relic",
"kubernetes-ingress-nginx": "NGINX Ingress Controller (Helm)",
"kubernetes-coredns": "CoreDNS (Helm)",
"kubernetes-cert-manager": "Jetstack Cert Manager (Helm)",
"nomad": "HashiCorp Nomad",
"ns1": "NS1",
"okta": "Okta",
"openstack": "OpenStack",
"opsgenie": "Opsgenie",
"packet": "Packet",
"pagerduty": "PagerDuty",
"pulumi-std": "Pulumi Standard Library",
"postgresql": "PostgreSQL",
"prometheus-helm": "Prometheus (Helm)",
"rabbitmq": "RabbitMQ",
"rancher2": "Rancher2",
"random": "random",
"rke": "Rancher Kubernetes Engine (RKE)",
"run-my-darn-container": "Run My Darn Container",
"shipa": "Shipa",
"signalfx": "SignalFx",
"snowflake": "Snowflake",
"splunk": "Splunk",
"spotinst": "Spotinst",
"sumologic": "Sumo Logic",
"tls": "TLS",
"vault": "Vault",
"venafi": "Venafi",
"vsphere": "vSphere",
"wavefront": "Wavefront",
"yandex": "Yandex",
}[shortName]
return v, ok
}
// Property anchor tag separator, used in a property anchor tag id to separate the
// property and language (e.g. property~lang).
const propertyLangSeparator = "_"
type languageConstructorSyntax struct {
resources map[string]string
invokes map[string]string
}
type constructorSyntaxData struct {
typescript *languageConstructorSyntax
python *languageConstructorSyntax
golang *languageConstructorSyntax
csharp *languageConstructorSyntax
java *languageConstructorSyntax
yaml *languageConstructorSyntax
}
func emptyLanguageConstructorSyntax() *languageConstructorSyntax {
return &languageConstructorSyntax{
resources: map[string]string{},
invokes: map[string]string{},
}
}
func newConstructorSyntaxData() *constructorSyntaxData {
return &constructorSyntaxData{
typescript: emptyLanguageConstructorSyntax(),
python: emptyLanguageConstructorSyntax(),
golang: emptyLanguageConstructorSyntax(),
csharp: emptyLanguageConstructorSyntax(),
java: emptyLanguageConstructorSyntax(),
yaml: emptyLanguageConstructorSyntax(),
}
}
type docGenContext struct {
internalModMap map[string]*modContext
supportedLanguages []string
snippetLanguages []string
templates *template.Template
docHelpers map[string]codegen.DocLanguageHelper
// The language-specific info objects for a certain package (provider).
goPkgInfo go_gen.GoPackageInfo
csharpPkgInfo dotnet.CSharpPackageInfo
nodePkgInfo nodejs.NodePackageInfo
pythonPkgInfo python.PackageInfo
// langModuleNameLookup is a map of module name to its language-specific
// name.
langModuleNameLookup map[string]string
// Maps a *modContext, *schema.Resource, or *schema.Function to the link that was assigned to it.
moduleConflictLinkMap map[interface{}]string
constructorSyntaxData *constructorSyntaxData
}
// modules is a map of a module name and information
// about it. This is crux of all API docs generation
// as the modContext carries information about the resources,
// functions, as well other modules within each module.
func (dctx *docGenContext) modules() map[string]*modContext {
return dctx.internalModMap
}
func (dctx *docGenContext) setModules(modules map[string]*modContext) {
m := map[string]*modContext{}
for k, v := range modules {
m[k] = v.withDocGenContext(dctx)
}
dctx.internalModMap = m
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
func newDocGenContext() *docGenContext {
2022-04-21 11:23:36 +00:00
supportedLanguages := []string{"csharp", "go", "nodejs", "python", "yaml", "java"}
docHelpers := make(map[string]codegen.DocLanguageHelper)
for _, lang := range supportedLanguages {
switch lang {
case "csharp":
docHelpers[lang] = &dotnet.DocLanguageHelper{}
case "go":
docHelpers[lang] = &go_gen.DocLanguageHelper{}
case "nodejs":
docHelpers[lang] = &nodejs.DocLanguageHelper{}
case "python":
docHelpers[lang] = &python.DocLanguageHelper{}
2022-04-21 11:23:36 +00:00
case "yaml":
docHelpers[lang] = &yaml.DocLanguageHelper{}
case "java":
docHelpers[lang] = &java.DocLanguageHelper{}
}
}
return &docGenContext{
supportedLanguages: supportedLanguages,
snippetLanguages: []string{"csharp", "go", "python", "typescript", "yaml", "java"},
langModuleNameLookup: map[string]string{},
docHelpers: docHelpers,
moduleConflictLinkMap: map[interface{}]string{},
}
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
type typeDetails struct {
inputType bool
}
// header represents the header of each resource markdown file.
type header struct {
Title string
TitleTag string
MetaDesc string
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
// property represents an input or an output property.
type property struct {
2020-05-22 21:53:34 +00:00
// ID is the `id` attribute that will be attached to the DOM element containing the property.
ID string
// DisplayName is the property name with word-breaks.
DisplayName string
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
Name string
Comment string
Types []propertyType
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
DeprecationMessage string
2020-05-22 21:53:34 +00:00
Link string
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
IsRequired bool
IsInput bool
IsReplaceOnChanges bool
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
// enum represents an enum.
type enum struct {
ID string // ID is the `id` attribute attached to the DOM element containing the enum.
DisplayName string // DisplayName is the enum name with word-breaks.
Name string // Name is the language-specific enum name.
Value string
Comment string
DeprecationMessage string
}
// docNestedType represents a complex type.
type docNestedType struct {
Name string
Input bool
AnchorID string
Properties map[string][]property
EnumValues map[string][]enum
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
// propertyType represents the type of a property.
type propertyType struct {
DisplayName string
DescriptionName string // Name used in description list.
Name string
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// Link can be a link to an anchor tag on the same
// page, or to another page/site.
Link string
}
// paramSeparator is for data passed to the separator template.
type paramSeparator struct {
Indent string
}
// formalParam represents the formal parameters of a constructor
// or a lookup function.
type formalParam struct {
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
Name string
Type propertyType
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// This is the language specific optional type indicator.
// For example, in nodejs this is the character "?" and in Go
// it's "*".
OptionalFlag string
DefaultValue string
// Comment is an optional description of the parameter.
Comment string
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
type packageDetails struct {
DisplayName string
Repository string
RepositoryName string
License string
Notes string
Version string
}
type resourceDocArgs struct {
Header header
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
Tool string
// LangChooserLanguages is a comma-separated list of languages to pass to the
// language chooser shortcode. Use this to customize the languages shown for a
// resource. By default, the language chooser will show all languages supported
// by Pulumi for all resources.
Add ability to constrain supported languages of resource and function overlays (#16579) The existing overlays (e.g. Chart v3 in Kubernetes, or CallbackFunction in AWS) are not available in every language Pulumi supports. This often confuses users because the generated docs include all languages Pulumi supports (e.g. see https://github.com/pulumi/pulumi-kubernetes/issues/2181). To solve that problem, this change adds a new optional parameter to the schema that allows configuring the languages an overlay (resource or function) supports. To support this in docsgen the existing Language Chooser (`LangChooserLanguages`) of resources is made configurable and extended to functions. Note: This doesn't support resource methods right now. They'll need extra handling because and overlay resource method might not support all of the languages its resource supports. I'll tackle this in a follow up PR. Here's a screenshot of how this will look like for the Helm v3 chart for example: <img width="1046" alt="Screenshot 2024-07-01 at 16 11 23" src="https://github.com/pulumi/pulumi/assets/2453580/b1a1365a-6dee-4099-829a-2859639a4c8c"> The PR contains the following commits. I'd recommend to look at the first three ones and then check the regenerated golden files in the last one: - **Add schema parameter to constrain supported languages for overlays** - **Update developer docs and changelog** - **Refactor LanguageChooser and always pass supported languages** - **Regenerate testdata** relates to #13231
2024-07-09 14:54:50 +00:00
// Supported values are "typescript", "python", "go", "csharp", "java", "yaml"
LangChooserLanguages string
// CreationExampleSyntax is a map from language to the rendered HTML for the
// creation example syntax where the key is the language name and the value is
// a piece of code that shows how to create a new instance of the resource with default placeholder values.
CreationExampleSyntax map[string]string
// Comment represents the introductory resource comment.
Comment string
Add ability to constrain supported languages of resource and function overlays (#16579) The existing overlays (e.g. Chart v3 in Kubernetes, or CallbackFunction in AWS) are not available in every language Pulumi supports. This often confuses users because the generated docs include all languages Pulumi supports (e.g. see https://github.com/pulumi/pulumi-kubernetes/issues/2181). To solve that problem, this change adds a new optional parameter to the schema that allows configuring the languages an overlay (resource or function) supports. To support this in docsgen the existing Language Chooser (`LangChooserLanguages`) of resources is made configurable and extended to functions. Note: This doesn't support resource methods right now. They'll need extra handling because and overlay resource method might not support all of the languages its resource supports. I'll tackle this in a follow up PR. Here's a screenshot of how this will look like for the Helm v3 chart for example: <img width="1046" alt="Screenshot 2024-07-01 at 16 11 23" src="https://github.com/pulumi/pulumi/assets/2453580/b1a1365a-6dee-4099-829a-2859639a4c8c"> The PR contains the following commits. I'd recommend to look at the first three ones and then check the regenerated golden files in the last one: - **Add schema parameter to constrain supported languages for overlays** - **Update developer docs and changelog** - **Refactor LanguageChooser and always pass supported languages** - **Regenerate testdata** relates to #13231
2024-07-09 14:54:50 +00:00
ExamplesSection examplesSection
DeprecationMessage string
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// Import
ImportDocs string
// ConstructorParams is a map from language to the rendered HTML for the constructor's
// arguments.
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
ConstructorParams map[string]string
// ConstructorParamsTyped is the typed set of parameters for the constructor, in order.
ConstructorParamsTyped map[string][]formalParam
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// ConstructorResource is the resource that is being constructed or
// is the result of a constructor-like function.
ConstructorResource map[string]propertyType
// ArgsRequired is a flag indicating if the args param is required
// when creating a new resource.
ArgsRequired bool
// InputProperties is a map per language and a corresponding slice of
// input properties accepted as args while creating a new resource.
InputProperties map[string][]property
// OutputProperties is a map per language and a corresponding slice of
// output properties returned when a new instance of the resource is
// created.
OutputProperties map[string][]property
// LookupParams is a map of the param string to be rendered per language
// for looking-up a resource.
LookupParams map[string]string
// StateInputs is a map per language and the corresponding slice of
// state input properties required while looking-up an existing resource.
StateInputs map[string][]property
// StateParam is the type name of the state param, if any.
StateParam string
// NestedTypes is a slice of the nested types used in the input and
// output properties.
NestedTypes []docNestedType
Resource docs: emit supporting types beyond the 200 limit (#16185) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Originally motivated by uncontrolled pseudo-recurcive type expansion in AWS WafV2, we've limited the number of types that we should in the docs to 200: https://github.com/pulumi/pulumi/pull/12070 Our large customer that publishes their own packages and docs came back to us and said they have legitimate use cases with more than 200 types: #15507 I've grabbed stats about our current packages and still found a few offenders: ``` "aws:lex/v2modelsIntent:V2modelsIntent" 920 "aws:wafv2/ruleGroup:RuleGroup" 310 "aws:wafv2/webAcl:WebAcl" 523 "azure-native:datafactory:Dataset" 256 "azure-native:datafactory:LinkedService" 299 "azure-native:datafactory:Pipeline" 618 "azure-native:datamigration:ServiceTask" 291 "azure-native:datamigration:Task" 291 "aws-native:quicksight:Analysis" 589 "aws-native:quicksight:Dashboard" 606 "aws-native:quicksight:Template" 590 ``` Therefore, I'm not entirely removing the limit in this PR, but a) bumping the default to 1000 b) applying 200 to the known offenders only I don't love it's hard coded, but I haven't found a place to add simple configuration nob. Anyway, it's slightly less hard-coded than it used to be. Fixes #15507 ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [x] I have added tests that prove my fix is effective or that my feature works - Existing docs gen tests cover that I haven't broken anything - I re-generated the AWS docs and they had no changes <!--- User-facing changes require a CHANGELOG entry. --> - [x] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2024-05-13 14:58:33 +00:00
// Maximum number of nested types to show.
MaxNestedTypes int
// A list of methods associated with the resource.
Methods []methodDocArgs
PackageDetails packageDetails
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// typeUsage represents a nested type's usage.
type typeUsage struct {
Input bool
Output bool
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
// nestedTypeUsageInfo is a type-alias for a map of Pulumi type-tokens
// and whether or not the type is used as an input and/or output
// properties.
type nestedTypeUsageInfo map[string]typeUsage
func (ss nestedTypeUsageInfo) add(s string, input bool) {
if v, ok := ss[s]; ok {
if input {
v.Input = true
} else {
v.Output = true
}
ss[s] = v
return
}
ss[s] = typeUsage{
Input: input,
Output: !input,
}
}
// contains returns true if the token already exists and matches the
// input or output flag of the token.
func (ss nestedTypeUsageInfo) contains(token string, input bool) bool {
a, ok := ss[token]
if !ok {
return false
}
if input && a.Input {
return true
} else if !input && a.Output {
return true
}
return false
}
type modContext struct {
2022-12-12 14:55:35 +00:00
pkg schema.PackageReference
mod string
inputTypes []*schema.ObjectType
resources []*schema.Resource
functions []*schema.Function
typeDetails map[*schema.ObjectType]*typeDetails
children []*modContext
tool string
docGenContext *docGenContext
}
func (mod *modContext) withDocGenContext(dctx *docGenContext) *modContext {
if mod == nil {
return nil
}
all: Fix revive issues Fixes the following issues found by revive included in the latest release of golangci-lint. Full list of issues: **pkg** ``` backend/display/object_diff.go:47:10: superfluous-else: if block ends with a break statement, so drop this else and outdent its block (move short variable declaration to its own line if necessary) (revive) backend/display/object_diff.go:716:12: redefines-builtin-id: redefinition of the built-in function delete (revive) backend/display/object_diff.go:742:14: redefines-builtin-id: redefinition of the built-in function delete (revive) backend/display/object_diff.go:983:10: superfluous-else: if block ends with a continue statement, so drop this else and outdent its block (revive) backend/httpstate/backend.go:1814:4: redefines-builtin-id: redefinition of the built-in function cap (revive) backend/httpstate/backend.go:1824:5: redefines-builtin-id: redefinition of the built-in function cap (revive) backend/httpstate/client/client.go:444:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) backend/httpstate/client/client.go:455:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) cmd/pulumi/org.go:113:4: if-return: redundant if ...; err != nil check, just return error instead. (revive) cmd/pulumi/util.go:216:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) codegen/docs/gen.go:428:2: redefines-builtin-id: redefinition of the built-in function copy (revive) codegen/hcl2/model/expression.go:2151:5: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/hcl2/syntax/comments.go:151:2: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/hcl2/syntax/comments.go:329:3: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/hcl2/syntax/comments.go:381:5: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/nodejs/gen.go:1367:5: redefines-builtin-id: redefinition of the built-in function copy (revive) codegen/python/gen_program_expressions.go:136:2: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/python/gen_program_expressions.go:142:3: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/report/report.go:126:6: redefines-builtin-id: redefinition of the built-in function panic (revive) codegen/schema/docs_test.go:210:10: superfluous-else: if block ends with a continue statement, so drop this else and outdent its block (move short variable declaration to its own line if necessary) (revive) codegen/schema/schema.go:790:2: redefines-builtin-id: redefinition of the built-in type any (revive) codegen/schema/schema.go:793:4: redefines-builtin-id: redefinition of the built-in type any (revive) resource/deploy/plan.go:506:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) resource/deploy/snapshot_test.go:59:3: redefines-builtin-id: redefinition of the built-in function copy (revive) resource/deploy/state_builder.go:108:2: redefines-builtin-id: redefinition of the built-in function copy (revive) ``` **sdk** ``` go/common/resource/plugin/context.go:142:2: redefines-builtin-id: redefinition of the built-in function copy (revive) go/common/resource/plugin/plugin.go:142:12: superfluous-else: if block ends with a break statement, so drop this else and outdent its block (revive) go/common/resource/properties_diff.go:114:2: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:117:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:122:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:127:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:132:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/util/deepcopy/copy.go:30:1: redefines-builtin-id: redefinition of the built-in function copy (revive) go/common/workspace/creds.go:242:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) go/pulumi-language-go/main.go:569:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) go/pulumi-language-go/main.go:706:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) go/pulumi/run_test.go:925:2: redefines-builtin-id: redefinition of the built-in type any (revive) go/pulumi/run_test.go:933:3: redefines-builtin-id: redefinition of the built-in type any (revive) nodejs/cmd/pulumi-language-nodejs/main.go:778:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) python/cmd/pulumi-language-python/main.go:1011:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) python/cmd/pulumi-language-python/main.go:863:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) python/python.go:230:2: redefines-builtin-id: redefinition of the built-in function print (revive) ``` **tests** ``` integration/integration_util_test.go:282:11: superfluous-else: if block ends with a continue statement, so drop this else and outdent its block (move short variable declaration to its own line if necessary) (revive) ```
2023-03-20 23:48:02 +00:00
newctx := *mod
newctx.docGenContext = dctx
children := slice.Prealloc[*modContext](len(newctx.children))
all: Fix revive issues Fixes the following issues found by revive included in the latest release of golangci-lint. Full list of issues: **pkg** ``` backend/display/object_diff.go:47:10: superfluous-else: if block ends with a break statement, so drop this else and outdent its block (move short variable declaration to its own line if necessary) (revive) backend/display/object_diff.go:716:12: redefines-builtin-id: redefinition of the built-in function delete (revive) backend/display/object_diff.go:742:14: redefines-builtin-id: redefinition of the built-in function delete (revive) backend/display/object_diff.go:983:10: superfluous-else: if block ends with a continue statement, so drop this else and outdent its block (revive) backend/httpstate/backend.go:1814:4: redefines-builtin-id: redefinition of the built-in function cap (revive) backend/httpstate/backend.go:1824:5: redefines-builtin-id: redefinition of the built-in function cap (revive) backend/httpstate/client/client.go:444:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) backend/httpstate/client/client.go:455:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) cmd/pulumi/org.go:113:4: if-return: redundant if ...; err != nil check, just return error instead. (revive) cmd/pulumi/util.go:216:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) codegen/docs/gen.go:428:2: redefines-builtin-id: redefinition of the built-in function copy (revive) codegen/hcl2/model/expression.go:2151:5: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/hcl2/syntax/comments.go:151:2: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/hcl2/syntax/comments.go:329:3: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/hcl2/syntax/comments.go:381:5: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/nodejs/gen.go:1367:5: redefines-builtin-id: redefinition of the built-in function copy (revive) codegen/python/gen_program_expressions.go:136:2: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/python/gen_program_expressions.go:142:3: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/report/report.go:126:6: redefines-builtin-id: redefinition of the built-in function panic (revive) codegen/schema/docs_test.go:210:10: superfluous-else: if block ends with a continue statement, so drop this else and outdent its block (move short variable declaration to its own line if necessary) (revive) codegen/schema/schema.go:790:2: redefines-builtin-id: redefinition of the built-in type any (revive) codegen/schema/schema.go:793:4: redefines-builtin-id: redefinition of the built-in type any (revive) resource/deploy/plan.go:506:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) resource/deploy/snapshot_test.go:59:3: redefines-builtin-id: redefinition of the built-in function copy (revive) resource/deploy/state_builder.go:108:2: redefines-builtin-id: redefinition of the built-in function copy (revive) ``` **sdk** ``` go/common/resource/plugin/context.go:142:2: redefines-builtin-id: redefinition of the built-in function copy (revive) go/common/resource/plugin/plugin.go:142:12: superfluous-else: if block ends with a break statement, so drop this else and outdent its block (revive) go/common/resource/properties_diff.go:114:2: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:117:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:122:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:127:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:132:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/util/deepcopy/copy.go:30:1: redefines-builtin-id: redefinition of the built-in function copy (revive) go/common/workspace/creds.go:242:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) go/pulumi-language-go/main.go:569:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) go/pulumi-language-go/main.go:706:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) go/pulumi/run_test.go:925:2: redefines-builtin-id: redefinition of the built-in type any (revive) go/pulumi/run_test.go:933:3: redefines-builtin-id: redefinition of the built-in type any (revive) nodejs/cmd/pulumi-language-nodejs/main.go:778:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) python/cmd/pulumi-language-python/main.go:1011:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) python/cmd/pulumi-language-python/main.go:863:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) python/python.go:230:2: redefines-builtin-id: redefinition of the built-in function print (revive) ``` **tests** ``` integration/integration_util_test.go:282:11: superfluous-else: if block ends with a continue statement, so drop this else and outdent its block (move short variable declaration to its own line if necessary) (revive) ```
2023-03-20 23:48:02 +00:00
for _, c := range newctx.children {
children = append(children, c.withDocGenContext(dctx))
}
all: Fix revive issues Fixes the following issues found by revive included in the latest release of golangci-lint. Full list of issues: **pkg** ``` backend/display/object_diff.go:47:10: superfluous-else: if block ends with a break statement, so drop this else and outdent its block (move short variable declaration to its own line if necessary) (revive) backend/display/object_diff.go:716:12: redefines-builtin-id: redefinition of the built-in function delete (revive) backend/display/object_diff.go:742:14: redefines-builtin-id: redefinition of the built-in function delete (revive) backend/display/object_diff.go:983:10: superfluous-else: if block ends with a continue statement, so drop this else and outdent its block (revive) backend/httpstate/backend.go:1814:4: redefines-builtin-id: redefinition of the built-in function cap (revive) backend/httpstate/backend.go:1824:5: redefines-builtin-id: redefinition of the built-in function cap (revive) backend/httpstate/client/client.go:444:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) backend/httpstate/client/client.go:455:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) cmd/pulumi/org.go:113:4: if-return: redundant if ...; err != nil check, just return error instead. (revive) cmd/pulumi/util.go:216:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) codegen/docs/gen.go:428:2: redefines-builtin-id: redefinition of the built-in function copy (revive) codegen/hcl2/model/expression.go:2151:5: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/hcl2/syntax/comments.go:151:2: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/hcl2/syntax/comments.go:329:3: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/hcl2/syntax/comments.go:381:5: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/nodejs/gen.go:1367:5: redefines-builtin-id: redefinition of the built-in function copy (revive) codegen/python/gen_program_expressions.go:136:2: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/python/gen_program_expressions.go:142:3: redefines-builtin-id: redefinition of the built-in function close (revive) codegen/report/report.go:126:6: redefines-builtin-id: redefinition of the built-in function panic (revive) codegen/schema/docs_test.go:210:10: superfluous-else: if block ends with a continue statement, so drop this else and outdent its block (move short variable declaration to its own line if necessary) (revive) codegen/schema/schema.go:790:2: redefines-builtin-id: redefinition of the built-in type any (revive) codegen/schema/schema.go:793:4: redefines-builtin-id: redefinition of the built-in type any (revive) resource/deploy/plan.go:506:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) resource/deploy/snapshot_test.go:59:3: redefines-builtin-id: redefinition of the built-in function copy (revive) resource/deploy/state_builder.go:108:2: redefines-builtin-id: redefinition of the built-in function copy (revive) ``` **sdk** ``` go/common/resource/plugin/context.go:142:2: redefines-builtin-id: redefinition of the built-in function copy (revive) go/common/resource/plugin/plugin.go:142:12: superfluous-else: if block ends with a break statement, so drop this else and outdent its block (revive) go/common/resource/properties_diff.go:114:2: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:117:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:122:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:127:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/resource/properties_diff.go:132:4: redefines-builtin-id: redefinition of the built-in function len (revive) go/common/util/deepcopy/copy.go:30:1: redefines-builtin-id: redefinition of the built-in function copy (revive) go/common/workspace/creds.go:242:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) go/pulumi-language-go/main.go:569:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) go/pulumi-language-go/main.go:706:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) go/pulumi/run_test.go:925:2: redefines-builtin-id: redefinition of the built-in type any (revive) go/pulumi/run_test.go:933:3: redefines-builtin-id: redefinition of the built-in type any (revive) nodejs/cmd/pulumi-language-nodejs/main.go:778:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) python/cmd/pulumi-language-python/main.go:1011:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) python/cmd/pulumi-language-python/main.go:863:2: if-return: redundant if ...; err != nil check, just return error instead. (revive) python/python.go:230:2: redefines-builtin-id: redefinition of the built-in function print (revive) ``` **tests** ``` integration/integration_util_test.go:282:11: superfluous-else: if block ends with a continue statement, so drop this else and outdent its block (move short variable declaration to its own line if necessary) (revive) ```
2023-03-20 23:48:02 +00:00
newctx.children = children
return &newctx
}
Add ability to constrain supported languages of resource and function overlays (#16579) The existing overlays (e.g. Chart v3 in Kubernetes, or CallbackFunction in AWS) are not available in every language Pulumi supports. This often confuses users because the generated docs include all languages Pulumi supports (e.g. see https://github.com/pulumi/pulumi-kubernetes/issues/2181). To solve that problem, this change adds a new optional parameter to the schema that allows configuring the languages an overlay (resource or function) supports. To support this in docsgen the existing Language Chooser (`LangChooserLanguages`) of resources is made configurable and extended to functions. Note: This doesn't support resource methods right now. They'll need extra handling because and overlay resource method might not support all of the languages its resource supports. I'll tackle this in a follow up PR. Here's a screenshot of how this will look like for the Helm v3 chart for example: <img width="1046" alt="Screenshot 2024-07-01 at 16 11 23" src="https://github.com/pulumi/pulumi/assets/2453580/b1a1365a-6dee-4099-829a-2859639a4c8c"> The PR contains the following commits. I'd recommend to look at the first three ones and then check the regenerated golden files in the last one: - **Add schema parameter to constrain supported languages for overlays** - **Update developer docs and changelog** - **Refactor LanguageChooser and always pass supported languages** - **Regenerate testdata** relates to #13231
2024-07-09 14:54:50 +00:00
// getSupportedLanguages returns the list of supported languages based on the overlay configuration.
// If `isOverlay` is false or `overlaySupportedLanguages` is empty/nil, it returns the default list of supported languages.
// Otherwise, it filters the `overlaySupportedLanguages` to ensure that they are a subset of the default supported languages.
func (dctx *docGenContext) getSupportedLanguages(isOverlay bool, overlaySupportedLanguages []string) []string {
if !isOverlay || len(overlaySupportedLanguages) == 0 {
return dctx.supportedLanguages
}
var supportedLanguages []string
allLanguages := codegen.NewStringSet(dctx.supportedLanguages...)
for _, lang := range overlaySupportedLanguages {
if allLanguages.Has(lang) {
supportedLanguages = append(supportedLanguages, lang)
}
}
return supportedLanguages
}
// getSupportedSnippetLanguages returns a comma separated string containing the supported snippet languages for the given type
// based on the overlay configuration.
// If the type is not an overlay or if there are no overlay supported languages, all languages are supported.
// Internally this calls the getSupportedLanguages function to retrieve the supported languages and replaces "nodejs"
// with "typescript" because snippet languages expect "typescript" instead of "nodejs".
func (dctx *docGenContext) getSupportedSnippetLanguages(isOverlay bool, overlaySupportedLanguages []string) string {
supportedLanguages := dctx.getSupportedLanguages(isOverlay, overlaySupportedLanguages)
supportedSnippetLanguages := make([]string, len(supportedLanguages))
for idx, lang := range supportedLanguages {
if lang == "nodejs" {
lang = "typescript"
}
supportedSnippetLanguages[idx] = lang
}
return strings.Join(supportedSnippetLanguages, ",")
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
func resourceName(r *schema.Resource) string {
if r.IsProvider {
return "Provider"
}
return strings.Title(tokenToName(r.Token))
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
func (dctx *docGenContext) getLanguageDocHelper(lang string) codegen.DocLanguageHelper {
if h, ok := dctx.docHelpers[lang]; ok {
return h
}
panic(fmt.Errorf("could not find a doc lang helper for %s", lang))
}
type propertyCharacteristics struct {
// input is a flag indicating if the property is an input type.
input bool
}
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
func (mod *modContext) details(t *schema.ObjectType) *typeDetails {
details, ok := mod.typeDetails[t]
if !ok {
details = &typeDetails{}
if mod.typeDetails == nil {
mod.typeDetails = map[*schema.ObjectType]*typeDetails{}
}
mod.typeDetails[t] = details
}
return details
}
// getLanguageModuleName transforms the current module's name to a
// language-specific name using the language info, if any, for the
// current package.
func (mod *modContext) getLanguageModuleName(lang string) string {
dctx := mod.docGenContext
modName := mod.mod
lookupKey := lang + "_" + modName
if v, ok := mod.docGenContext.langModuleNameLookup[lookupKey]; ok {
return v
}
switch lang {
case "go":
// Go module names use lowercase.
modName = strings.ToLower(modName)
if override, ok := dctx.goPkgInfo.ModuleToPackage[modName]; ok {
modName = override
}
case "csharp":
if override, ok := dctx.csharpPkgInfo.Namespaces[modName]; ok {
modName = override
}
case "nodejs":
if override, ok := dctx.nodePkgInfo.ModuleToPackage[modName]; ok {
modName = override
}
case "python":
if override, ok := dctx.pythonPkgInfo.ModuleNameOverrides[modName]; ok {
modName = override
}
}
mod.docGenContext.langModuleNameLookup[lookupKey] = modName
return modName
}
// cleanTypeString removes any namespaces from the generated type string for all languages.
// The result of this function should be used display purposes only.
func (mod *modContext) cleanTypeString(t schema.Type, langTypeString, lang, modName string, isInput bool) string {
switch lang {
Display full type names in Python references in the docs (#15784) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Currently, our resource API docs for Python only display a type name itself. If the type is defined in a different module, we do not indicate this explicitly, which causes confusion. For example, [K8s Pod Inputs](https://www.pulumi.com/registry/packages/kubernetes/api-docs/core/v1/pod/#inputs) is in `core.v1` module itself but refer to the `meta.v1.ObjectMeta` type. Node.js docs display the type as <img width="719" alt="image" src="https://github.com/pulumi/pulumi/assets/1454008/fb3e8fc5-7dc8-4661-ac6f-95e7d7918cfc"> but Python simply shows <img width="725" alt="image" src="https://github.com/pulumi/pulumi/assets/1454008/4cd4c09c-13cb-4070-b716-0b78ad98379b"> The same problem exists when we reference types from external packages, and even for composed types like `Sequence[some_external_type]`. This PR removes a special case for Python that reduces a full type name to its name. Instead, it executes on the same path as Node.js and C#. I had to apply some cleaning to Python types to remove underscore prefixes of modules. We use underscore-prefixed imports in SDK gen, but they should not be visible in user docs. I expect we need to apply the same fix to Go, but I suggest we do that as a follow-up. Testing: the existing test suite seems adequate for testing the change. All the discrepancies look like improvements to me. Fixes #15137 ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [x] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2024-04-01 14:59:50 +00:00
case "go":
langTypeString = cleanOptionalIdentifier(langTypeString, lang)
parts := strings.Split(langTypeString, ".")
return parts[len(parts)-1]
}
cleanCSharpName := func(pkgName, objModName string) string {
// C# types can be wrapped in enumerable types such as List<> or Dictionary<>, so we have to
// only replace the namespace between the < and the > characters.
qualifier := "Inputs"
if !isInput {
qualifier = "Outputs"
}
var csharpNS string
// This type could be at the package-level, so it won't have a module name.
if objModName != "" {
csharpNS = fmt.Sprintf("Pulumi.%s.%s.%s.", title(pkgName, lang), title(objModName, lang), qualifier)
} else {
csharpNS = fmt.Sprintf("Pulumi.%s.%s.", title(pkgName, lang), qualifier)
}
return strings.ReplaceAll(langTypeString, csharpNS, "")
}
cleanNodeJSName := func(objModName string) string {
// The nodejs codegen currently doesn't use the ModuleToPackage override available
// in the k8s package's schema. So we'll manually strip some known module names for k8s.
// TODO[pulumi/pulumi#4325]: Remove this block once the nodejs code gen is able to use the
// package name overrides for modules.
if isKubernetesPackage(mod.pkg) {
langTypeString = strings.ReplaceAll(langTypeString, "k8s.io.", "")
langTypeString = strings.ReplaceAll(langTypeString, "apiserver.", "")
langTypeString = strings.ReplaceAll(langTypeString, "rbac.authorization.v1.", "")
langTypeString = strings.ReplaceAll(langTypeString, "rbac.authorization.v1alpha1.", "")
langTypeString = strings.ReplaceAll(langTypeString, "rbac.authorization.v1beta1.", "")
}
objModName = strings.ReplaceAll(objModName, "/", ".") + "."
return strings.ReplaceAll(langTypeString, objModName, "")
}
Display full type names in Python references in the docs (#15784) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Currently, our resource API docs for Python only display a type name itself. If the type is defined in a different module, we do not indicate this explicitly, which causes confusion. For example, [K8s Pod Inputs](https://www.pulumi.com/registry/packages/kubernetes/api-docs/core/v1/pod/#inputs) is in `core.v1` module itself but refer to the `meta.v1.ObjectMeta` type. Node.js docs display the type as <img width="719" alt="image" src="https://github.com/pulumi/pulumi/assets/1454008/fb3e8fc5-7dc8-4661-ac6f-95e7d7918cfc"> but Python simply shows <img width="725" alt="image" src="https://github.com/pulumi/pulumi/assets/1454008/4cd4c09c-13cb-4070-b716-0b78ad98379b"> The same problem exists when we reference types from external packages, and even for composed types like `Sequence[some_external_type]`. This PR removes a special case for Python that reduces a full type name to its name. Instead, it executes on the same path as Node.js and C#. I had to apply some cleaning to Python types to remove underscore prefixes of modules. We use underscore-prefixed imports in SDK gen, but they should not be visible in user docs. I expect we need to apply the same fix to Go, but I suggest we do that as a follow-up. Testing: the existing test suite seems adequate for testing the change. All the discrepancies look like improvements to me. Fixes #15137 ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [x] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2024-04-01 14:59:50 +00:00
cleanPythonName := func(objModName string) string {
// SDK codegen aliases imported top-level inputs as _root_inputs and _root_enums, e.g.
// from .. import _inputs as _root_inputs
// This is our implementation detail, so we shouldn't show this prefix
// in end-user documentation. Remove them here.
// Top-level arg types will be displayed without any module prefix.
objModName = strings.Replace(objModName, "root_enums.", "", 1)
objModName = strings.Replace(objModName, "root_inputs.", "", 1)
// SDK codegen aliases imported modules with underscored names, e.g.
// from ... import meta as _meta
// Therefore, type references for Python all have _ before module names.
// This is our implementation detail, so we shouldn't show those underscores
// in end-user documentation. Remove them here.
// We need to keep underscores inside module names though, as in 'pulumi_random'.
return removeLeadingUnderscores(objModName)
}
switch t := t.(type) {
case *schema.ObjectType:
// Strip "Args" suffixes from display names for everything but Python inputs.
if lang != "python" || (lang == "python" && !isInput) {
name := tokenToName(t.Token)
nameWithArgs := name + "Args"
// If the langTypeString looks like it's a concatenation of its name and "Args", strip out the "Args".
if strings.Contains(langTypeString, nameWithArgs) {
langTypeString = strings.ReplaceAll(langTypeString, nameWithArgs, name)
}
}
}
switch t := t.(type) {
case *schema.ArrayType:
if schema.IsPrimitiveType(t.ElementType) {
break
}
return mod.cleanTypeString(t.ElementType, langTypeString, lang, modName, isInput)
case *schema.UnionType:
for _, e := range t.ElementTypes {
if schema.IsPrimitiveType(e) {
continue
}
return mod.cleanTypeString(e, langTypeString, lang, modName, isInput)
}
case *schema.ObjectType:
objTypeModName := mod.pkg.TokenToModule(t.Token)
if objTypeModName != mod.mod {
modName = mod.getLanguageModuleName(lang)
}
}
Display full type names in Python references in the docs (#15784) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Currently, our resource API docs for Python only display a type name itself. If the type is defined in a different module, we do not indicate this explicitly, which causes confusion. For example, [K8s Pod Inputs](https://www.pulumi.com/registry/packages/kubernetes/api-docs/core/v1/pod/#inputs) is in `core.v1` module itself but refer to the `meta.v1.ObjectMeta` type. Node.js docs display the type as <img width="719" alt="image" src="https://github.com/pulumi/pulumi/assets/1454008/fb3e8fc5-7dc8-4661-ac6f-95e7d7918cfc"> but Python simply shows <img width="725" alt="image" src="https://github.com/pulumi/pulumi/assets/1454008/4cd4c09c-13cb-4070-b716-0b78ad98379b"> The same problem exists when we reference types from external packages, and even for composed types like `Sequence[some_external_type]`. This PR removes a special case for Python that reduces a full type name to its name. Instead, it executes on the same path as Node.js and C#. I had to apply some cleaning to Python types to remove underscore prefixes of modules. We use underscore-prefixed imports in SDK gen, but they should not be visible in user docs. I expect we need to apply the same fix to Go, but I suggest we do that as a follow-up. Testing: the existing test suite seems adequate for testing the change. All the discrepancies look like improvements to me. Fixes #15137 ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [x] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2024-04-01 14:59:50 +00:00
switch lang {
case "nodejs":
return cleanNodeJSName(modName)
Display full type names in Python references in the docs (#15784) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Currently, our resource API docs for Python only display a type name itself. If the type is defined in a different module, we do not indicate this explicitly, which causes confusion. For example, [K8s Pod Inputs](https://www.pulumi.com/registry/packages/kubernetes/api-docs/core/v1/pod/#inputs) is in `core.v1` module itself but refer to the `meta.v1.ObjectMeta` type. Node.js docs display the type as <img width="719" alt="image" src="https://github.com/pulumi/pulumi/assets/1454008/fb3e8fc5-7dc8-4661-ac6f-95e7d7918cfc"> but Python simply shows <img width="725" alt="image" src="https://github.com/pulumi/pulumi/assets/1454008/4cd4c09c-13cb-4070-b716-0b78ad98379b"> The same problem exists when we reference types from external packages, and even for composed types like `Sequence[some_external_type]`. This PR removes a special case for Python that reduces a full type name to its name. Instead, it executes on the same path as Node.js and C#. I had to apply some cleaning to Python types to remove underscore prefixes of modules. We use underscore-prefixed imports in SDK gen, but they should not be visible in user docs. I expect we need to apply the same fix to Go, but I suggest we do that as a follow-up. Testing: the existing test suite seems adequate for testing the change. All the discrepancies look like improvements to me. Fixes #15137 ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [x] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2024-04-01 14:59:50 +00:00
case "csharp":
2022-12-12 14:55:35 +00:00
return cleanCSharpName(mod.pkg.Name(), modName)
Display full type names in Python references in the docs (#15784) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Currently, our resource API docs for Python only display a type name itself. If the type is defined in a different module, we do not indicate this explicitly, which causes confusion. For example, [K8s Pod Inputs](https://www.pulumi.com/registry/packages/kubernetes/api-docs/core/v1/pod/#inputs) is in `core.v1` module itself but refer to the `meta.v1.ObjectMeta` type. Node.js docs display the type as <img width="719" alt="image" src="https://github.com/pulumi/pulumi/assets/1454008/fb3e8fc5-7dc8-4661-ac6f-95e7d7918cfc"> but Python simply shows <img width="725" alt="image" src="https://github.com/pulumi/pulumi/assets/1454008/4cd4c09c-13cb-4070-b716-0b78ad98379b"> The same problem exists when we reference types from external packages, and even for composed types like `Sequence[some_external_type]`. This PR removes a special case for Python that reduces a full type name to its name. Instead, it executes on the same path as Node.js and C#. I had to apply some cleaning to Python types to remove underscore prefixes of modules. We use underscore-prefixed imports in SDK gen, but they should not be visible in user docs. I expect we need to apply the same fix to Go, but I suggest we do that as a follow-up. Testing: the existing test suite seems adequate for testing the change. All the discrepancies look like improvements to me. Fixes #15137 ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [x] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2024-04-01 14:59:50 +00:00
case "python":
return cleanPythonName(langTypeString)
default:
return strings.ReplaceAll(langTypeString, modName, "")
}
}
// typeString returns a property type suitable for docs with its display name and the anchor link to
// a type if the type of the property is an array or an object.
func (mod *modContext) typeString(t schema.Type, lang string, characteristics propertyCharacteristics, insertWordBreaks bool) propertyType {
t = codegen.PlainType(t)
docLanguageHelper := mod.docGenContext.getLanguageDocHelper(lang)
modName := mod.getLanguageModuleName(lang)
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get package definition for %q", mod.pkg.Name())
2022-12-12 14:55:35 +00:00
langTypeString := docLanguageHelper.GetLanguageTypeString(def, modName, t, characteristics.input)
if optional, ok := t.(*schema.OptionalType); ok {
t = optional.ElementType
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// If the type is an object type, let's also wrap it with a link to the supporting type
// on the same page using an anchor tag.
var href string
switch t := t.(type) {
case *schema.ArrayType:
elementLangType := mod.typeString(t.ElementType, lang, characteristics, false)
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
href = elementLangType.Link
case *schema.ObjectType:
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
tokenName := tokenToName(t.Token)
// Links to anchor tags on the same page must be lower-cased.
href = "#" + strings.ToLower(tokenName)
case *schema.EnumType:
tokenName := tokenToName(t.Token)
// Links to anchor tags on the same page must be lower-cased.
href = "#" + strings.ToLower(tokenName)
case *schema.UnionType:
var elements []string
for _, e := range t.ElementTypes {
elementLangType := mod.typeString(e, lang, characteristics, false)
elements = append(elements, elementLangType.DisplayName)
}
langTypeString = strings.Join(elements, " | ")
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
// Strip the namespace/module prefix for the type's display name.
displayName := langTypeString
if !schema.IsPrimitiveType(t) {
displayName = mod.cleanTypeString(t, langTypeString, lang, modName, characteristics.input)
}
displayName = cleanOptionalIdentifier(displayName, lang)
langTypeString = cleanOptionalIdentifier(langTypeString, lang)
// Name and DisplayName should be html-escaped to avoid throwing off rendering for template types in languages like
// csharp, Java etc. If word-breaks need to be inserted, then the type string should be html-escaped first.
displayName = html.EscapeString(displayName)
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
if insertWordBreaks {
displayName = wbr(displayName)
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
return propertyType{
Name: html.EscapeString(langTypeString),
DisplayName: displayName,
Link: href,
}
}
// cleanOptionalIdentifier removes the type identifier (i.e. "?" in "string?").
func cleanOptionalIdentifier(s, lang string) string {
switch lang {
case "nodejs":
return strings.TrimSuffix(s, "?")
case "go":
return strings.TrimPrefix(s, "*")
case "csharp":
return strings.TrimSuffix(s, "?")
case "python":
if strings.HasPrefix(s, "Optional[") && strings.HasSuffix(s, "]") {
s = strings.TrimPrefix(s, "Optional[")
s = strings.TrimSuffix(s, "]")
return s
}
}
return s
}
// Resources typically take the same set of parameters to their constructors, and these
// are the default comments/descriptions for them.
const (
ctorNameArgComment = "The unique name of the resource."
ctorArgsArgComment = "The arguments to resource properties."
ctorOptsArgComment = "Bag of options to control resource's behavior."
)
func (mod *modContext) genConstructorTS(r *schema.Resource, argsOptional bool) []formalParam {
name := resourceName(r)
docLangHelper := mod.docGenContext.getLanguageDocHelper("nodejs")
var argsType string
optsType := "CustomResourceOptions"
// The args type for k8s package differs from the rest depending on whether we are dealing with
// overlay resources or regular k8s resources.
if isKubernetesPackage(mod.pkg) {
if mod.isKubernetesOverlayModule() {
if name == "CustomResource" {
argsType = name + "Args"
} else {
argsType = name + "Opts"
}
} else {
// The non-schema-based k8s codegen does not apply a suffix to the input types.
argsType = name
}
if mod.isComponentResource() {
optsType = "ComponentResourceOptions"
}
} else {
argsType = name + "Args"
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
argsFlag := ""
if argsOptional {
argsFlag = "?"
}
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-12-12 14:55:35 +00:00
return []formalParam{
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
{
Name: "name",
Type: propertyType{
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
Name: "string",
},
Comment: ctorNameArgComment,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
{
Name: "args",
OptionalFlag: argsFlag,
Type: propertyType{
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
Name: argsType,
Link: "#inputs",
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
Comment: ctorArgsArgComment,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
{
Name: "opts",
OptionalFlag: "?",
Type: propertyType{
Name: optsType,
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, optsType),
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
Comment: ctorOptsArgComment,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
}
}
func (mod *modContext) genConstructorGo(r *schema.Resource, argsOptional bool) []formalParam {
name := resourceName(r)
argsType := name + "Args"
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
argsFlag := ""
if argsOptional {
argsFlag = "*"
}
docLangHelper := mod.docGenContext.getLanguageDocHelper("go")
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-12-12 14:55:35 +00:00
return []formalParam{
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
{
Name: "ctx",
OptionalFlag: "*",
Type: propertyType{
Name: "Context",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "Context"),
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
Comment: "Context object for the current deployment.",
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
{
Name: "name",
Type: propertyType{
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
Name: "string",
},
Comment: ctorNameArgComment,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
{
Name: "args",
OptionalFlag: argsFlag,
Type: propertyType{
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
Name: argsType,
Link: "#inputs",
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
Comment: ctorArgsArgComment,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
{
Name: "opts",
OptionalFlag: "...",
Type: propertyType{
Name: "ResourceOption",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "ResourceOption"),
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
Comment: ctorOptsArgComment,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
}
}
func (mod *modContext) genConstructorCS(r *schema.Resource, argsOptional bool) []formalParam {
name := resourceName(r)
optsType := "CustomResourceOptions"
if isKubernetesPackage(mod.pkg) && mod.isComponentResource() {
optsType = "ComponentResourceOptions"
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
var argsFlag string
var argsDefault string
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
if argsOptional {
// If the number of required input properties was zero, we can make the args object optional.
argsDefault = " = null"
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
argsFlag = "?"
}
docLangHelper := mod.docGenContext.getLanguageDocHelper("csharp")
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-12-12 14:55:35 +00:00
return []formalParam{
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
{
Name: "name",
Type: propertyType{
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
Name: "string",
},
Comment: ctorNameArgComment,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
{
Name: "args",
OptionalFlag: argsFlag,
DefaultValue: argsDefault,
Type: propertyType{
Name: name + "Args",
Link: "#inputs",
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
Comment: ctorArgsArgComment,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
{
Name: "opts",
OptionalFlag: "?",
DefaultValue: " = null",
Type: propertyType{
Name: optsType,
Enable perfsprint linter (#14813) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description <!--- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. --> Prompted by a comment in another review: https://github.com/pulumi/pulumi/pull/14654#discussion_r1419995945 This lints that we don't use `fmt.Errorf` when `errors.New` will suffice, it also covers a load of other cases where `Sprintf` is sub-optimal. Most of these edits were made by running `perfsprint --fix`. ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2023-12-12 12:19:42 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "Pulumi."+optsType),
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
Comment: ctorOptsArgComment,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
},
}
}
2022-04-21 11:23:36 +00:00
func (mod *modContext) genConstructorYaml() []formalParam {
return []formalParam{
{
Name: "properties",
Comment: ctorArgsArgComment,
},
{
Name: "options",
Comment: ctorOptsArgComment,
},
}
}
func (mod *modContext) genConstructorJava(r *schema.Resource, argsOverload bool) []formalParam {
name := resourceName(r)
optsType := "CustomResourceOptions"
if mod.isComponentResource() {
optsType = "ComponentResourceOptions"
}
docLangHelper := mod.docGenContext.getLanguageDocHelper("java")
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-12-12 14:55:35 +00:00
2022-04-21 11:23:36 +00:00
result := []formalParam{
{
Name: "name",
Type: propertyType{
Name: "String",
},
Comment: ctorNameArgComment,
},
{
Name: "args",
Type: propertyType{
Name: name + "Args",
Link: "#inputs",
2022-04-21 11:23:36 +00:00
},
Comment: ctorArgsArgComment,
},
}
if !argsOverload {
result = append(result, formalParam{
Name: "options",
OptionalFlag: "@Nullable",
Type: propertyType{
Name: optsType,
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, optsType),
2022-04-21 11:23:36 +00:00
},
Comment: ctorOptsArgComment,
})
}
return result
}
func (mod *modContext) genConstructorPython(r *schema.Resource, argsOptional, argsOverload bool) []formalParam {
docLanguageHelper := mod.docGenContext.getLanguageDocHelper("python")
isK8sOverlayMod := mod.isKubernetesOverlayModule()
2022-12-12 14:55:35 +00:00
isDockerImageResource := mod.pkg.Name() == "docker" && resourceName(r) == "Image"
// Kubernetes overlay resources use a different ordering of formal params in Python.
if isK8sOverlayMod && r.IsOverlay {
return getKubernetesOverlayPythonFormalParams(mod.mod)
} else if isDockerImageResource {
return getDockerImagePythonFormalParams()
}
2023-01-12 17:04:35 +00:00
// We perform at least three appends before iterating over input types.
params := slice.Prealloc[formalParam](3 + len(r.InputProperties))
params = append(params, formalParam{
Name: "resource_name",
Type: propertyType{
Name: "str",
},
Comment: ctorNameArgComment,
})
if argsOverload {
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
// Determine whether we need to use the alternate args class name (e.g. `<Resource>InitArgs` instead of
// `<Resource>Args`) due to an input type with the same name as the resource in the same module.
resName := resourceName(r)
Enable perfsprint linter (#14813) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description <!--- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. --> Prompted by a comment in another review: https://github.com/pulumi/pulumi/pull/14654#discussion_r1419995945 This lints that we don't use `fmt.Errorf` when `errors.New` will suffice, it also covers a load of other cases where `Sprintf` is sub-optimal. Most of these edits were made by running `perfsprint --fix`. ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2023-12-12 12:19:42 +00:00
resArgsName := resName + "Args"
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
for _, inputType := range mod.inputTypes {
inputTypeName := strings.Title(tokenToName(inputType.Token))
if resName == inputTypeName {
Enable perfsprint linter (#14813) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description <!--- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. --> Prompted by a comment in another review: https://github.com/pulumi/pulumi/pull/14654#discussion_r1419995945 This lints that we don't use `fmt.Errorf` when `errors.New` will suffice, it also covers a load of other cases where `Sprintf` is sub-optimal. Most of these edits were made by running `perfsprint --fix`. ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2023-12-12 12:19:42 +00:00
resArgsName = resName + "InitArgs"
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
}
}
optionalFlag, defaultVal, descriptionName := "", "", resArgsName
typeName := descriptionName
if argsOptional {
optionalFlag, defaultVal, typeName = "optional", " = None", fmt.Sprintf("Optional[%s]", typeName)
}
params = append(params, formalParam{
Name: "args",
OptionalFlag: optionalFlag,
DefaultValue: defaultVal,
Type: propertyType{
Name: typeName,
DescriptionName: descriptionName,
Link: "#inputs",
},
Comment: ctorArgsArgComment,
})
}
params = append(params, formalParam{
Name: "opts",
OptionalFlag: "optional",
DefaultValue: " = None",
Type: propertyType{
Name: "Optional[ResourceOptions]",
DescriptionName: "ResourceOptions",
Link: "/docs/reference/pkg/python/pulumi/#pulumi.ResourceOptions",
},
Comment: ctorOptsArgComment,
})
if argsOverload {
return params
}
for _, p := range r.InputProperties {
// If the property defines a const value, then skip it.
// For example, in k8s, `apiVersion` and `kind` are often hard-coded
// in the SDK and are not really user-provided input properties.
if p.ConstValue != nil {
continue
}
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-12-12 14:55:35 +00:00
typ := docLanguageHelper.GetLanguageTypeString(def, mod.mod, codegen.PlainType(codegen.OptionalType(p)), true /*input*/)
params = append(params, formalParam{
Name: python.InitParamName(p.Name),
DefaultValue: " = None",
Type: propertyType{
Name: typ,
},
})
}
return params
}
func (mod *modContext) genNestedTypes(member interface{}, resourceType bool) []docNestedType {
dctx := mod.docGenContext
tokens := nestedTypeUsageInfo{}
// Collect all of the types for this "member" as a map of resource names
// and if it appears in an input object and/or output object.
mod.getTypes(member, tokens)
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
sortedTokens := slice.Prealloc[string](len(tokens))
for token := range tokens {
2021-11-19 16:23:06 +00:00
sortedTokens = append(sortedTokens, token)
}
sort.Strings(sortedTokens)
var typs []docNestedType
for _, token := range sortedTokens {
2022-12-12 14:55:35 +00:00
for iter := mod.pkg.Types().Range(); iter.Next(); {
t, err := iter.Type()
contract.AssertNoErrorf(err, "error iterating types")
switch typ := t.(type) {
case *schema.ObjectType:
if typ.Token != token || len(typ.Properties) == 0 || typ.IsInputShape() {
continue
}
// Create a map to hold the per-language properties of this object.
props := make(map[string][]property)
for _, lang := range dctx.supportedLanguages {
props[lang] = mod.getProperties(typ.Properties, lang, true, true, false)
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
name := strings.Title(tokenToName(typ.Token))
typs = append(typs, docNestedType{
Name: wbr(name),
AnchorID: strings.ToLower(name),
Properties: props,
})
case *schema.EnumType:
if typ.Token != token || len(typ.Elements) == 0 {
continue
}
name := strings.Title(tokenToName(typ.Token))
enums := make(map[string][]enum)
for _, lang := range dctx.supportedLanguages {
docLangHelper := dctx.getLanguageDocHelper(lang)
var langEnumValues []enum
for _, e := range typ.Elements {
enumName, err := docLangHelper.GetEnumName(e, name)
if err != nil {
panic(err)
}
enumID := strings.ToLower(name + propertyLangSeparator + lang)
langEnumValues = append(langEnumValues, enum{
ID: enumID,
DisplayName: wbr(enumName),
Name: enumName,
Value: fmt.Sprintf("%v", e.Value),
Comment: e.Comment,
DeprecationMessage: e.DeprecationMessage,
})
}
enums[lang] = langEnumValues
}
typs = append(typs, docNestedType{
Name: wbr(name),
AnchorID: strings.ToLower(name),
EnumValues: enums,
})
}
}
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
sort.Slice(typs, func(i, j int) bool {
return typs[i].Name < typs[j].Name
})
return typs
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// getProperties returns a slice of properties that can be rendered for docs for
// the provided slice of properties in the schema.
func (mod *modContext) getProperties(properties []*schema.Property, lang string, input, nested, isProvider bool,
) []property {
2021-08-13 00:20:13 +00:00
return mod.getPropertiesWithIDPrefixAndExclude(properties, lang, input, nested, isProvider, "", nil)
}
2021-08-13 00:20:13 +00:00
func (mod *modContext) getPropertiesWithIDPrefixAndExclude(properties []*schema.Property, lang string, input, nested,
all: Reformat with gofumpt Per team discussion, switching to gofumpt. [gofumpt][1] is an alternative, stricter alternative to gofmt. It addresses other stylistic concerns that gofmt doesn't yet cover. [1]: https://github.com/mvdan/gofumpt See the full list of [Added rules][2], but it includes: - Dropping empty lines around function bodies - Dropping unnecessary variable grouping when there's only one variable - Ensuring an empty line between multi-line functions - simplification (`-s` in gofmt) is always enabled - Ensuring multi-line function signatures end with `) {` on a separate line. [2]: https://github.com/mvdan/gofumpt#Added-rules gofumpt is stricter, but there's no lock-in. All gofumpt output is valid gofmt output, so if we decide we don't like it, it's easy to switch back without any code changes. gofumpt support is built into the tooling we use for development so this won't change development workflows. - golangci-lint includes a gofumpt check (enabled in this PR) - gopls, the LSP for Go, includes a gofumpt option (see [installation instrutions][3]) [3]: https://github.com/mvdan/gofumpt#installation This change was generated by running: ```bash gofumpt -w $(rg --files -g '*.go' | rg -v testdata | rg -v compilation_error) ``` The following files were manually tweaked afterwards: - pkg/cmd/pulumi/stack_change_secrets_provider.go: one of the lines overflowed and had comments in an inconvenient place - pkg/cmd/pulumi/destroy.go: `var x T = y` where `T` wasn't necessary - pkg/cmd/pulumi/policy_new.go: long line because of error message - pkg/backend/snapshot_test.go: long line trying to assign three variables in the same assignment I have included mention of gofumpt in the CONTRIBUTING.md.
2023-03-03 16:36:39 +00:00
isProvider bool, idPrefix string, exclude func(name string) bool,
) []property {
dctx := mod.docGenContext
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
if len(properties) == 0 {
return nil
}
docProperties := slice.Prealloc[property](len(properties))
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
for _, prop := range properties {
if prop == nil {
continue
}
if exclude != nil && exclude(prop.Name) {
continue
}
// If the property has a const value, then don't show it as an input property.
// Even though it is a valid property, it is used by the language code gen to
// generate the appropriate defaults for it. These cannot be overridden by users.
if prop.ConstValue != nil {
continue
}
characteristics := propertyCharacteristics{input: input}
langDocHelper := dctx.getLanguageDocHelper(lang)
name, err := langDocHelper.GetPropertyName(prop)
if err != nil {
panic(err)
}
propLangName := name
propID := idPrefix + strings.ToLower(propLangName+propertyLangSeparator+lang)
2020-05-22 21:53:34 +00:00
propTypes := make([]propertyType, 0)
if typ, isUnion := codegen.UnwrapType(prop.Type).(*schema.UnionType); isUnion {
for _, elementType := range typ.ElementTypes {
propTypes = append(propTypes, mod.typeString(elementType, lang, characteristics, true))
}
} else {
propTypes = append(propTypes, mod.typeString(prop.Type, lang, characteristics, true))
}
comment := prop.Comment
link := "#" + propID
// Check if type is defined in a package external to the current package. If
// it is external, update comment to indicate to user that type is defined
// in another package and link there.
if isExt := isExternalType(codegen.UnwrapType(prop.Type), mod.pkg); isExt {
packageName := tokenToPackageName(fmt.Sprintf("%v", codegen.UnwrapType(prop.Type)))
extPkgLink := "/registry/packages/" + packageName
comment += fmt.Sprintf("\nThis type is defined in the [%s](%s) package.", getPackageDisplayName(packageName), extPkgLink)
}
// Default values for Provider inputs correspond to environment variables, so add that info to the docs.
if isProvider && input && prop.DefaultValue != nil && len(prop.DefaultValue.Environment) > 0 {
var suffix string
if len(prop.DefaultValue.Environment) > 1 {
suffix = "s"
}
comment += fmt.Sprintf(" It can also be sourced from the following environment variable%s: ", suffix)
for i, v := range prop.DefaultValue.Environment {
comment += fmt.Sprintf("`%s`", v)
if i != len(prop.DefaultValue.Environment)-1 {
comment += ", "
}
}
}
docProperties = append(docProperties, property{
2020-05-22 21:53:34 +00:00
ID: propID,
DisplayName: wbr(propLangName),
Name: propLangName,
Comment: comment,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
DeprecationMessage: prop.DeprecationMessage,
IsRequired: prop.IsRequired(),
IsInput: input,
// We indicate that a property will replace if either
// a) we will force the replace at the engine level
// b) we are told that the provider will require a replace
IsReplaceOnChanges: prop.ReplaceOnChanges || prop.WillReplaceOnChanges,
Link: link,
Types: propTypes,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
})
}
// Sort required props to move them to the top of the properties list, then by name.
sort.SliceStable(docProperties, func(i, j int) bool {
pi, pj := docProperties[i], docProperties[j]
switch {
case pi.IsRequired != pj.IsRequired:
return pi.IsRequired && !pj.IsRequired
default:
return pi.Name < pj.Name
}
})
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
return docProperties
}
func getDockerImagePythonFormalParams() []formalParam {
return []formalParam{
{
Name: "image_name",
},
{
Name: "build",
},
{
Name: "local_image_name",
DefaultValue: "=None",
},
{
Name: "registry",
DefaultValue: "=None",
},
{
Name: "skip_push",
DefaultValue: "=None",
},
{
Name: "opts",
DefaultValue: "=None",
},
}
}
// Returns the rendered HTML for the resource's constructor, as well as the specific arguments.
func (mod *modContext) genConstructors(r *schema.Resource, allOptionalInputs bool) (map[string]string, map[string][]formalParam) {
dctx := mod.docGenContext
renderedParams := make(map[string]string)
formalParams := make(map[string][]formalParam)
// Add an extra language for Python's ResourceArg __init__ overload.
langs := append(dctx.supportedLanguages, "pythonargs")
2022-04-21 11:23:36 +00:00
// Add an extra language for Java's ResourceArg overload.
langs = append(langs, "javaargs")
for _, lang := range langs {
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
var (
paramTemplate string
params []formalParam
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
)
b := &bytes.Buffer{}
paramSeparatorTemplate := "param_separator"
ps := paramSeparator{}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
switch lang {
case "nodejs":
params = mod.genConstructorTS(r, allOptionalInputs)
paramTemplate = "ts_formal_param"
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
case "go":
params = mod.genConstructorGo(r, allOptionalInputs)
paramTemplate = "go_formal_param"
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
case "csharp":
params = mod.genConstructorCS(r, allOptionalInputs)
paramTemplate = "csharp_formal_param"
2022-04-21 11:23:36 +00:00
case "java":
fallthrough
case "javaargs":
argsOverload := lang == "javaargs"
params = mod.genConstructorJava(r, argsOverload)
paramTemplate = "java_formal_param"
case "python":
fallthrough
case "pythonargs":
argsOverload := lang == "pythonargs"
params = mod.genConstructorPython(r, allOptionalInputs, argsOverload)
paramTemplate = "py_formal_param"
paramSeparatorTemplate = "py_param_separator"
ps = paramSeparator{Indent: strings.Repeat(" ", len("def (")+len(resourceName(r)))}
2022-04-21 11:23:36 +00:00
case "yaml":
params = mod.genConstructorYaml()
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
2022-04-21 11:23:36 +00:00
if paramTemplate != "" {
for i, p := range params {
if i != 0 {
if err := dctx.templates.ExecuteTemplate(b, paramSeparatorTemplate, ps); err != nil {
panic(err)
}
}
if err := dctx.templates.ExecuteTemplate(b, paramTemplate, p); err != nil {
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
panic(err)
}
}
}
renderedParams[lang] = b.String()
formalParams[lang] = params
}
return renderedParams, formalParams
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// getConstructorResourceInfo returns a map of per-language information about
// the resource being constructed.
2022-04-21 11:23:36 +00:00
func (mod *modContext) getConstructorResourceInfo(resourceTypeName, tok string) map[string]propertyType {
dctx := mod.docGenContext
2022-04-21 11:23:36 +00:00
docLangHelper := dctx.getLanguageDocHelper("yaml")
resourceMap := make(map[string]propertyType)
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
resourceDisplayName := resourceTypeName
for _, lang := range dctx.supportedLanguages {
// Use the module to package lookup to transform the module name to its normalized package name.
modName := mod.getLanguageModuleName(lang)
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// Reset the type name back to the display name.
resourceTypeName = resourceDisplayName
switch lang {
2022-04-21 11:23:36 +00:00
case "nodejs", "go", "python", "java":
// Intentionally left blank.
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
case "csharp":
2022-12-12 14:55:35 +00:00
namespace := title(mod.pkg.Name(), lang)
if ns, ok := dctx.csharpPkgInfo.Namespaces[mod.pkg.Name()]; ok {
namespace = ns
}
if mod.mod == "" {
resourceTypeName = fmt.Sprintf("Pulumi.%s.%s", namespace, resourceTypeName)
break
}
resourceTypeName = fmt.Sprintf("Pulumi.%s.%s.%s", namespace, modName, resourceTypeName)
2022-04-21 11:23:36 +00:00
case "yaml":
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-04-21 11:23:36 +00:00
resourceMap[lang] = propertyType{
Name: resourceTypeName,
2022-12-12 14:55:35 +00:00
DisplayName: docLangHelper.GetLanguageTypeString(def, mod.mod, &schema.ResourceType{Token: tok}, false),
2022-04-21 11:23:36 +00:00
}
continue
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
default:
panic(fmt.Errorf("cannot generate constructor info for unhandled language %q", lang))
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
parts := strings.Split(resourceTypeName, ".")
displayName := parts[len(parts)-1]
resourceMap[lang] = propertyType{
Name: resourceDisplayName,
DisplayName: displayName,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
return resourceMap
}
func (mod *modContext) getTSLookupParams(r *schema.Resource, stateParam string) []formalParam {
dctx := mod.docGenContext
docLangHelper := dctx.getLanguageDocHelper("nodejs")
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
return []formalParam{
{
Name: "name",
Type: propertyType{
Name: "string",
},
},
{
Name: "id",
Type: propertyType{
Name: "Input<ID>",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "ID"),
},
},
{
Name: "state",
OptionalFlag: "?",
Type: propertyType{
Name: stateParam,
},
},
{
Name: "opts",
OptionalFlag: "?",
Type: propertyType{
Name: "CustomResourceOptions",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "CustomResourceOptions"),
},
},
}
}
func (mod *modContext) getGoLookupParams(r *schema.Resource, stateParam string) []formalParam {
dctx := mod.docGenContext
docLangHelper := dctx.getLanguageDocHelper("go")
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-12-12 14:55:35 +00:00
return []formalParam{
{
Name: "ctx",
OptionalFlag: "*",
Type: propertyType{
Name: "Context",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "Context"),
},
},
{
Name: "name",
Type: propertyType{
Name: "string",
},
},
{
Name: "id",
Type: propertyType{
Name: "IDInput",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "IDInput"),
},
},
{
Name: "state",
OptionalFlag: "*",
Type: propertyType{
Name: stateParam,
},
},
{
Name: "opts",
OptionalFlag: "...",
Type: propertyType{
Name: "ResourceOption",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "ResourceOption"),
},
},
}
}
func (mod *modContext) getCSLookupParams(r *schema.Resource, stateParam string) []formalParam {
dctx := mod.docGenContext
docLangHelper := dctx.getLanguageDocHelper("csharp")
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-12-12 14:55:35 +00:00
return []formalParam{
{
Name: "name",
Type: propertyType{
Name: "string",
},
},
{
Name: "id",
Type: propertyType{
Name: "Input<string>",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "Pulumi.Input"),
},
},
{
Name: "state",
OptionalFlag: "?",
Type: propertyType{
Name: stateParam,
},
},
{
Name: "opts",
OptionalFlag: "?",
DefaultValue: " = null",
Type: propertyType{
Name: "CustomResourceOptions",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "Pulumi.CustomResourceOptions"),
},
},
}
}
2022-04-21 11:23:36 +00:00
func (mod *modContext) getJavaLookupParams(r *schema.Resource, stateParam string) []formalParam {
dctx := mod.docGenContext
docLangHelper := dctx.getLanguageDocHelper("java")
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-04-21 11:23:36 +00:00
return []formalParam{
{
Name: "name",
Type: propertyType{
Name: "String",
},
},
{
Name: "id",
Type: propertyType{
Name: "Output<String>",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "Output"),
2022-04-21 11:23:36 +00:00
},
},
{
Name: "state",
Type: propertyType{
Name: stateParam,
},
},
{
Name: "options",
Type: propertyType{
Name: "CustomResourceOptions",
2022-12-12 14:55:35 +00:00
Link: docLangHelper.GetDocLinkForPulumiType(def, "CustomResourceOptions"),
2022-04-21 11:23:36 +00:00
},
},
}
}
func (mod *modContext) getPythonLookupParams(r *schema.Resource, stateParam string) []formalParam {
dctx := mod.docGenContext
// The input properties for a resource needs to be exploded as
// individual constructor params.
docLanguageHelper := dctx.getLanguageDocHelper("python")
params := slice.Prealloc[formalParam](len(r.StateInputs.Properties))
for _, p := range r.StateInputs.Properties {
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-12-12 14:55:35 +00:00
typ := docLanguageHelper.GetLanguageTypeString(def, mod.mod, codegen.PlainType(codegen.OptionalType(p)), true /*input*/)
params = append(params, formalParam{
Name: python.PyName(p.Name),
DefaultValue: " = None",
Type: propertyType{
Name: typ,
},
})
}
return params
}
// genLookupParams generates a map of per-language way of rendering the formal parameters of the lookup function
// used to lookup an existing resource.
func (mod *modContext) genLookupParams(r *schema.Resource, stateParam string) map[string]string {
dctx := mod.docGenContext
lookupParams := make(map[string]string)
if r.StateInputs == nil {
return lookupParams
}
for _, lang := range dctx.supportedLanguages {
var (
paramTemplate string
params []formalParam
)
b := &bytes.Buffer{}
paramSeparatorTemplate := "param_separator"
ps := paramSeparator{}
switch lang {
case "nodejs":
params = mod.getTSLookupParams(r, stateParam)
paramTemplate = "ts_formal_param"
case "go":
params = mod.getGoLookupParams(r, stateParam)
paramTemplate = "go_formal_param"
case "csharp":
params = mod.getCSLookupParams(r, stateParam)
paramTemplate = "csharp_formal_param"
2022-04-21 11:23:36 +00:00
case "java":
params = mod.getJavaLookupParams(r, stateParam)
paramTemplate = "java_formal_param"
case "python":
params = mod.getPythonLookupParams(r, stateParam)
paramTemplate = "py_formal_param"
paramSeparatorTemplate = "py_param_separator"
ps = paramSeparator{Indent: strings.Repeat(" ", len("def get("))}
}
n := len(params)
for i, p := range params {
if err := dctx.templates.ExecuteTemplate(b, paramTemplate, p); err != nil {
panic(err)
}
if i != n-1 {
if err := dctx.templates.ExecuteTemplate(b, paramSeparatorTemplate, ps); err != nil {
panic(err)
}
}
}
lookupParams[lang] = b.String()
}
return lookupParams
}
// filterOutputProperties removes the input properties from the output properties list
// (since input props are implicitly output props), returning only "output" props.
func filterOutputProperties(inputProps []*schema.Property, props []*schema.Property) []*schema.Property {
var outputProps []*schema.Property
inputMap := make(map[string]bool, len(inputProps))
for _, p := range inputProps {
inputMap[p.Name] = true
}
for _, p := range props {
if _, found := inputMap[p.Name]; !found {
outputProps = append(outputProps, p)
}
}
return outputProps
}
func (mod *modContext) genResourceHeader(r *schema.Resource) header {
resourceName := resourceName(r)
var metaDescription string
var titleTag string
if mod.mod == "" {
metaDescription = fmt.Sprintf("Documentation for the %s.%s resource "+
"with examples, input properties, output properties, "+
2022-12-12 14:55:35 +00:00
"lookup functions, and supporting types.", mod.pkg.Name(), resourceName)
titleTag = fmt.Sprintf("%s.%s", mod.pkg.Name(), resourceName)
} else {
metaDescription = fmt.Sprintf("Documentation for the %s.%s.%s resource "+
"with examples, input properties, output properties, "+
2022-12-12 14:55:35 +00:00
"lookup functions, and supporting types.", mod.pkg.Name(), mod.mod, resourceName)
titleTag = fmt.Sprintf("%s.%s.%s", mod.pkg.Name(), mod.mod, resourceName)
}
return header{
Title: resourceName,
TitleTag: titleTag,
MetaDesc: metaDescription,
}
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// genResource is the entrypoint for generating a doc for a resource
// from its Pulumi schema.
func (mod *modContext) genResource(r *schema.Resource) resourceDocArgs {
dctx := mod.docGenContext
// Create a resource module file into which all of this resource's types will go.
name := resourceName(r)
inputProps := make(map[string][]property)
outputProps := make(map[string][]property)
stateInputs := make(map[string][]property)
var filteredOutputProps []*schema.Property
// Provider resources do not have output properties, so there won't be anything to filter.
if !r.IsProvider {
filteredOutputProps = filterOutputProperties(r.InputProperties, r.Properties)
}
// All custom resources have an implicit `id` output property, that we must inject into the docs.
if !r.IsComponent {
filteredOutputProps = append(filteredOutputProps, &schema.Property{
Name: "id",
Comment: "The provider-assigned unique ID for this managed resource.",
Type: schema.StringType,
})
}
for _, lang := range dctx.supportedLanguages {
inputProps[lang] = mod.getProperties(r.InputProperties, lang, true, false, r.IsProvider)
outputProps[lang] = mod.getProperties(filteredOutputProps, lang, false, false, r.IsProvider)
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
if r.IsProvider {
continue
}
if r.StateInputs != nil {
stateProps := mod.getProperties(r.StateInputs.Properties, lang, true, false, r.IsProvider)
2020-05-22 21:53:34 +00:00
for i := 0; i < len(stateProps); i++ {
id := "state_" + stateProps[i].ID
stateProps[i].ID = id
stateProps[i].Link = "#" + id
2020-05-22 21:53:34 +00:00
}
stateInputs[lang] = stateProps
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
}
allOptionalInputs := true
for _, prop := range r.InputProperties {
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
// If at least one prop is required, then break.
if prop.IsRequired() {
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
allOptionalInputs = false
break
}
}
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %s", mod.pkg.Name())
packageDetails := packageDetails{
2023-01-17 18:22:12 +00:00
DisplayName: getPackageDisplayName(def.Name),
Repository: def.Repository,
RepositoryName: getRepositoryName(def.Repository),
License: def.License,
Notes: def.Attribution,
}
renderedCtorParams, typedCtorParams := mod.genConstructors(r, allOptionalInputs)
stateParam := name + "State"
creationExampleSyntax := map[string]string{}
if !r.IsProvider && err == nil {
if example, found := dctx.constructorSyntaxData.typescript.resources[r.Token]; found {
if strings.Contains(example, "notImplemented") || strings.Contains(example, "PANIC") {
example = ""
}
creationExampleSyntax["typescript"] = example
}
if example, found := dctx.constructorSyntaxData.python.resources[r.Token]; found {
if strings.Contains(example, "not_implemented") || strings.Contains(example, "PANIC") {
example = ""
}
creationExampleSyntax["python"] = example
}
if example, found := dctx.constructorSyntaxData.csharp.resources[r.Token]; found {
if strings.Contains(example, "NotImplemented") || strings.Contains(example, "PANIC") {
example = ""
}
creationExampleSyntax["csharp"] = example
}
if example, found := dctx.constructorSyntaxData.golang.resources[r.Token]; found {
modified := strings.ReplaceAll(example, "_, err =", "example, err :=")
modified = strings.ReplaceAll(modified, "_, err :=", "example, err :=")
if strings.Contains(modified, "notImplemented") || strings.Contains(modified, "PANIC") {
modified = ""
}
creationExampleSyntax["go"] = modified
}
if example, found := dctx.constructorSyntaxData.java.resources[r.Token]; found {
creationExampleSyntax["java"] = example
}
if example, found := dctx.constructorSyntaxData.yaml.resources[collapseYAMLToken(r.Token)]; found {
creationExampleSyntax["yaml"] = example
}
}
Resource docs: emit supporting types beyond the 200 limit (#16185) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Originally motivated by uncontrolled pseudo-recurcive type expansion in AWS WafV2, we've limited the number of types that we should in the docs to 200: https://github.com/pulumi/pulumi/pull/12070 Our large customer that publishes their own packages and docs came back to us and said they have legitimate use cases with more than 200 types: #15507 I've grabbed stats about our current packages and still found a few offenders: ``` "aws:lex/v2modelsIntent:V2modelsIntent" 920 "aws:wafv2/ruleGroup:RuleGroup" 310 "aws:wafv2/webAcl:WebAcl" 523 "azure-native:datafactory:Dataset" 256 "azure-native:datafactory:LinkedService" 299 "azure-native:datafactory:Pipeline" 618 "azure-native:datamigration:ServiceTask" 291 "azure-native:datamigration:Task" 291 "aws-native:quicksight:Analysis" 589 "aws-native:quicksight:Dashboard" 606 "aws-native:quicksight:Template" 590 ``` Therefore, I'm not entirely removing the limit in this PR, but a) bumping the default to 1000 b) applying 200 to the known offenders only I don't love it's hard coded, but I haven't found a place to add simple configuration nob. Anyway, it's slightly less hard-coded than it used to be. Fixes #15507 ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [x] I have added tests that prove my fix is effective or that my feature works - Existing docs gen tests cover that I haven't broken anything - I re-generated the AWS docs and they had no changes <!--- User-facing changes require a CHANGELOG entry. --> - [x] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2024-05-13 14:58:33 +00:00
// Set a cap on how many auxiliary types the docs will include. We do that to limit the maximum size of
// a doc page. The default limit is rather high - we tried setting it to 200 for everyone but got
// pushback from third-party consumers who have legitimate use cases with more that 200 types.
// Therefore, we currently apply a smaller limit of 200 to packages that we know have some bloat in
// their types (AWS and AWS Native).
// See https://github.com/pulumi/pulumi/issues/15507#issuecomment-2064361317
//
// Schema Tools will print a warning every time a new resources gets an increase in number of types
// that is beyond 200. This should help us catch new instances and make decisions whether to include all
// types or add a limit. The default is including all types up to 1000.
maxNestedTypes := 1000
switch mod.pkg.Name() {
case "aws", "aws-native":
maxNestedTypes = 200
}
Add ability to constrain supported languages of resource and function overlays (#16579) The existing overlays (e.g. Chart v3 in Kubernetes, or CallbackFunction in AWS) are not available in every language Pulumi supports. This often confuses users because the generated docs include all languages Pulumi supports (e.g. see https://github.com/pulumi/pulumi-kubernetes/issues/2181). To solve that problem, this change adds a new optional parameter to the schema that allows configuring the languages an overlay (resource or function) supports. To support this in docsgen the existing Language Chooser (`LangChooserLanguages`) of resources is made configurable and extended to functions. Note: This doesn't support resource methods right now. They'll need extra handling because and overlay resource method might not support all of the languages its resource supports. I'll tackle this in a follow up PR. Here's a screenshot of how this will look like for the Helm v3 chart for example: <img width="1046" alt="Screenshot 2024-07-01 at 16 11 23" src="https://github.com/pulumi/pulumi/assets/2453580/b1a1365a-6dee-4099-829a-2859639a4c8c"> The PR contains the following commits. I'd recommend to look at the first three ones and then check the regenerated golden files in the last one: - **Add schema parameter to constrain supported languages for overlays** - **Update developer docs and changelog** - **Refactor LanguageChooser and always pass supported languages** - **Regenerate testdata** relates to #13231
2024-07-09 14:54:50 +00:00
supportedSnippetLanguages := mod.docGenContext.getSupportedSnippetLanguages(r.IsOverlay, r.OverlaySupportedLanguages)
docInfo := dctx.decomposeDocstring(r.Comment, supportedSnippetLanguages)
data := resourceDocArgs{
Header: mod.genResourceHeader(r),
Tool: mod.tool,
Add ability to constrain supported languages of resource and function overlays (#16579) The existing overlays (e.g. Chart v3 in Kubernetes, or CallbackFunction in AWS) are not available in every language Pulumi supports. This often confuses users because the generated docs include all languages Pulumi supports (e.g. see https://github.com/pulumi/pulumi-kubernetes/issues/2181). To solve that problem, this change adds a new optional parameter to the schema that allows configuring the languages an overlay (resource or function) supports. To support this in docsgen the existing Language Chooser (`LangChooserLanguages`) of resources is made configurable and extended to functions. Note: This doesn't support resource methods right now. They'll need extra handling because and overlay resource method might not support all of the languages its resource supports. I'll tackle this in a follow up PR. Here's a screenshot of how this will look like for the Helm v3 chart for example: <img width="1046" alt="Screenshot 2024-07-01 at 16 11 23" src="https://github.com/pulumi/pulumi/assets/2453580/b1a1365a-6dee-4099-829a-2859639a4c8c"> The PR contains the following commits. I'd recommend to look at the first three ones and then check the regenerated golden files in the last one: - **Add schema parameter to constrain supported languages for overlays** - **Update developer docs and changelog** - **Refactor LanguageChooser and always pass supported languages** - **Regenerate testdata** relates to #13231
2024-07-09 14:54:50 +00:00
Comment: docInfo.description,
DeprecationMessage: r.DeprecationMessage,
ExamplesSection: examplesSection{
Examples: docInfo.examples,
LangChooserLanguages: supportedSnippetLanguages,
},
ImportDocs: docInfo.importDetails,
CreationExampleSyntax: creationExampleSyntax,
ConstructorParams: renderedCtorParams,
ConstructorParamsTyped: typedCtorParams,
2022-04-21 11:23:36 +00:00
ConstructorResource: mod.getConstructorResourceInfo(name, r.Token),
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
ArgsRequired: !allOptionalInputs,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
InputProperties: inputProps,
OutputProperties: outputProps,
LookupParams: mod.genLookupParams(r, stateParam),
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
StateInputs: stateInputs,
StateParam: stateParam,
NestedTypes: mod.genNestedTypes(r, true /*resourceType*/),
Resource docs: emit supporting types beyond the 200 limit (#16185) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Originally motivated by uncontrolled pseudo-recurcive type expansion in AWS WafV2, we've limited the number of types that we should in the docs to 200: https://github.com/pulumi/pulumi/pull/12070 Our large customer that publishes their own packages and docs came back to us and said they have legitimate use cases with more than 200 types: #15507 I've grabbed stats about our current packages and still found a few offenders: ``` "aws:lex/v2modelsIntent:V2modelsIntent" 920 "aws:wafv2/ruleGroup:RuleGroup" 310 "aws:wafv2/webAcl:WebAcl" 523 "azure-native:datafactory:Dataset" 256 "azure-native:datafactory:LinkedService" 299 "azure-native:datafactory:Pipeline" 618 "azure-native:datamigration:ServiceTask" 291 "azure-native:datamigration:Task" 291 "aws-native:quicksight:Analysis" 589 "aws-native:quicksight:Dashboard" 606 "aws-native:quicksight:Template" 590 ``` Therefore, I'm not entirely removing the limit in this PR, but a) bumping the default to 1000 b) applying 200 to the known offenders only I don't love it's hard coded, but I haven't found a place to add simple configuration nob. Anyway, it's slightly less hard-coded than it used to be. Fixes #15507 ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [x] I have added tests that prove my fix is effective or that my feature works - Existing docs gen tests cover that I haven't broken anything - I re-generated the AWS docs and they had no changes <!--- User-facing changes require a CHANGELOG entry. --> - [x] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2024-05-13 14:58:33 +00:00
MaxNestedTypes: maxNestedTypes,
Methods: mod.genMethods(r),
Add ability to constrain supported languages of resource and function overlays (#16579) The existing overlays (e.g. Chart v3 in Kubernetes, or CallbackFunction in AWS) are not available in every language Pulumi supports. This often confuses users because the generated docs include all languages Pulumi supports (e.g. see https://github.com/pulumi/pulumi-kubernetes/issues/2181). To solve that problem, this change adds a new optional parameter to the schema that allows configuring the languages an overlay (resource or function) supports. To support this in docsgen the existing Language Chooser (`LangChooserLanguages`) of resources is made configurable and extended to functions. Note: This doesn't support resource methods right now. They'll need extra handling because and overlay resource method might not support all of the languages its resource supports. I'll tackle this in a follow up PR. Here's a screenshot of how this will look like for the Helm v3 chart for example: <img width="1046" alt="Screenshot 2024-07-01 at 16 11 23" src="https://github.com/pulumi/pulumi/assets/2453580/b1a1365a-6dee-4099-829a-2859639a4c8c"> The PR contains the following commits. I'd recommend to look at the first three ones and then check the regenerated golden files in the last one: - **Add schema parameter to constrain supported languages for overlays** - **Update developer docs and changelog** - **Refactor LanguageChooser and always pass supported languages** - **Regenerate testdata** relates to #13231
2024-07-09 14:54:50 +00:00
PackageDetails: packageDetails,
LangChooserLanguages: supportedSnippetLanguages,
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
}
Update schema-based docs generator (#4035) * Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables. * Generate the constructor dynamically from the resource per language. * Add doc functions in each language generator package for getting doc links for types..and later other functions too. * Render the constructor params in the Go code and inject into the template. * Generate nodejs types using the nodejs lang generator. * Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator. * Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names. * Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator. * Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type. * Fix bug with C# property type html encoding. * Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it. * Do not generate the examples section if there are none. * Generating the property types per language. * Formatting. Rename function for readability. * Add comments. Update README. * Use relative URLs for doc links within the main site
2020-03-09 17:35:20 +00:00
return data
}
func (mod *modContext) getNestedTypes(t schema.Type, types nestedTypeUsageInfo, input bool) {
switch t := t.(type) {
case *schema.InputType:
mod.getNestedTypes(t.ElementType, types, input)
case *schema.OptionalType:
mod.getNestedTypes(t.ElementType, types, input)
case *schema.ArrayType:
mod.getNestedTypes(t.ElementType, types, input)
case *schema.MapType:
mod.getNestedTypes(t.ElementType, types, input)
case *schema.ObjectType:
if types.contains(t.Token, input) {
break
}
types.add(t.Token, input)
for _, p := range t.Properties {
mod.getNestedTypes(p.Type, types, input)
}
case *schema.EnumType:
types.add(t.Token, false)
case *schema.UnionType:
for _, e := range t.ElementTypes {
mod.getNestedTypes(e, types, input)
}
}
}
func (mod *modContext) getTypes(member interface{}, types nestedTypeUsageInfo) {
glog.V(3).Infoln("getting nested types for module", mod.mod)
switch t := member.(type) {
case *schema.ObjectType:
for _, p := range t.Properties {
mod.getNestedTypes(p.Type, types, false)
}
case *schema.Resource:
for _, p := range t.Properties {
mod.getNestedTypes(p.Type, types, false)
}
for _, p := range t.InputProperties {
mod.getNestedTypes(p.Type, types, true)
}
for _, m := range t.Methods {
mod.getTypes(m.Function, types)
}
case *schema.Function:
if t.Inputs != nil && !t.MultiArgumentInputs {
mod.getNestedTypes(t.Inputs, types, true)
}
if t.ReturnType != nil {
if objectType, ok := t.ReturnType.(*schema.ObjectType); ok && objectType != nil {
mod.getNestedTypes(objectType, types, false)
}
}
}
}
// getModuleFileName returns the file name to use for a module.
func (mod *modContext) getModuleFileName() string {
dctx := mod.docGenContext
if !isKubernetesPackage(mod.pkg) {
return mod.mod
}
// For k8s packages, use the Go-language info to get the file name
// for the module.
if override, ok := dctx.goPkgInfo.ModuleToPackage[mod.mod]; ok {
return override
}
return mod.mod
}
// moduleConflictResolver holds module-level information for resolving naming conflicts.
// It shares information with the top-level docGenContext
// to ensure the same name is used across modules that reference each other.
type moduleConflictResolver struct {
dctx *docGenContext
seen map[string]struct{}
}
func (dctx *docGenContext) newModuleConflictResolver() moduleConflictResolver {
return moduleConflictResolver{
dctx: dctx,
seen: map[string]struct{}{},
}
}
// getSafeName returns a documentation name for an item
// that is unique within the module.
//
// if the item has already been resolved by any module,
// the previously-resolved name is returned.
func (r *moduleConflictResolver) getSafeName(name string, item interface{}) string {
if safeName, ok := r.dctx.moduleConflictLinkMap[item]; ok {
return safeName
}
var prefixes []string
switch item.(type) {
case *schema.Resource:
prefixes = []string{"", "res-"}
case *schema.Function:
prefixes = []string{"", "fn-"}
case *modContext:
prefixes = []string{"", "mod-"}
default:
prefixes = []string{""}
}
for _, prefix := range prefixes {
candidate := prefix + name
if _, exists := r.seen[candidate]; exists {
continue
}
r.seen[candidate] = struct{}{}
r.dctx.moduleConflictLinkMap[item] = candidate
return candidate
}
glog.Error("skipping unresolvable duplicate file name: ", name)
return ""
}
func (mod *modContext) gen(fs codegen.Fs) error {
glog.V(4).Infoln("genIndex for", mod.mod)
modName := mod.getModuleFileName()
conflictResolver := mod.docGenContext.newModuleConflictResolver()
2022-12-12 14:55:35 +00:00
def, err := mod.pkg.Definition()
contract.AssertNoErrorf(err, "failed to get definition for package %q", mod.pkg.Name())
2022-12-12 14:55:35 +00:00
modTitle := modName
if modTitle == "" {
// An empty string indicates that this is the root module.
2022-12-12 14:55:35 +00:00
if def.DisplayName != "" {
modTitle = def.DisplayName
} else {
modTitle = getPackageDisplayName(mod.pkg.Name())
}
}
// addFileTemplated executes template tmpl with data,
// and adds a file $dirName/_index.md with the result.
addFileTemplated := func(dirName, tmpl string, data interface{}) error {
var buff bytes.Buffer
if err := mod.docGenContext.templates.ExecuteTemplate(&buff, tmpl, data); err != nil {
return err
}
p := path.Join(modName, dirName, "_index.md")
fs.Add(p, buff.Bytes())
return nil
}
// If there are submodules, list them.
modules := slice.Prealloc[indexEntry](len(mod.children))
for _, mod := range mod.children {
modName := mod.getModuleFileName()
displayName := modFilenameToDisplayName(modName)
safeName := conflictResolver.getSafeName(displayName, mod)
if safeName == "" {
continue // unresolved conflict
}
modules = append(modules, indexEntry{
Link: getModuleLink(safeName),
DisplayName: displayName,
})
}
sortIndexEntries(modules)
// If there are resources in the root, list them.
resources := slice.Prealloc[indexEntry](len(mod.resources))
for _, r := range mod.resources {
title := resourceName(r)
link := getResourceLink(title)
link = conflictResolver.getSafeName(link, r)
if link == "" {
continue // unresolved conflict
}
data := mod.genResource(r)
if err := addFileTemplated(link, "resource.tmpl", data); err != nil {
return err
}
resources = append(resources, indexEntry{
Link: link + "/",
DisplayName: title,
})
}
sortIndexEntries(resources)
// If there are functions in the root, list them.
functions := slice.Prealloc[indexEntry](len(mod.functions))
for _, f := range mod.functions {
name := tokenToName(f.Token)
link := getFunctionLink(name)
link = conflictResolver.getSafeName(link, f)
if link == "" {
continue // unresolved conflict
}
data := mod.genFunction(f)
if err := addFileTemplated(link, "function.tmpl", data); err != nil {
return err
}
functions = append(functions, indexEntry{
Link: link + "/",
DisplayName: strings.Title(name),
})
}
sortIndexEntries(functions)
version := ""
2022-12-12 14:55:35 +00:00
if mod.pkg.Version() != nil {
version = mod.pkg.Version().String()
}
packageDetails := packageDetails{
DisplayName: getPackageDisplayName(def.Name),
Repository: def.Repository,
RepositoryName: getRepositoryName(def.Repository),
License: def.License,
Notes: def.Attribution,
Version: version,
}
var modTitleTag string
var packageDescription string
// The same index.tmpl template is used for both top level package and module pages, if modules not present,
// assume top level package index page when formatting title tags otherwise, if contains modules, assume modules
// top level page when generating title tags.
if len(modules) > 0 {
Enable perfsprint linter (#14813) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description <!--- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. --> Prompted by a comment in another review: https://github.com/pulumi/pulumi/pull/14654#discussion_r1419995945 This lints that we don't use `fmt.Errorf` when `errors.New` will suffice, it also covers a load of other cases where `Sprintf` is sub-optimal. Most of these edits were made by running `perfsprint --fix`. ## Checklist - [x] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2023-12-12 12:19:42 +00:00
modTitleTag = getPackageDisplayName(modTitle) + " Package"
} else {
modTitleTag = fmt.Sprintf("%s.%s", mod.pkg.Name(), modTitle)
2022-12-12 14:55:35 +00:00
packageDescription = fmt.Sprintf("Explore the resources and functions of the %s.%s module.",
mod.pkg.Name(), modTitle)
}
// Generate the index file.
idxData := indexData{
Tool: mod.tool,
PackageDescription: packageDescription,
Title: modTitle,
TitleTag: modTitleTag,
Resources: resources,
Functions: functions,
Modules: modules,
PackageDetails: packageDetails,
}
// If this is the root module, write out the package description.
if mod.mod == "" {
idxData.PackageDescription = mod.pkg.Description()
}
return addFileTemplated("", "index.tmpl", idxData)
}
// indexEntry represents an individual entry on an index page.
type indexEntry struct {
Link string
DisplayName string
}
// indexData represents the index file data to be rendered as _index.md.
type indexData struct {
Tool string
Title string
TitleTag string
PackageDescription string
Functions []indexEntry
Resources []indexEntry
Modules []indexEntry
PackageDetails packageDetails
}
func sortIndexEntries(entries []indexEntry) {
if len(entries) == 0 {
return
}
sort.Slice(entries, func(i, j int) bool {
return entries[i].DisplayName < entries[j].DisplayName
})
}
// getPackageDisplayName uses the title lookup map to look for a
// display name for the given title.
func getPackageDisplayName(title string) string {
// If title not found in titleLookup map, default back to title given.
if val, ok := titleLookup(title); ok {
return val
}
return title
}
// getRepositoryName returns the repository name based on the repository's URL.
func getRepositoryName(repoURL string) string {
return strings.TrimPrefix(repoURL, "https://github.com/")
}
func (dctx *docGenContext) getMod(
2022-12-12 14:55:35 +00:00
pkg schema.PackageReference,
token string,
2022-12-12 14:55:35 +00:00
tokenPkg schema.PackageReference,
modules map[string]*modContext,
tool string,
all: Reformat with gofumpt Per team discussion, switching to gofumpt. [gofumpt][1] is an alternative, stricter alternative to gofmt. It addresses other stylistic concerns that gofmt doesn't yet cover. [1]: https://github.com/mvdan/gofumpt See the full list of [Added rules][2], but it includes: - Dropping empty lines around function bodies - Dropping unnecessary variable grouping when there's only one variable - Ensuring an empty line between multi-line functions - simplification (`-s` in gofmt) is always enabled - Ensuring multi-line function signatures end with `) {` on a separate line. [2]: https://github.com/mvdan/gofumpt#Added-rules gofumpt is stricter, but there's no lock-in. All gofumpt output is valid gofmt output, so if we decide we don't like it, it's easy to switch back without any code changes. gofumpt support is built into the tooling we use for development so this won't change development workflows. - golangci-lint includes a gofumpt check (enabled in this PR) - gopls, the LSP for Go, includes a gofumpt option (see [installation instrutions][3]) [3]: https://github.com/mvdan/gofumpt#installation This change was generated by running: ```bash gofumpt -w $(rg --files -g '*.go' | rg -v testdata | rg -v compilation_error) ``` The following files were manually tweaked afterwards: - pkg/cmd/pulumi/stack_change_secrets_provider.go: one of the lines overflowed and had comments in an inconvenient place - pkg/cmd/pulumi/destroy.go: `var x T = y` where `T` wasn't necessary - pkg/cmd/pulumi/policy_new.go: long line because of error message - pkg/backend/snapshot_test.go: long line trying to assign three variables in the same assignment I have included mention of gofumpt in the CONTRIBUTING.md.
2023-03-03 16:36:39 +00:00
add bool,
) *modContext {
modName := pkg.TokenToModule(token)
Fix docs generator parent module computation (#15035) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Fixes #14820 Fixes #14821 Fixes a bug in docs generator parent module computation that used to lead to duplicate files panics and undesirable documentation URL layout for affected providers such as [pulumi/fortios](https://github.com/pulumiverse/pulumi-fortios/issues). Joint work with @tmeckel . ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [ ] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. --> --------- Co-authored-by: Thomas Meckel <tmeckel@users.noreply.github.com>
2024-02-20 15:44:37 +00:00
return dctx.getModByModName(pkg, tokens.ModuleName(modName), tokenPkg, modules, tool, add)
}
func (dctx *docGenContext) getModByModName(
pkg schema.PackageReference,
modName tokens.ModuleName,
tokenPkg schema.PackageReference,
modules map[string]*modContext,
tool string,
add bool,
) *modContext {
mod, ok := modules[string(modName)]
if !ok {
mod = &modContext{
pkg: pkg,
Fix docs generator parent module computation (#15035) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Fixes #14820 Fixes #14821 Fixes a bug in docs generator parent module computation that used to lead to duplicate files panics and undesirable documentation URL layout for affected providers such as [pulumi/fortios](https://github.com/pulumiverse/pulumi-fortios/issues). Joint work with @tmeckel . ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [ ] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. --> --------- Co-authored-by: Thomas Meckel <tmeckel@users.noreply.github.com>
2024-02-20 15:44:37 +00:00
mod: string(modName),
tool: tool,
docGenContext: dctx,
}
2022-12-12 14:55:35 +00:00
if modName != "" && codegen.PkgEquals(tokenPkg, pkg) {
Fix docs generator parent module computation (#15035) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Fixes #14820 Fixes #14821 Fixes a bug in docs generator parent module computation that used to lead to duplicate files panics and undesirable documentation URL layout for affected providers such as [pulumi/fortios](https://github.com/pulumiverse/pulumi-fortios/issues). Joint work with @tmeckel . ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [ ] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. --> --------- Co-authored-by: Thomas Meckel <tmeckel@users.noreply.github.com>
2024-02-20 15:44:37 +00:00
parentName, hasParent := parentModule(modName)
if add && hasParent {
parent := dctx.getModByModName(pkg, parentName, tokenPkg, modules, tool, add)
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
parent.children = append(parent.children, mod)
}
}
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
// Save the module only if we're adding and it's for the current package.
// This way, modules for external packages are not saved.
if add && tokenPkg == pkg {
Fix docs generator parent module computation (#15035) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Fixes #14820 Fixes #14821 Fixes a bug in docs generator parent module computation that used to lead to duplicate files panics and undesirable documentation URL layout for affected providers such as [pulumi/fortios](https://github.com/pulumiverse/pulumi-fortios/issues). Joint work with @tmeckel . ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [ ] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. --> --------- Co-authored-by: Thomas Meckel <tmeckel@users.noreply.github.com>
2024-02-20 15:44:37 +00:00
modules[string(modName)] = mod
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
}
}
return mod
}
func (dctx *docGenContext) generateModulesFromSchemaPackage(tool string, pkg *schema.Package) map[string]*modContext {
// Group resources, types, and functions into modules.
modules := map[string]*modContext{}
// Decode language-specific info.
if err := pkg.ImportLanguages(map[string]schema.Language{
"go": go_gen.Importer,
"python": python.Importer,
"csharp": dotnet.Importer,
"nodejs": nodejs.Importer,
}); err != nil {
panic(err)
}
dctx.goPkgInfo, _ = pkg.Language["go"].(go_gen.GoPackageInfo)
dctx.csharpPkgInfo, _ = pkg.Language["csharp"].(dotnet.CSharpPackageInfo)
dctx.nodePkgInfo, _ = pkg.Language["nodejs"].(nodejs.NodePackageInfo)
dctx.pythonPkgInfo, _ = pkg.Language["python"].(python.PackageInfo)
goLangHelper := dctx.getLanguageDocHelper("go").(*go_gen.DocLanguageHelper)
// Generate the Go package map info now, so we can use that to get the type string
// names later.
goLangHelper.GeneratePackagesMap(pkg, tool, dctx.goPkgInfo)
csharpLangHelper := dctx.getLanguageDocHelper("csharp").(*dotnet.DocLanguageHelper)
csharpLangHelper.Namespaces = dctx.csharpPkgInfo.Namespaces
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
visitObjects := func(r *schema.Resource) {
visitObjectTypes(r.InputProperties, func(t schema.Type) {
switch T := t.(type) {
case *schema.ObjectType:
2022-12-12 14:55:35 +00:00
dctx.getMod(pkg.Reference(), T.Token, T.PackageReference, modules, tool, true).details(T).inputType = true
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
}
})
if r.StateInputs != nil {
visitObjectTypes(r.StateInputs.Properties, func(t schema.Type) {
switch T := t.(type) {
case *schema.ObjectType:
2022-12-12 14:55:35 +00:00
dctx.getMod(pkg.Reference(), T.Token, T.PackageReference, modules, tool, true).details(T).inputType = true
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
}
})
}
}
scanResource := func(r *schema.Resource) {
2022-12-12 14:55:35 +00:00
mod := dctx.getMod(pkg.Reference(), r.Token, r.PackageReference, modules, tool, true)
mod.resources = append(mod.resources, r)
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
visitObjects(r)
}
scanK8SResource := func(r *schema.Resource) {
mod := getKubernetesMod(pkg, r.Token, modules, tool)
mod.resources = append(mod.resources, r)
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
visitObjects(r)
}
glog.V(3).Infoln("scanning resources")
2022-12-12 14:55:35 +00:00
if isKubernetesPackage(pkg.Reference()) {
scanK8SResource(pkg.Provider)
for _, r := range pkg.Resources {
scanK8SResource(r)
}
} else {
scanResource(pkg.Provider)
for _, r := range pkg.Resources {
scanResource(r)
}
}
glog.V(3).Infoln("done scanning resources")
for _, f := range pkg.Functions {
if !f.IsMethod {
2022-12-12 14:55:35 +00:00
mod := dctx.getMod(pkg.Reference(), f.Token, f.PackageReference, modules, tool, true)
mod.functions = append(mod.functions, f)
}
}
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
// Find nested types.
for _, t := range pkg.Types {
switch typ := t.(type) {
case *schema.ObjectType:
2022-12-12 14:55:35 +00:00
mod := dctx.getMod(pkg.Reference(), typ.Token, typ.PackageReference, modules, tool, false)
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
if mod.details(typ).inputType {
mod.inputTypes = append(mod.inputTypes, typ)
}
}
}
return modules
}
// generateModules generates constructor syntax examples for all resources of the input the package in the given
// input languages. We first generate a PCL program from the resource definitions, then for each language
// we call `GenerateProgram` to generate a language program that has all resources with their inputs being default
// values. After that, we extract the resource declarations from each program into a structured map.
//
// The reason we generate a full program a schema with all the resources is that if we did every resource separately,
// it would take too long to generate the programs and the rest of the docs. That is why we batch generate them and
// split the resource declarations by comment delimiters.
func generateConstructorSyntaxData(pkg *schema.Package, languages []string) *constructorSyntaxData {
loader := NewStaticSchemaLoader(pkg)
constructorGenerator := &constructorSyntaxGenerator{
indentSize: 0,
requiredPropertiesOnly: false,
}
schemaProgram := constructorGenerator.generateAll(pkg, generateAllOptions{
includeResources: true,
includeFunctions: false,
resourcesToSkip: []string{
// Skipping problematic resources which block example generation
"aws:wafv2/ruleGroup:RuleGroup",
"aws:wafv2/webAcl:WebAcl",
},
})
packagesToSkip := map[string]codegen.StringSet{
[docs] Implement Java constructor syntax examples (#15805) # Description This PR implements Java constructor syntax examples, rendering them into the docs. It upgrades pulumi-java to 0.10.0 which includes features from https://github.com/pulumi/pulumi-java/pull/1338 It also updates contructor syntax generator to emit an unbound variable for resource-typed properties. We use the name of the resource as the name of the variable: ```typescript const example = new Resource("name", { pet: randomPet }) ```` where `pet` is a property that is typed as `random.RandomPet` so it gets assigned the (unbound) variable called `randomPet` Previously we would skip emitting any code for resource-typed properties. I think this gives better docs even though it doesn't compile ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [x] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [x] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2024-03-28 00:03:58 +00:00
"aws-native": codegen.NewStringSet("python", "typescript", "go", "csharp", "yaml", "java"),
}
type ProgramGenerator = func(program *pcl.Program) (files map[string][]byte, diags hcl.Diagnostics, err error)
constructorSyntax := newConstructorSyntaxData()
for _, lang := range languages {
if skippedLanguages, ok := packagesToSkip[pkg.Name]; ok && skippedLanguages.Has(lang) {
continue
}
boundProgram, err := constructorGenerator.bindProgram(loader, schemaProgram)
if err != nil {
continue
}
safeExtract := func(generator ProgramGenerator) (files map[string][]byte, diags hcl.Diagnostics, err error) {
defer func() {
if r := recover(); r != nil {
err = fmt.Errorf("panic: %v", r)
files = map[string][]byte{}
}
}()
return generator(boundProgram)
}
switch lang {
case "nodejs":
files, diags, err := safeExtract(nodejs.GenerateProgram)
if !diags.HasErrors() && err == nil {
program := string(files["index.ts"])
constructorSyntax.typescript = extractConstructorSyntaxExamples(
program, /* program */
"", /* indentation to trim */
"//", /* comment prefix */
func(line string) bool { return strings.HasSuffix(line, "});") })
}
case "python":
files, diags, err := safeExtract(python.GenerateProgram)
if !diags.HasErrors() && err == nil {
program := string(files["__main__.py"])
constructorSyntax.python = extractConstructorSyntaxExamples(
program, /* program */
"", /* indentation to trim */
"#", /* comment prefix */
func(line string) bool { return strings.HasSuffix(line, ")") })
}
case "csharp":
files, diags, err := safeExtract(dotnet.GenerateProgram)
if !diags.HasErrors() && err == nil {
exampleEnd := func(line string) bool {
return strings.HasSuffix(line, "});") || strings.HasSuffix(line, `");`)
}
program := string(files["Program.cs"])
constructorSyntax.csharp = extractConstructorSyntaxExamples(
program, /* program */
" ", /* indentation to trim */
"//", /* comment prefix */
exampleEnd)
}
case "go":
files, diags, err := safeExtract(go_gen.GenerateProgram)
if !diags.HasErrors() && err == nil {
var program string
content := files["main.go"]
if formatted, err := format.Source(content); err == nil {
program = string(formatted)
} else {
program = string(content)
}
constructorSyntax.golang = extractConstructorSyntaxExamples(
program, /* program */
"\t\t", /* indentation to trim */
"//", /* comment prefix */
func(line string) bool { return strings.HasSuffix(strings.TrimSpace(line), ")") })
}
case "yaml":
files, diags, err := safeExtract(yaml.GenerateProgram)
if !diags.HasErrors() && err == nil {
program := string(files["Main.yaml"])
constructorSyntax.yaml = extractConstructorSyntaxExamplesFromYAML(program)
}
case "java":
[docs] Implement Java constructor syntax examples (#15805) # Description This PR implements Java constructor syntax examples, rendering them into the docs. It upgrades pulumi-java to 0.10.0 which includes features from https://github.com/pulumi/pulumi-java/pull/1338 It also updates contructor syntax generator to emit an unbound variable for resource-typed properties. We use the name of the resource as the name of the variable: ```typescript const example = new Resource("name", { pet: randomPet }) ```` where `pet` is a property that is typed as `random.RandomPet` so it gets assigned the (unbound) variable called `randomPet` Previously we would skip emitting any code for resource-typed properties. I think this gives better docs even though it doesn't compile ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [x] I have run `make lint` to verify my code passes the lint check - [x] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [x] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [x] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
2024-03-28 00:03:58 +00:00
files, diags, err := safeExtract(java.GenerateProgram)
if !diags.HasErrors() && err == nil {
program := string(files["MyStack.java"])
constructorSyntax.java = extractConstructorSyntaxExamples(
program, /* program */
" ", /* indentation to trim */
"//", /* comment prefix */
func(line string) bool { return strings.HasSuffix(line, ");") })
}
}
}
return constructorSyntax
}
// collapseToken converts an exact token to a token more suitable for
// display. For example, it converts
//
// fizz:index/buzz:Buzz => fizz:Buzz
// fizz:mode/buzz:Buzz => fizz:mode:Buzz
// foo:index:Bar => foo:Bar
// foo::Bar => foo:Bar
// fizz:mod:buzz => fizz:mod:buzz
func collapseYAMLToken(token string) string {
tokenParts := strings.Split(token, ":")
if len(tokenParts) == 3 {
title := func(s string) string {
r := []rune(s)
if len(r) == 0 {
return ""
}
return strings.ToTitle(string(r[0])) + string(r[1:])
}
if mod := strings.Split(tokenParts[1], "/"); len(mod) == 2 && title(mod[1]) == tokenParts[2] {
// aws:s3/bucket:Bucket => aws:s3:Bucket
// We handle the case foo:index/bar:Bar => foo:index:Bar
tokenParts = []string{tokenParts[0], mod[0], tokenParts[2]}
}
if tokenParts[1] == "index" || tokenParts[1] == "" {
// foo:index:Bar => foo:Bar
// or
// foo::Bar => foo:Bar
tokenParts = []string{tokenParts[0], tokenParts[2]}
}
}
return strings.Join(tokenParts, ":")
}
func (dctx *docGenContext) initialize(tool string, pkg *schema.Package) {
dctx.templates = template.New("").Funcs(template.FuncMap{
"htmlSafe": func(html string) template.HTML {
// Markdown fragments in the templates need to be rendered as-is,
// so that html/template package doesn't try to inject data into it,
// which will most certainly fail.
//nolint:gosec
return template.HTML(html)
},
2022-04-29 22:04:15 +00:00
"markdownify": func(html string) template.HTML {
// Convert a string of Markdown into HTML.
var buf bytes.Buffer
if err := goldmark.Convert([]byte(html), &buf); err != nil {
glog.Fatalf("rendering Markdown: %v", err)
}
[docsgen] Fix rendering of deprecated messages and text in description lists (#13773) A change was made a while back to remove the use of shortcodes. As part of that, the shortcode used to render markdown was replaced by a function call that used goldmark to render markdown. The resulting HTML from that wraps the text in paragraph tags. This causes some problems for rendering the docs. For deprecations, the deprecation message now shows up outside of the "Deprecated" box. This happens because the rendered markdown was being wrapped in `<p></p>` tags, leading to `<p class="resource-deprecated">Deprecated: <p>message</p></p>`, which does not render correctly because paragraph tags cannot be nested. Also, in description lists, rendered markdown text was being wrapped in paragraph tags (e.g. `<dd><p>text</p></dd>`), causing it to render differently from text not wrapped in paragraph tags (e.g. `<dd>text</dd>`). This change addresses these issues. - First, `<div class="resource-deprecated">` is used rather than `<p>` to contain the deprecation information. - Second, the `markdownify` function will now trim unnecessary paragraph tags. Fixes https://github.com/pulumi/pulumi-hugo/issues/2832 Fixes https://github.com/pulumi/registry/issues/3008 --- ## Before <img width="713" alt="Screen Shot 2023-08-24 at 5 21 44 PM" src="https://github.com/pulumi/pulumi/assets/710598/1358cc74-dd8a-4bc0-bed8-603b1439b2aa"> ## After <img width="721" alt="Screen Shot 2023-08-24 at 5 21 58 PM" src="https://github.com/pulumi/pulumi/assets/710598/ad501e68-1bac-486c-a723-7db2b3442c8a"> ## Before <img width="719" alt="Screen Shot 2023-08-24 at 5 22 28 PM" src="https://github.com/pulumi/pulumi/assets/710598/6ca40b85-9008-429b-83c3-2f0d681752f3"> ## After <img width="714" alt="Screen Shot 2023-08-24 at 5 24 02 PM" src="https://github.com/pulumi/pulumi/assets/710598/eec1dacf-8c24-470e-b1e3-da843b4aeaee">
2023-08-26 17:36:28 +00:00
rendered := buf.String()
// Trim surrounding <p></p> tags.
result := strings.TrimSpace(rendered)
result = strings.TrimPrefix(result, "<p>")
result = strings.TrimSuffix(result, "</p>")
// If there are still <p> tags, there are multiple paragraphs,
// in which case use the original rendered string (untrimmed).
if strings.Contains(result, "<p>") {
result = rendered
}
//nolint:gosec
[docsgen] Fix rendering of deprecated messages and text in description lists (#13773) A change was made a while back to remove the use of shortcodes. As part of that, the shortcode used to render markdown was replaced by a function call that used goldmark to render markdown. The resulting HTML from that wraps the text in paragraph tags. This causes some problems for rendering the docs. For deprecations, the deprecation message now shows up outside of the "Deprecated" box. This happens because the rendered markdown was being wrapped in `<p></p>` tags, leading to `<p class="resource-deprecated">Deprecated: <p>message</p></p>`, which does not render correctly because paragraph tags cannot be nested. Also, in description lists, rendered markdown text was being wrapped in paragraph tags (e.g. `<dd><p>text</p></dd>`), causing it to render differently from text not wrapped in paragraph tags (e.g. `<dd>text</dd>`). This change addresses these issues. - First, `<div class="resource-deprecated">` is used rather than `<p>` to contain the deprecation information. - Second, the `markdownify` function will now trim unnecessary paragraph tags. Fixes https://github.com/pulumi/pulumi-hugo/issues/2832 Fixes https://github.com/pulumi/registry/issues/3008 --- ## Before <img width="713" alt="Screen Shot 2023-08-24 at 5 21 44 PM" src="https://github.com/pulumi/pulumi/assets/710598/1358cc74-dd8a-4bc0-bed8-603b1439b2aa"> ## After <img width="721" alt="Screen Shot 2023-08-24 at 5 21 58 PM" src="https://github.com/pulumi/pulumi/assets/710598/ad501e68-1bac-486c-a723-7db2b3442c8a"> ## Before <img width="719" alt="Screen Shot 2023-08-24 at 5 22 28 PM" src="https://github.com/pulumi/pulumi/assets/710598/6ca40b85-9008-429b-83c3-2f0d681752f3"> ## After <img width="714" alt="Screen Shot 2023-08-24 at 5 24 02 PM" src="https://github.com/pulumi/pulumi/assets/710598/eec1dacf-8c24-470e-b1e3-da843b4aeaee">
2023-08-26 17:36:28 +00:00
return template.HTML(result)
2022-04-29 22:04:15 +00:00
},
})
defer glog.Flush()
if _, err := dctx.templates.ParseFS(packagedTemplates, "templates/*.tmpl"); err != nil {
glog.Fatalf("initializing templates: %v", err)
}
dctx.constructorSyntaxData = generateConstructorSyntaxData(pkg, dctx.supportedLanguages)
// Generate the modules from the schema, and for every module
// run the generator functions to generate markdown files.
dctx.setModules(dctx.generateModulesFromSchemaPackage(tool, pkg))
}
func (dctx *docGenContext) generatePackage(tool string, pkg *schema.Package) (map[string][]byte, error) {
if dctx.modules() == nil {
return nil, errors.New("must call Initialize before generating the docs package")
}
defer glog.Flush()
glog.V(3).Infoln("generating package docs now...")
files := codegen.Fs{}
modules := []string{}
modMap := dctx.modules()
for k := range modMap {
modules = append(modules, k)
}
sort.Strings(modules)
for _, mod := range modules {
if err := modMap[mod].gen(files); err != nil {
return nil, err
}
}
return files, nil
}
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
Fix docs generator parent module computation (#15035) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Fixes #14820 Fixes #14821 Fixes a bug in docs generator parent module computation that used to lead to duplicate files panics and undesirable documentation URL layout for affected providers such as [pulumi/fortios](https://github.com/pulumiverse/pulumi-fortios/issues). Joint work with @tmeckel . ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [ ] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. --> --------- Co-authored-by: Thomas Meckel <tmeckel@users.noreply.github.com>
2024-02-20 15:44:37 +00:00
const (
// "" indicates the top-most module.
topMostModule tokens.ModuleName = ""
)
// GeneratePackageTree returns a navigable structure starting from the top-most module.
func (dctx *docGenContext) generatePackageTree() ([]PackageTreeItem, error) {
if dctx.modules() == nil {
return nil, errors.New("must call Initialize before generating the docs package")
}
defer glog.Flush()
var packageTree []PackageTreeItem
Fix docs generator parent module computation (#15035) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Fixes #14820 Fixes #14821 Fixes a bug in docs generator parent module computation that used to lead to duplicate files panics and undesirable documentation URL layout for affected providers such as [pulumi/fortios](https://github.com/pulumiverse/pulumi-fortios/issues). Joint work with @tmeckel . ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [ ] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. --> --------- Co-authored-by: Thomas Meckel <tmeckel@users.noreply.github.com>
2024-02-20 15:44:37 +00:00
if rootMod, ok := dctx.modules()[string(topMostModule)]; ok {
tree, err := generatePackageTree(*rootMod)
if err != nil {
glog.Errorf("Error generating the package tree for package: %v", err)
}
packageTree = tree
} else {
glog.Error("A root module entry was not found for the package. Cannot generate the package tree...")
}
return packageTree, nil
}
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
func visitObjectTypes(properties []*schema.Property, visitor func(t schema.Type)) {
codegen.VisitTypeClosure(properties, func(t schema.Type) {
switch st := t.(type) {
[codegen/python] Rename conflicting ResourceArgs classes (#7171) Python resource constructor overloads were recently added that accept a `<Resource>Args` class for input properties, as an alternative to the other constructor overload that accepts keyword arguments. The name of the new args class is the name of the resource concatenated with an `Args` suffix. Some providers (e.g. Kubernetes, Azure Native, and Google Native) have input types with the same name as resources in the same module, which results in two different `<Resource>Args` classes in the same module. When you try to use the new args class with the constructor, e.g.: ```python pulumi_kubernetes.storage.v1.StorageClass( resource_name='string', args=pulumi_kubernetes.storage.v1.StorageClassArgs(...), opts=pulumi.ResourceOptions(...), ) ``` You run into an error, because `pulumi_kubernetes.storage.v1.StorageClassArgs` is actually referring to the existing input type rather than the intended `StorageClassArgs` class for the constructor arguments. Having the duplicate classes hasn't broken existing usage of the input type because we "export" all the input types for a module _after_ all the resources and resource args classes are exported, so the input type just ends up "overwriting" the duplicate resource args class. Other languages don't have this problem because the input type is either in it's own module/namespace (e.g. Node.js and .NET) or a different name is used for the input type (Go). But with Python, the input types and resources are all available in the same module. To address this for Python, when there is an input type in the same module with the same name as the resource, the args class for the resource will be emitted as `<Resource>InitArgs` instead of `<Resource>Args`.
2021-06-10 17:41:49 +00:00
case *schema.EnumType, *schema.ObjectType, *schema.ResourceType:
visitor(st)
}
})
}
// Export a default static context so as not to break external
// consumers of this API; prefer *WithContext API internally to ensure
// tests can run in parallel.
var defaultContext = newDocGenContext()
func Initialize(tool string, pkg *schema.Package) {
defaultContext.initialize(tool, pkg)
}
// GeneratePackage generates docs for each resource given the Pulumi
// schema. The returned map contains the filename with path as the key
// and the contents as its value.
func GeneratePackage(tool string, pkg *schema.Package) (map[string][]byte, error) {
return defaultContext.generatePackage(tool, pkg)
}
// GeneratePackageTree returns a navigable structure starting from the top-most module.
func GeneratePackageTree() ([]PackageTreeItem, error) {
return defaultContext.generatePackageTree()
}
Fix docs generator parent module computation (#15035) <!--- Thanks so much for your contribution! If this is your first time contributing, please ensure that you have read the [CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) documentation. --> # Description Fixes #14820 Fixes #14821 Fixes a bug in docs generator parent module computation that used to lead to duplicate files panics and undesirable documentation URL layout for affected providers such as [pulumi/fortios](https://github.com/pulumiverse/pulumi-fortios/issues). Joint work with @tmeckel . ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [ ] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @Pulumi employees: If yes, you must submit corresponding changes in the service repo. --> --------- Co-authored-by: Thomas Meckel <tmeckel@users.noreply.github.com>
2024-02-20 15:44:37 +00:00
// Returns the parent module, if available. For top-level modules the parent is a special
// topMostModule. For topMostModule itself there is no parent and this function returns false.
func parentModule(modName tokens.ModuleName) (tokens.ModuleName, bool) {
switch {
case modName == topMostModule:
return "", false
case strings.Contains(string(modName), tokens.QNameDelimiter):
return tokens.ModuleName(tokens.QName(modName).Namespace()), true
default:
return topMostModule, true
}
}