pulumi/pkg/codegen/docs/utils.go

136 lines
4.1 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
// 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
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
package docs
import (
"strings"
"unicode"
"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/schema"
"github.com/pulumi/pulumi/sdk/v3/go/common/slice"
"github.com/pulumi/pulumi/sdk/v3/go/common/util/contract"
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 isDotNetTypeNameBoundary(prev rune, next rune) bool {
// For C# type names, which are PascalCase are qualified using "." as the separator.
return prev == rune('.') && unicode.IsUpper(next)
}
func isPythonTypeNameBoundary(prev rune, next rune) bool {
// For Python, names are snake_cased (Duh?).
return (prev == rune('_') && unicode.IsLower(next))
}
// wbr inserts HTML <wbr> in between case changes, e.g. "fooBar" becomes "foo<wbr>Bar".
func wbr(s string) string {
runes := slice.Prealloc[rune](len(s))
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 prev rune
for i, r := range s {
if i != 0 &&
// For TS, JS and Go, property names are camelCase and types are PascalCase.
((unicode.IsLower(prev) && unicode.IsUpper(r)) ||
isDotNetTypeNameBoundary(prev, r) ||
isPythonTypeNameBoundary(prev, r)) {
runes = append(runes, []rune("<wbr>")...)
}
runes = append(runes, r)
prev = r
}
return string(runes)
}
// tokenToName returns the resource name from a Pulumi token.
func tokenToName(tok string) string {
components := strings.Split(tok, ":")
contract.Assertf(len(components) == 3, "malformed token %v", tok)
return components[2]
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 tokenToPackageName(tok string) string {
components := strings.Split(tok, ":")
contract.Assertf(len(components) == 3, "malformed token %v", tok)
return components[0]
}
func title(s, lang string) string {
switch lang {
case "go":
return go_gen.Title(s)
case "csharp":
return dotnet.Title(s)
default:
return strings.Title(s)
}
}
func modFilenameToDisplayName(name string) string {
parts := strings.Split(name, "/")
return parts[len(parts)-1]
}
func getModuleLink(name string) string {
return strings.ToLower(name) + "/"
}
func getResourceLink(name string) string {
2023-01-18 20:23:08 +00:00
link := strings.ToLower(name)
// Handle URL generation for resources named `index`. We prepend a double underscore
// here, since a link of .../<module>/index has trouble resolving and returns a 404 in
// the browser, likely due to `index` being some sort of reserved keyword.
if link == "index" {
2023-01-20 20:53:34 +00:00
return "--" + link
2023-01-18 20:23:08 +00:00
}
return link
}
func getFunctionLink(name string) string {
return strings.ToLower(name)
}
// isExternalType checks if the type is external to the given package.
func isExternalType(t schema.Type, pkg schema.PackageReference) (isExternal bool) {
switch typ := t.(type) {
case *schema.ObjectType:
return typ.PackageReference != nil && !codegen.PkgEquals(typ.PackageReference, pkg)
case *schema.ResourceType:
return typ.Resource != nil && pkg != nil && !codegen.PkgEquals(typ.Resource.PackageReference, pkg)
case *schema.EnumType:
return pkg != nil && !codegen.PkgEquals(typ.PackageReference, pkg)
}
return
}
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
// Iterate character by character and remove underscores if that underscore
// is at the very front of an identifier, follows a special character, and is not a delimeter
// within an identifier.
func removeLeadingUnderscores(s string) string {
var sb strings.Builder
lastChar := ' '
for _, ch := range s {
if ch != '_' || (unicode.IsLetter(lastChar)) {
sb.WriteRune(ch)
}
lastChar = ch
}
return sb.String()
}