From 1544f9a83b32698b8ecd33d2508d412259c11e18 Mon Sep 17 00:00:00 2001 From: Cameron Thornton Date: Mon, 24 Jun 2024 08:11:46 -0500 Subject: [PATCH] go rewrite - compute documentation diffs --- mmv1/api/resource.go | 5 +- mmv1/google/template_utils.go | 59 +++++++++++++++++++ ..._property_documentation.html.markdown.tmpl | 44 +++++++++----- .../property_documentation.html.markdown.tmpl | 10 ++-- .../terraform/resource.html.markdown.tmpl | 40 +++++++------ 5 files changed, 121 insertions(+), 37 deletions(-) diff --git a/mmv1/api/resource.go b/mmv1/api/resource.go index ea122cd6ef82..d3c248335967 100644 --- a/mmv1/api/resource.go +++ b/mmv1/api/resource.go @@ -1379,6 +1379,9 @@ func (r Resource) GetPropertyUpdateMasksGroups(properties []*Type, maskPrefix st // Formats whitespace in the style of the old Ruby generator's descriptions in documentation func (r Resource) FormatDocDescription(desc string, indent bool) string { + if desc == "" { + return "" + } returnString := desc if indent { returnString = strings.ReplaceAll(returnString, "\n\n", "\n") @@ -1387,7 +1390,7 @@ func (r Resource) FormatDocDescription(desc string, indent bool) string { // fix removing for ruby -> go transition diffs returnString = strings.ReplaceAll(returnString, "\n \n **Note**: This field is non-authoritative,", "\n\n **Note**: This field is non-authoritative,") - return strings.TrimSuffix(returnString, "\n ") + return fmt.Sprintf("\n %s", strings.TrimSuffix(returnString, "\n ")) } return strings.TrimSuffix(returnString, "\n") } diff --git a/mmv1/google/template_utils.go b/mmv1/google/template_utils.go index 1053894233ba..78eb2dea26ac 100644 --- a/mmv1/google/template_utils.go +++ b/mmv1/google/template_utils.go @@ -14,10 +14,15 @@ package google import ( + "bytes" "errors" + "fmt" + "path/filepath" "strings" "text/template" + + "github.com/golang/glog" ) // Build a map(map[string]interface{}) from a list of paramerter @@ -66,4 +71,58 @@ var TemplateFunctions = template.FuncMap{ "sub": subtract, "plus": plus, "firstSentence": FirstSentence, + "trimTemplate": TrimTemplate, +} + +// Temporary function to simulate how Ruby MMv1's lines() function works +// for nested documentation. Can replace with normal "template" after switchover +func TrimTemplate(templatePath string, e any) string { + templates := []string{ + fmt.Sprintf("templates/terraform/%s", templatePath), + "templates/terraform/expand_resource_ref.tmpl", + } + templateFileName := filepath.Base(templatePath) + + // Need to remake TemplateFunctions, referencing it directly here + // causes a declaration loop + var templateFunctions = template.FuncMap{ + "title": SpaceSeparatedTitle, + "replace": strings.Replace, + "replaceAll": strings.ReplaceAll, + "camelize": Camelize, + "underscore": Underscore, + "plural": Plural, + "contains": strings.Contains, + "join": strings.Join, + "lower": strings.ToLower, + "upper": strings.ToUpper, + "dict": wrapMultipleParams, + "format2regex": Format2Regex, + "hasPrefix": strings.HasPrefix, + "sub": subtract, + "plus": plus, + "firstSentence": FirstSentence, + "trimTemplate": TrimTemplate, + } + + tmpl, err := template.New(templateFileName).Funcs(templateFunctions).ParseFiles(templates...) + if err != nil { + glog.Exit(err) + } + + contents := bytes.Buffer{} + if err = tmpl.ExecuteTemplate(&contents, templateFileName, e); err != nil { + glog.Exit(err) + } + + rs := contents.String() + + if rs == "" { + return rs + } + + for strings.HasSuffix(rs, "\n") { + rs = strings.TrimSuffix(rs, "\n") + } + return fmt.Sprintf("%s\n", rs) } diff --git a/mmv1/templates/terraform/nested_property_documentation.html.markdown.tmpl b/mmv1/templates/terraform/nested_property_documentation.html.markdown.tmpl index f451327fe851..4b4979bc6193 100644 --- a/mmv1/templates/terraform/nested_property_documentation.html.markdown.tmpl +++ b/mmv1/templates/terraform/nested_property_documentation.html.markdown.tmpl @@ -1,18 +1,34 @@ -{{- define "nestedPropertyDocumentation" }} - {{- if $.FlattenObject }} - {{- range $np := $.NestedProperties }} -{{- template "nestedPropertyDocumentation" $np -}} - {{- end}} - {{- else if $.NestedProperties }} +{{ "" }} +{{- if $.FlattenObject }} + {{- range $np := $.NestedProperties }} +{{- trimTemplate "nested_property_documentation.html.markdown.tmpl" $np -}} + {{- end -}} +{{- else if $.NestedProperties }} The `{{ underscore $.Name }}` block {{ if $.Output }}contains{{ else }}supports{{ end }}: -{{ if $.IsA "Map" }} - * `{{ underscore $.KeyName }}` - (Required) The identifier for this object. Format specified above. - {{- end}} +{{ "" }} + {{- if $.IsA "Map" }} +* `{{ underscore $.KeyName }}` - (Required) The identifier for this object. Format specified above. +{{ "" }} + {{- end -}} + {{- if $.NestedProperties }} {{- range $np := $.NestedProperties }} -{{- template "propertyDocumentation" $np }} +{{- trimTemplate "property_documentation.html.markdown.tmpl" $np -}} + {{- end -}} +{{ "" }} + {{- $innerNested := false }} + {{- range $np := $.NestedProperties }} + {{- if $np.NestedProperties }} + {{- $innerNested = true }} + {{- end }} + {{- end }} + {{- if $innerNested}} +{{ "" }} {{- end }} {{- range $np := $.NestedProperties }} -{{- template "nestedPropertyDocumentation" $np -}} - {{- end}} - {{- end}} -{{- end}} \ No newline at end of file + {{- if $np.NestedProperties }} +{{- trimTemplate "nested_property_documentation.html.markdown.tmpl" $np -}} + {{- end -}} + {{- end -}} + {{- end -}} +{{- end -}} +{{ "" }} \ No newline at end of file diff --git a/mmv1/templates/terraform/property_documentation.html.markdown.tmpl b/mmv1/templates/terraform/property_documentation.html.markdown.tmpl index 6b08df4ada86..92d35d242d26 100644 --- a/mmv1/templates/terraform/property_documentation.html.markdown.tmpl +++ b/mmv1/templates/terraform/property_documentation.html.markdown.tmpl @@ -1,4 +1,4 @@ -{{- define "propertyDocumentation" }} +{{ "" }} * `{{ underscore $.Name }}` - {{- if and (eq $.MinVersion "beta") (not (eq $.ResourceMetadata.MinVersion "beta")) }} {{- if $.Required }} @@ -21,12 +21,12 @@ (Deprecated) {{- end}} {{- end }} - {{ $.ResourceMetadata.FormatDocDescription $.Description true -}} + {{- $.ResourceMetadata.FormatDocDescription $.Description true -}} {{- if and (and ($.IsA "Array") ($.ItemType.IsA "Enum")) (and (not $.Output) (not $.ItemType.SkipDocsValues))}} {{- if $.ItemType.DefaultValue }} Default value is `{{ $.ItemType.DefaultValue }}`. {{- end }} - Each value may be one of: {{ $.ItemType.EnumValuesToString "`" false }}. + Each value may be one of: {{ $.ItemType.EnumValuesToString "`" false }}. {{- else if and ($.IsA "Enum") (and (not $.Output) (not (and $.ItemType $.ItemType.SkipDocsValues)))}} {{- if $.DefaultValue }} Default value is `{{ $.DefaultValue }}`. @@ -42,5 +42,5 @@ {{- if $.DeprecationMessage }} ~> **Warning:** {{ $.DeprecationMessage }} - {{- end }} -{{ end }} \ No newline at end of file + {{- end -}} +{{ "" }} \ No newline at end of file diff --git a/mmv1/templates/terraform/resource.html.markdown.tmpl b/mmv1/templates/terraform/resource.html.markdown.tmpl index cf13c07f9e3e..5ebe9a3680d0 100644 --- a/mmv1/templates/terraform/resource.html.markdown.tmpl +++ b/mmv1/templates/terraform/resource.html.markdown.tmpl @@ -27,7 +27,7 @@ # ---------------------------------------------------------------------------- subcategory: "{{$.ProductMetadata.DisplayName}}" description: |- - {{ $.FormatDocDescription (firstSentence $.Description) true }} + {{- $.FormatDocDescription (firstSentence $.Description) true }} --- # {{$.TerraformName}} @@ -40,7 +40,7 @@ description: |- ~> **Warning:** This resource is in beta, and should be used with the terraform-provider-google-beta provider. See [Provider Versions](https://terraform.io/docs/providers/google/guides/provider_versions.html) for more details on beta resources. {{- end }} -{{ if $.References}} +{{ if or $.References.Api $.References.Guides }} To get more information about {{$.Name}}, see: {{- if $.References.Api}} @@ -53,7 +53,10 @@ To get more information about {{$.Name}}, see: * [{{$title}}]({{$link}}) {{- end }} {{- end }} -{{ end }} +{{ "" }} +{{- else }} +{{ "" }} +{{- end }} {{- if $.Docs.Warning}} ~> **Warning:** {{$.Docs.Warning}} @@ -76,37 +79,37 @@ values will be stored in the raw state as plain text: {{ $.SensitivePropsToStrin {{- end }} - {{- end }} ## Example Usage - {{ title (camelize $e.Name "upper" )}} ```hcl {{ $e.DocumentationHCLText -}} ``` + {{- end }} {{- end }} {{- end }} ## Argument Reference The following arguments are supported: - -{{ range $p := $.RootProperties }} +{{ "" }} +{{ "" }} +{{- range $p := $.RootProperties }} {{- if $p.Required }} -{{- template "propertyDocumentation" $p }} +{{- trimTemplate "property_documentation.html.markdown.tmpl" $p -}} {{- end }} {{- end }} - +{{ "" }} {{- range $p := $.AllUserProperties }} {{- if $p.Required }} -{{- template "nestedPropertyDocumentation" $p}} +{{- trimTemplate "nested_property_documentation.html.markdown.tmpl" $p -}} {{- end}} {{- end }} - - - - {{ range $p := $.RootProperties }} {{- if and (not $p.Required) (not $p.Output) }} -{{- template "propertyDocumentation" $p -}} +{{- trimTemplate "property_documentation.html.markdown.tmpl" $p -}} {{- end }} {{- end }} {{- if or (contains $.BaseUrl "{{project}}") (contains $.CreateUrl "{{project}}")}} @@ -121,8 +124,8 @@ The following arguments are supported: {{- end }} {{- range $p := $.AllUserProperties }} {{- if and (not $p.Required) (not $p.Output) }} -{{- template "nestedPropertyDocumentation" $p -}} -{{ end}} +{{- trimTemplate "nested_property_documentation.html.markdown.tmpl" $p -}} +{{- end}} {{- end }} ## Attributes Reference @@ -131,15 +134,16 @@ In addition to the arguments listed above, the following computed attributes are * `id` - an identifier for the resource with format `{{$.IdFormat}}` {{ range $p := $.RootProperties }} {{- if $p.Output }} -{{- template "propertyDocumentation" $p -}} +{{- trimTemplate "property_documentation.html.markdown.tmpl" $p }} {{- end}} {{- end }} -{{- if $.HasSelfLink }} +{{- if $.HasSelfLink -}} * `self_link` - The URI of the created resource. +{{ "" }} {{- end }} {{ range $p := $.AllUserProperties }} {{- if $p.Output }} -{{- template "nestedPropertyDocumentation" $p -}} +{{- trimTemplate "nested_property_documentation.html.markdown.tmpl" $p }} {{- end }} {{- end }} ## Timeouts @@ -148,7 +152,9 @@ This resource provides the following [Timeouts](https://developer.hashicorp.com/terraform/plugin/sdkv2/resources/retries-and-customizable-timeouts) configuration options: - `create` - Default is {{$.Timeouts.InsertMinutes}} minutes. -- `update` - Default is {{$.Timeouts.UpdateMinutes}} minutes.{{/*TODO Q2: <% if updatable?(object, properties) || object.root_labels? -%> */}} +{{- if or $.Updatable $.RootLabels }} +- `update` - Default is {{$.Timeouts.UpdateMinutes}} minutes. +{{- end }} - `delete` - Default is {{$.Timeouts.DeleteMinutes}} minutes. ## Import