fix docs builder for examples overriding use case (#1509)

Fixes #1497 separates the resource description from the examples section --------- Signed-off-by: ocobleseqx <[email protected]> Co-authored-by: Ian Wahbe <[email protected]>
pulumi · Nov 21, 2023 · c76fc0f · c76fc0f
1 parent 089f386
commit c76fc0f
Show file tree

Hide file tree

Showing 4 changed files with 1,051 additions and 10 deletions.
diff --git a/pkg/tfgen/docs.go b/pkg/tfgen/docs.go
@@ -1276,7 +1276,19 @@ func (g *Generator) convertExamples(docs string, path examplePath, stripSubsecti
 		strings.Contains(docs, "```csharp") || strings.Contains(docs, "```java") {
 		// we have explicitly rewritten these examples and need to just return them directly rather than trying
 		// to reconvert them. But we need to surround them in the examples shortcode for rendering on the registry
-		return fmt.Sprintf("{{%% examples %%}}\n%s\n{{%% /examples %%}}", docs)
+
+		// Find the index of "## Example Usage"
+		exampleIndex := strings.Index(docs, "## Example Usage")
+
+		// if not found surround all content
+		if exampleIndex == -1 {
+			return fmt.Sprintf("{{%% examples %%}}\n%s\n{{%% /examples %%}}", docs)
+		}
+
+		// Separate resource description and surround the examples
+		return fmt.Sprintf("%s\n\n{{%% examples %%}}\n%s\n{{%% /examples %%}}",
+			strings.TrimRightFunc(docs[:exampleIndex], unicode.IsSpace),
+			docs[exampleIndex:])
 	}
 
 	if cliConverterEnabled() {

diff --git a/pkg/tfgen/docs_test.go b/pkg/tfgen/docs_test.go
@@ -22,6 +22,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"runtime"
 	"strings"
@@ -39,7 +40,6 @@ import (
 
 	"github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge"
 	"github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfgen/internal/testprovider"
-	"os/exec"
 )
 
 var (
@@ -900,7 +900,7 @@ func TestConvertExamples(t *testing.T) {
 
 		stripSubsectionWithErrors bool
 
-		needsProviders map[string]string
+		needsProviders map[string]pluginDesc
 	}
 
 	testCases := []testCase{
@@ -911,8 +911,21 @@ func TestConvertExamples(t *testing.T) {
 				token:    "wavefront:index/dashboardJson:DashboardJson",
 			},
 			stripSubsectionWithErrors: true,
-			needsProviders: map[string]string{
-				"wavefront": "3.0.0",
+			needsProviders: map[string]pluginDesc{
+				"wavefront": {version: "3.0.0"},
+			},
+		},
+		{
+			name: "equinix_fabric_connection",
+			path: examplePath{
+				fullPath: "#/resources/equinix:fabric:Connection",
+				token:    "equinix:fabric:Connection",
+			},
+			needsProviders: map[string]pluginDesc{
+				"equinix": {
+					pluginDownloadURL: "github://api.github.com/equinix",
+					version:           "0.6.0",
+				},
 			},
 		},
 	}
@@ -943,7 +956,12 @@ func TestConvertExamples(t *testing.T) {
 	}
 }
 
-func ensureProvidersInstalled(t *testing.T, needsProviders map[string]string) {
+type pluginDesc struct {
+	version           string
+	pluginDownloadURL string
+}
+
+func ensureProvidersInstalled(t *testing.T, needsProviders map[string]pluginDesc) {
 	pulumi, err := exec.LookPath("pulumi")
 	require.NoError(t, err)
 
@@ -963,15 +981,15 @@ func ensureProvidersInstalled(t *testing.T, needsProviders map[string]string) {
 	err = json.Unmarshal(buf.Bytes(), &installedPlugins)
 	require.NoError(t, err)
 
-	for name, ver := range needsProviders {
+	for name, desc := range needsProviders {
 		count := 0
 		matched := false
 
 		for _, p := range installedPlugins {
 			if p.Name == name {
 				count++
 			}
-			if p.Name == name && p.Version == ver {
+			if p.Name == name && p.Version == desc.version {
 				matched = true
 			}
 		}
@@ -987,8 +1005,13 @@ func ensureProvidersInstalled(t *testing.T, needsProviders map[string]string) {
 			require.NoError(t, err)
 		}
 
-		t.Logf("pulumi plugin install resource %s %s", name, ver)
-		err = exec.Command(pulumi, "plugin", "install", "resource", name, ver).Run()
+		args := []string{"plugin", "install", "resource", name, desc.version}
+		if desc.pluginDownloadURL != "" {
+			args = append(args, "--server", desc.pluginDownloadURL)
+		}
+		cmd := exec.Command(pulumi, args...)
+		t.Logf("Exec: %s", cmd)
+		err = cmd.Run()
 		require.NoError(t, err)
 	}
 }