From 3a71ffbdb7cf3e310bd0a5feba080681ca0b3c24 Mon Sep 17 00:00:00 2001 From: Guinevere Saenger Date: Wed, 6 Nov 2024 16:06:51 -0800 Subject: [PATCH] Use Provider Display Name for index doc (#2599) This pull request leverages the provider's info.DisplayName field to populate the index file's frontmatter (title) as well as the installation instructions. It will fall back to using the package name as supplied by the generator if DisplayName is not set. For generating installation instructions, the package name continues to be used for the packages, but the display name, if set, will be used for "The Foo provider is available as a package...." line. Fixes #2586. --- pkg/tfgen/installation_docs.go | 35 +++++++--- pkg/tfgen/installation_docs_test.go | 99 ++++++++++++++++++++++++----- 2 files changed, 108 insertions(+), 26 deletions(-) diff --git a/pkg/tfgen/installation_docs.go b/pkg/tfgen/installation_docs.go index 89182f875..43782c51d 100644 --- a/pkg/tfgen/installation_docs.go +++ b/pkg/tfgen/installation_docs.go @@ -33,9 +33,11 @@ func plainDocsParser(docFile *DocFile, g *Generator) ([]byte, error) { // Get file content without front matter content := trimFrontMatter(contentBytes) + providerName := getProviderName(g) + // Add pulumi-specific front matter // Generate pulumi-specific front matter - frontMatter := writeFrontMatter(g.pkg.Name().String()) + frontMatter := writeFrontMatter(providerName) // Remove the title. A title gets populated from Hugo frontmatter; we do not want two. content, err = removeTitle(content) @@ -47,7 +49,11 @@ func plainDocsParser(docFile *DocFile, g *Generator) ([]byte, error) { content = stripSchemaGeneratedByTFPluginDocs(content) // Generate pulumi-specific installation instructions - installationInstructions := writeInstallationInstructions(g.info.Golang.ImportBasePath, g.pkg.Name().String()) + installationInstructions := writeInstallationInstructions( + g.info.Golang.ImportBasePath, + providerName, + g.pkg.Name().String(), + ) // Determine if we should write an overview header. overviewHeader := getOverviewHeader(content) @@ -103,20 +109,21 @@ func writeFrontMatter(providerName string) string { // .NET: Pulumi.foo // Java: com.pulumi/foo // **** -func writeInstallationInstructions(goImportBasePath, providerName string) string { +func writeInstallationInstructions(goImportBasePath, displayName, pkgName string) string { // Capitalize the package name for C# capitalize := cases.Title(language.English) - cSharpName := capitalize.String(providerName) + cSharpName := capitalize.String(pkgName) return fmt.Sprintf( "## Installation\n\n"+ "The %[1]s provider is available as a package in all Pulumi languages:\n\n"+ - "* JavaScript/TypeScript: [`@pulumi/%[1]s`](https://www.npmjs.com/package/@pulumi/%[1]s)\n"+ - "* Python: [`pulumi-%[1]s`](https://pypi.org/project/pulumi-%[1]s/)\n"+ - "* Go: [`%[3]s`](https://github.com/pulumi/pulumi-%[1]s)\n"+ - "* .NET: [`Pulumi.%[2]s`](https://www.nuget.org/packages/Pulumi.%[2]s)\n"+ - "* Java: [`com.pulumi/%[1]s`](https://central.sonatype.com/artifact/com.pulumi/%[1]s)\n\n", - providerName, + "* JavaScript/TypeScript: [`@pulumi/%[2]s`](https://www.npmjs.com/package/@pulumi/%[2]s)\n"+ + "* Python: [`pulumi-%[2]s`](https://pypi.org/project/pulumi-%[2]s/)\n"+ + "* Go: [`%[4]s`](https://github.com/pulumi/pulumi-%[2]s)\n"+ + "* .NET: [`Pulumi.%[3]s`](https://www.nuget.org/packages/Pulumi.%[3]s)\n"+ + "* Java: [`com.pulumi/%[2]s`](https://central.sonatype.com/artifact/com.pulumi/%[2]s)\n\n", + displayName, + pkgName, cSharpName, goImportBasePath, ) @@ -429,3 +436,11 @@ func removeTfVersionMentions() tfbridge.DocsEdit { Phase: info.PostCodeTranslation, } } + +func getProviderName(g *Generator) string { + providerName := g.info.DisplayName + if providerName != "" { + return providerName + } + return g.pkg.Name().String() +} diff --git a/pkg/tfgen/installation_docs_test.go b/pkg/tfgen/installation_docs_test.go index f412f59a1..3e3f01c59 100644 --- a/pkg/tfgen/installation_docs_test.go +++ b/pkg/tfgen/installation_docs_test.go @@ -108,6 +108,50 @@ func TestPlainDocsParser(t *testing.T) { } } +func TestDisplayNameFallback(t *testing.T) { + t.Parallel() + + type testCase struct { + // The name of the test case. + name string + displayName string + pkgName string + expected string + } + + tests := []testCase{ + { + name: "Uses Display Name", + displayName: "Unicorn", + pkgName: "Horse", + expected: "Unicorn", + }, + { + name: "Defaults to pkgName as provider name", + pkgName: "Horse", + expected: "Horse", + }, + } + for _, tt := range tests { + tt := tt + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + if runtime.GOOS == "windows" { + t.Skipf("Skipping on Windows due to a newline handling issue") + } + g := &Generator{ + info: tfbridge.ProviderInfo{ + DisplayName: tt.displayName, + }, + pkg: tokens.NewPackageToken(tokens.PackageName(tt.pkgName)), + } + actual := getProviderName(g) + + assert.Equal(t, tt.expected, actual) + }) + } +} + func TestTrimFrontmatter(t *testing.T) { t.Parallel() type testCase struct { @@ -186,28 +230,51 @@ func TestWriteInstallationInstructions(t *testing.T) { // The name of the test case. name string goImportBasePath string + displayName string packageName string expected string } - tc := testCase{ - name: "Generates Install Information From Package Name", - expected: "## Installation\n\n" + - "The testcase provider is available as a package in all Pulumi languages:\n\n" + - "* JavaScript/TypeScript: [`@pulumi/testcase`](https://www.npmjs.com/package/@pulumi/testcase)\n" + - "* Python: [`pulumi-testcase`](https://pypi.org/project/pulumi-testcase/)\n" + - "* Go: [`github.com/pulumi/pulumi-testcase/sdk/v3/go/pulumi-testcase`](https://github.com/pulumi/pulumi-testcase)\n" + - "* .NET: [`Pulumi.Testcase`](https://www.nuget.org/packages/Pulumi.Testcase)\n" + - "* Java: [`com.pulumi/testcase`](https://central.sonatype.com/artifact/com.pulumi/testcase)\n\n", - goImportBasePath: "github.com/pulumi/pulumi-testcase/sdk/v3/go/pulumi-testcase", - packageName: "testcase", + tests := []testCase{ + { + name: "Generates Install Information From Package Name", + expected: "## Installation\n\n" + + "The testcase provider is available as a package in all Pulumi languages:\n\n" + + "* JavaScript/TypeScript: [`@pulumi/testcase`](https://www.npmjs.com/package/@pulumi/testcase)\n" + + "* Python: [`pulumi-testcase`](https://pypi.org/project/pulumi-testcase/)\n" + + "* Go: [`github.com/pulumi/pulumi-testcase/sdk/v3/go/pulumi-testcase`](https://github.com/pulumi/pulumi-testcase)\n" + + "* .NET: [`Pulumi.Testcase`](https://www.nuget.org/packages/Pulumi.Testcase)\n" + + "* Java: [`com.pulumi/testcase`](https://central.sonatype.com/artifact/com.pulumi/testcase)\n\n", + goImportBasePath: "github.com/pulumi/pulumi-testcase/sdk/v3/go/pulumi-testcase", + displayName: "testcase", + packageName: "testcase", + }, + { + name: "Generates Install Information From Display And Package Names", + expected: "## Installation\n\n" + + "The Test Case provider is available as a package in all Pulumi languages:\n\n" + + "* JavaScript/TypeScript: [`@pulumi/testcase`](https://www.npmjs.com/package/@pulumi/testcase)\n" + + "* Python: [`pulumi-testcase`](https://pypi.org/project/pulumi-testcase/)\n" + + "* Go: [`github.com/pulumi/pulumi-testcase/sdk/v3/go/pulumi-testcase`](https://github.com/pulumi/pulumi-testcase)\n" + + "* .NET: [`Pulumi.Testcase`](https://www.nuget.org/packages/Pulumi.Testcase)\n" + + "* Java: [`com.pulumi/testcase`](https://central.sonatype.com/artifact/com.pulumi/testcase)\n\n", + goImportBasePath: "github.com/pulumi/pulumi-testcase/sdk/v3/go/pulumi-testcase", + displayName: "Test Case", + packageName: "testcase", + }, } - t.Run(tc.name, func(t *testing.T) { - t.Parallel() - actual := writeInstallationInstructions(tc.goImportBasePath, tc.packageName) - require.Equal(t, tc.expected, actual) - }) + for _, tt := range tests { + tt := tt + t.Run(tt.name, func(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skipf("Skipping on Windows due to a test setup issue") + } + t.Parallel() + actual := writeInstallationInstructions(tt.goImportBasePath, tt.displayName, tt.packageName) + assert.Equal(t, tt.expected, actual) + }) + } } func TestWriteOverviewHeader(t *testing.T) {