Skip to content

Commit

Permalink
Exclude code choosers in SDKs (#1887)
Browse files Browse the repository at this point in the history
Right now, we generate code blocks for the schema that look like this:


    <!--Start PulumiCodeChooser -->
    ```typescript
    // TS Code
    ```
    ```python
    # Python Code
    ```
    ...
    <!--End PulumiCodeChooser -->


That works great in the registry. For SDKs, we generate code that looks
like this:

```python
  # <!--Start PulumiCodeChooser -->
  # ```python
  # # Python Code
  # ```
  # <!--End PulumiCodeChooser -->
```

This is not good, since our users see our PulumiCodeChooser directives
directly.

This PR changes the bridge's behavior to only emit the PulumiCodeChooser
directives when we are targeting the schema.
  • Loading branch information
iwahbe committed Apr 19, 2024
1 parent f096184 commit 94c1de4
Show file tree
Hide file tree
Showing 4 changed files with 482 additions and 17 deletions.
21 changes: 18 additions & 3 deletions pkg/tfgen/docs.go
Original file line number Diff line number Diff line change
Expand Up @@ -1466,16 +1466,31 @@ func (g *Generator) convertExamplesInner(

if err != nil {
// We do not write this section, ever.
// We have to strip the entire section: any header, the code block, and any surrounding text.
//
// We have to strip the entire section: any header, the code
// block, and any surrounding text.
stripSection = true
stripSectionHeader = tfBlock.headerStart
} else {
// append any headers and following text first
if hasHeader {
fprintf("%s", docs[tfBlock.headerStart:tfBlock.start])
}
fprintf("%s\n%s\n%s",
startPulumiCodeChooser, convertedBlock, endPulumiCodeChooser)

switch g.language {
// If we are targeting the schema, then print code switcher
// fences for the registry.
case Schema:
fprintf("%s\n%s\n%s",
startPulumiCodeChooser,
convertedBlock,
endPulumiCodeChooser)
// Otherwise skip code switcher fences so they don't show up
// in generated SDKs.
default:
fprintf("%s", convertedBlock)
}

}
}
} else {
Expand Down
47 changes: 33 additions & 14 deletions pkg/tfgen/docs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -949,30 +949,20 @@ func TestParseImports_WithOverride(t *testing.T) {
assert.Equal(t, "## Import\n\noverridden import details", parser.ret.Import)
}

func ref[T any](t T) *T { return &t }

func TestConvertExamples(t *testing.T) {
if runtime.GOOS == "windows" {
t.Skipf("Skipping on windows to avoid failing on incorrect newline handling")
}

inmem := afero.NewMemMapFs()
info := testprovider.ProviderMiniRandom()
g, err := NewGenerator(GeneratorOptions{
Package: info.Name,
Version: info.Version,
Language: Schema,
ProviderInfo: info,
Root: inmem,
Sink: diag.DefaultSink(io.Discard, io.Discard, diag.FormatOptions{
Color: colors.Never,
}),
})
assert.NoError(t, err)

type testCase struct {
name string
path examplePath

needsProviders map[string]pluginDesc

language *Language
}

testCases := []testCase{
Expand All @@ -986,6 +976,17 @@ func TestConvertExamples(t *testing.T) {
"wavefront": {version: "3.0.0"},
},
},
{
name: "golang_wavefront_dashboard_json",
path: examplePath{
fullPath: "#/resources/wavefront:index/dashboardJson:DashboardJson",
token: "wavefront:index/dashboardJson:DashboardJson",
},
needsProviders: map[string]pluginDesc{
"wavefront": {version: "3.0.0"},
},
language: ref(Golang),
},
{
name: "equinix_fabric_connection",
path: examplePath{
Expand Down Expand Up @@ -1026,6 +1027,24 @@ func TestConvertExamples(t *testing.T) {
})

t.Run(tc.name, func(t *testing.T) {
inmem := afero.NewMemMapFs()
info := testprovider.ProviderMiniRandom()
language := Schema
if tc.language != nil {
language = *tc.language
}
g, err := NewGenerator(GeneratorOptions{
Package: info.Name,
Version: info.Version,
Language: language,
ProviderInfo: info,
Root: inmem,
Sink: diag.DefaultSink(io.Discard, io.Discard, diag.FormatOptions{
Color: colors.Never,
}),
})
assert.NoError(t, err)

docs, err := os.ReadFile(filepath.Join("test_data", "convertExamples",
fmt.Sprintf("%s.md", tc.name)))
require.NoError(t, err)
Expand Down
275 changes: 275 additions & 0 deletions pkg/tfgen/test_data/convertExamples/golang_wavefront_dashboard_json.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,275 @@
Provides a Wavefront Dashboard JSON resource. This allows dashboards to be created, updated, and deleted.

## Example Usage

```hcl
resource "wavefront_dashboard_json" "test_dashboard_json" {
dashboard_json = <<-EOF
{
"acl": {
"canModify": [
"group-uuid",
"role-uuid"
],
"canView": [
"group-uuid",
"role-uuid"
]
},
"name": "Terraform Test Dashboard Json",
"description": "a",
"eventFilterType": "BYCHART",
"eventQuery": "",
"defaultTimeWindow": "",
"url": "tftestimport",
"displayDescription": false,
"displaySectionTableOfContents": true,
"displayQueryParameters": false,
"sections": [
{
"name": "section 1",
"rows": [
{
"charts": [
{
"name": "chart 1",
"sources": [
{
"name": "source 1",
"query": "ts()",
"scatterPlotSource": "Y",
"querybuilderEnabled": false,
"sourceDescription": ""
}
],
"units": "someunit",
"base": 0,
"noDefaultEvents": false,
"interpolatePoints": false,
"includeObsoleteMetrics": false,
"description": "This is chart 1, showing something",
"chartSettings": {
"type": "markdown-widget",
"max": 100,
"expectedDataSpacing": 120,
"windowing": "full",
"windowSize": 10,
"autoColumnTags": false,
"columnTags": "deprecated",
"tagMode": "all",
"numTags": 2,
"customTags": [
"tag1",
"tag2"
],
"groupBySource": true,
"y1Max": 100,
"y1Units": "units",
"y0ScaleSIBy1024": true,
"y1ScaleSIBy1024": true,
"y0UnitAutoscaling": true,
"y1UnitAutoscaling": true,
"fixedLegendEnabled": true,
"fixedLegendUseRawStats": true,
"fixedLegendPosition": "RIGHT",
"fixedLegendDisplayStats": [
"stat1",
"stat2"
],
"fixedLegendFilterSort": "TOP",
"fixedLegendFilterLimit": 1,
"fixedLegendFilterField": "CURRENT",
"plainMarkdownContent": "markdown content"
},
"chartAttributes": {
"dashboardLinks": {
"*": {
"variables": {
"xxx": "xxx"
},
"destination": "/dashboards/xxxx"
}
}
},
"summarization": "MEAN"
}
],
"heightFactor": 50
}
]
}
],
"parameterDetails": {
"param": {
"hideFromView": false,
"description": null,
"allowAll": null,
"tagKey": null,
"queryValue": null,
"dynamicFieldType": null,
"reverseDynSort": null,
"parameterType": "SIMPLE",
"label": "test",
"defaultValue": "Label",
"valuesToReadableStrings": {
"Label": "test"
},
"selectedLabel": "Label",
"value": "test"
}
},
"tags": {
"customerTags": [
"terraform"
]
}
}
EOF
}
```

*
*Note:
** If there are dynamic variables in the Wavefront dashboard json, then these variables must be present in a separate file as mentioned in the section below.

## Reading from an External File

Below is the example dashboard with sections and parameters from an external file.

```hcl
resource "wavefront_dashboard_json" "test_dashboard_json" {
dashboard_json = templatefile("./<dashboard_file_path>.txt",
{
section1 = file("<path>/section1.json"),
section2 = file("<path>/section2.json"),
parameters = file("<path>/params.json")
}
)
}
```

The sample files are listed below.

* dashboard_file.txt

```hcl
{
"name": "Terraform Test Dashboard JSON",
"description": "a",
"eventFilterType": "BYCHART",
"eventQuery": "",
"defaultTimeWindow": "",
"url": "tftestimport",
"displayDescription": false,
"displaySectionTableOfContents": true,
"displayQueryParameters": false,
"sections": [
${section1},
${section2}
],
"parameterDetails": ${parameters},
"tags": {
"customerTags": ["terraform"]
}
}
```

* section1.json

```json
{
"name": "section 1",
"rows": [
{
"charts": [
{
"name": "chart 1",
"sources": [
{
"name": "source 1",
"query": "ts()",
"scatterPlotSource": "Y",
"querybuilderEnabled": false,
"sourceDescription": ""
}
],
"units": "someunit",
"base": 0,
"noDefaultEvents": false,
"interpolatePoints": false,
"includeObsoleteMetrics": false,
"description": "This is chart 1, showing something",
"chartSettings": {
"type": "markdown-widget",
"max": 100,
"expectedDataSpacing": 120,
"windowing": "full",
"windowSize": 10,
"autoColumnTags": false,
"columnTags": "deprecated",
"tagMode": "all",
"numTags": 2,
"customTags": [
"tag1",
"tag2"
],
"groupBySource": true,
"y1Max": 100,
"y1Units": "units",
"y0ScaleSIBy1024": true,
"y1ScaleSIBy1024": true,
"y0UnitAutoscaling": true,
"y1UnitAutoscaling": true,
"fixedLegendEnabled": true,
"fixedLegendUseRawStats": true,
"fixedLegendPosition": "RIGHT",
"fixedLegendDisplayStats": [
"stat1",
"stat2"
],
"fixedLegendFilterSort": "TOP",
"fixedLegendFilterLimit": 1,
"fixedLegendFilterField": "CURRENT",
"plainMarkdownContent": "markdown content"
},
"summarization": "MEAN"
}
],
"heightFactor": 50
}
]
}
```

* parameters.json

```json
{
"param": {
"hideFromView": false,
"description": null,
"allowAll": null,
"tagKey": null,
"queryValue": null,
"dynamicFieldType": null,
"reverseDynSort": null,
"parameterType": "SIMPLE",
"label": "test",
"defaultValue": "Label",
"valuesToReadableStrings": {
"Label": "test"
},
"selectedLabel": "Label",
"value": "test"
}
}
```

## Import

Dashboard JSON can be imported by using the `id`, e.g.:

```sh
$ pulumi import wavefront:index/dashboardJson:DashboardJson dashboard_json tftestimport
```

0 comments on commit 94c1de4

Please sign in to comment.