pulumi/pkg/codegen/docs/utils_test.go

61 lines
1.8 KiB
Go
Raw Normal View History

// 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 (
"testing"
"github.com/stretchr/testify/assert"
)
func TestWbr(t *testing.T) {
t.Parallel()
assert.Equal(t, wbr(""), "")
assert.Equal(t, wbr("a"), "a")
assert.Equal(t, wbr("A"), "A")
assert.Equal(t, wbr("aa"), "aa")
assert.Equal(t, wbr("AA"), "AA")
assert.Equal(t, wbr("Ab"), "Ab")
assert.Equal(t, wbr("aB"), "a<wbr>B")
assert.Equal(t, wbr("fooBar"), "foo<wbr>Bar")
assert.Equal(t, wbr("fooBarBaz"), "foo<wbr>Bar<wbr>Baz")
}
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
func TestRemoveLeadingUnderscores(t *testing.T) {
t.Parallel()
tests := []struct {
input string
expected string
}{
{input: "", expected: ""},
{input: "root", expected: "root"},
{input: "pulumi_azure_native", expected: "pulumi_azure_native"},
{input: "_root.FooBuzz", expected: "root.FooBuzz"},
{input: "_pulumi_random.sub_module.Type", expected: "pulumi_random.sub_module.Type"},
{input: "Optional[Sequence[_meta.v1.module_name.FooBar]]", expected: "Optional[Sequence[meta.v1.module_name.FooBar]]"},
}
for _, test := range tests {
result := removeLeadingUnderscores(test.input)
assert.Equal(t, test.expected, result)
}
}