Add an Overview subheader to logically separate Installation and general provider info (#2419)

This pull request is the result of discovering #2420.

This fix:

- Avoids the rendering issues for unheadered text as outlined in #2420
by adding a `##` header
- Visually and logically separates the provider summary text from the
installation section.
- Strips the H1 header earlier in the doc transformation so we can
verify remaining content
- Strips the "schema generated by tfplugindocs" HTML comment

TL;DR: while this is on its face a quick fix, we _do_ want to separate
the installation from the general text, so adding the Overview header is
something we'd want to do anyway.

Screenshots:

Before:
<img width="550" alt="Screenshot 2024-09-17 at 11 16 15 AM"
src="https://github.com/user-attachments/assets/0b07e7a3-2f74-4049-9382-e5739d13577d">

After:
<img width="578" alt="Screenshot 2024-09-17 at 11 16 34 AM"
src="https://github.com/user-attachments/assets/2f648067-56a2-4c0c-96c5-d8297afe7f8c">

Author: guineveresaenger

pkg/tfgen/installation_docs.go

@@ -28,14 +28,25 @@ func plainDocsParser(docFile *DocFile, g *Generator) ([]byte, error) {
 	// Generate pulumi-specific front matter
 	frontMatter := writeFrontMatter(g.info.Name)
 
+	// Remove the title. A title gets populated from Hugo frontmatter; we do not want two.
+	content, err := removeTitle(content)
+	if err != nil {
+		return nil, err
+	}
+
+	// Strip the tfplugindocs generation HTML comment
+	content = stripSchemaGeneratedByTFPluginDocs(content)
+
 	// Generate pulumi-specific installation instructions
 	installationInstructions := writeInstallationInstructions(g.info.Golang.ImportBasePath, g.info.Name)
 
+	overviewHeader := getOverviewHeader(content)
+
 	// Add instructions to top of file
-	contentStr := frontMatter + installationInstructions + string(content)
+	contentStr := frontMatter + installationInstructions + overviewHeader + string(content)
 
 	//Translate code blocks to Pulumi
-	contentStr, err := translateCodeBlocks(contentStr, g)
+	contentStr, err = translateCodeBlocks(contentStr, g)
 	if err != nil {
 		return nil, err
 	}
@@ -45,13 +56,6 @@ func plainDocsParser(docFile *DocFile, g *Generator) ([]byte, error) {
 	if err != nil {
 		return nil, err
 	}
-
-	// Remove the title. A title gets populated from Hugo frontmatter; we do not want two.
-	contentBytes, err = removeTitle(contentBytes)
-	if err != nil {
-		return nil, err
-	}
-
 	//Reformat field names. Configuration fields are camelCased like nodejs.
 	contentStr, _ = reformatText(infoContext{
 		language: "nodejs",
@@ -107,6 +111,23 @@ func writeInstallationInstructions(goImportBasePath, providerName string) string
 	)
 }
 
+func getOverviewHeader(content []byte) string {
+	const overviewHeader = "## Overview\n\n"
+	// If content starts with an H2, or is otherwise empty then we don't want to add this header
+	content = bytes.TrimSpace(content)
+	if bytes.HasPrefix(content, []byte("## ")) || len(content) == 0 {
+		return ""
+	}
+	return overviewHeader
+}
+
+var tfplugindocsComment = regexp.MustCompile("<!-- schema generated by tfplugindocs -->")
+
+func stripSchemaGeneratedByTFPluginDocs(content []byte) []byte {
+	content = tfplugindocsComment.ReplaceAll(content, nil)
+	return content
+}
+
 func applyEditRules(contentBytes []byte, docFile string, g *Generator) ([]byte, error) {
 	// Obtain edit rules passed by the provider
 	edits := g.editRules

pkg/tfgen/installation_docs_test.go

@@ -157,6 +157,57 @@ func TestWriteInstallationInstructions(t *testing.T) {
 	})
 }
 
+func TestWriteOverviewHeader(t *testing.T) {
+	t.Parallel()
+	type testCase struct {
+		// The name of the test case.
+		name     string
+		input    string
+		expected string
+	}
+
+	testCases := []testCase{
+		{
+			name:     "Writes When Content Exists",
+			input:    readTestFile(t, "write-overview-header/with-overview-text.md"),
+			expected: "## Overview\n\n",
+		},
+		{
+			name:     "Does Not Write For Empty Overview",
+			input:    readTestFile(t, "write-overview-header/empty-overview.md"),
+			expected: "",
+		},
+		{
+			name:     "Does Not Write For Empty Content",
+			input:    "",
+			expected: "",
+		},
+	}
+	for _, tt := range testCases {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			actual := getOverviewHeader([]byte(tt.input))
+			assert.Equal(t, tt.expected, actual)
+		})
+	}
+
+	// The following mirrors the way that the result of `writeOverviewHeader` gets applied to our installation doc.
+	contextTest := testCase{
+		name:     "Does Not Write For Empty Overview With Context",
+		input:    readTestFile(t, "write-overview-header/empty-overview-with-context-input.md"),
+		expected: readTestFile(t, "write-overview-header/empty-overview-with-context-expected.md"),
+	}
+	t.Run(contextTest.name, func(t *testing.T) {
+		t.Parallel()
+		text, err := removeTitle([]byte(contextTest.input))
+		require.NoError(t, err)
+		header := getOverviewHeader(text)
+		actual := header + string(text)
+		assertEqualHTML(t, contextTest.expected, actual)
+	})
+}
+
 func TestWriteFrontMatter(t *testing.T) {
 	t.Parallel()
 

pkg/tfgen/test_data/write-overview-header/empty-overview-with-context-expected.md

@@ -0,0 +1,2 @@
+## Schema
+Find information about the test provider schema here.

pkg/tfgen/test_data/write-overview-header/empty-overview-with-context-input.md

@@ -0,0 +1,4 @@
+# Test Provider
+
+## Schema
+Find information about the test provider schema here.

pkg/tfgen/test_data/write-overview-header/empty-overview.md

@@ -0,0 +1,6 @@
+
+
+
+
+
+## Schema

pkg/tfgen/test_data/write-overview-header/with-overview-text.md

@@ -0,0 +1,11 @@
+
+# test Provider
+
+This provider has some functionality that we're introducing here.
+
+More text
+
+Lorem ipsum
+
+
+## Schema