Skip to content

Commit

Permalink
Use Provider Display Name for index doc (#2599)
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@guineveresaenger
guineveresaenger authored Nov 7, 2024
1 parent e6ffc06 commit 3a71ffb
Show file tree
Hide file tree
Showing 2 changed files with 108 additions and 26 deletions.
35 changes: 25 additions & 10 deletions pkg/tfgen/installation_docs.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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,
)
Expand Down Expand Up @@ -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()
}
99 changes: 83 additions & 16 deletions pkg/tfgen/installation_docs_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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) {
Expand Down

0 comments on commit 3a71ffb

Please sign in to comment.