go rewrite - compute documentation diffs

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")
 }

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)
 }

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 }}
 <a name="nested_{{ underscore $.Name }}"></a>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}}
+      {{- if $np.NestedProperties }}
+{{- trimTemplate "nested_property_documentation.html.markdown.tmpl" $np -}}
+      {{- end -}}
+    {{- end -}}
+  {{- end -}}
+{{- end -}}
+{{ "" }}

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 }}
+  {{- end -}}
+{{ "" }}

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
   </a>
 </div>
 			{{- 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