From 78c55099c2b854c121c17080a66bdcba68d91065 Mon Sep 17 00:00:00 2001 From: Cameron Thornton Date: Thu, 30 May 2024 17:05:43 -0500 Subject: [PATCH] go rewrite - fix some more documentation diffs (#10834) --- mmv1/api/resource.go | 12 ++ mmv1/api/resource/examples.go | 142 ++++-------------- mmv1/products/pubsub/go_Subscription.yaml | 6 +- mmv1/products/pubsub/go_Topic.yaml | 6 +- mmv1/provider/template_data.go | 29 ++-- .../property_documentation.html.markdown.tmpl | 26 ++-- mmv1/templates/terraform/resource.go.tmpl | 2 +- .../terraform/resource.html.markdown.tmpl | 11 +- 8 files changed, 79 insertions(+), 155 deletions(-) diff --git a/mmv1/api/resource.go b/mmv1/api/resource.go index a750741ecce9..6d9ad9bdf4c7 100644 --- a/mmv1/api/resource.go +++ b/mmv1/api/resource.go @@ -1293,6 +1293,18 @@ func (r Resource) GetPropertyUpdateMasksGroups() map[string][]string { return maskGroups } +// Formats whitespace in the style of the old Ruby generator's descriptions in documentation +func FormatDocDescription(desc string) string { + returnString := strings.ReplaceAll(desc, "\n\n", "\n") + + returnString = strings.ReplaceAll(returnString, "\n", "\n ") + + // 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 ") +} + func (r Resource) CustomTemplate(templatePath string, appendNewline bool) string { return resource.ExecuteTemplate(&r, templatePath, appendNewline) } diff --git a/mmv1/api/resource/examples.go b/mmv1/api/resource/examples.go index d5a5dde96cf8..7c6c45530140 100644 --- a/mmv1/api/resource/examples.go +++ b/mmv1/api/resource/examples.go @@ -179,13 +179,33 @@ func (e *Examples) UnmarshalYAML(n *yaml.Node) error { // Executes example templates for documentation and tests func (e *Examples) SetHCLText() { - e.DocumentationHCLText = ExecuteTemplate(e, e.ConfigPath, true) + docCopy := e + testCopy := e + docs_defaults := map[string]string{ + "PROJECT_NAME": "my-project-name", + "CREDENTIALS": "my/credentials/filename.json", + "REGION": "us-west1", + "ORG_ID": "123456789", + "ORG_DOMAIN": "example.com", + "ORG_TARGET": "123456789", + "BILLING_ACCT": "000000-0000000-0000000-000000", + "MASTER_BILLING_ACCT": "000000-0000000-0000000-000000", + "SERVICE_ACCT": "my@service-account.com", + "CUST_ID": "A01b123xz", + "IDENTITY_USER": "cloud_identity_user", + "PAP_DESCRIPTION": "description", + } + + // Apply doc defaults to test_env_vars from YAML + for key := range docCopy.TestEnvVars { + docCopy.TestEnvVars[key] = docs_defaults[docCopy.TestEnvVars[key]] + } + e.DocumentationHCLText = ExecuteTemplate(docCopy, docCopy.ConfigPath, true) - copy := e // Override vars to inject test values into configs - will have // - "a-example-var-value%{random_suffix}"" // - "%{my_var}" for overrides that have custom Golang values - for key, value := range copy.Vars { + for key, value := range testCopy.Vars { var newVal string if strings.Contains(value, "-") { newVal = fmt.Sprintf("tf-test-%s", value) @@ -199,15 +219,15 @@ func (e *Examples) SetHCLText() { if len(newVal) > 54 { newVal = newVal[:54] } - copy.Vars[key] = fmt.Sprintf("%s%%{random_suffix}", newVal) + testCopy.Vars[key] = fmt.Sprintf("%s%%{random_suffix}", newVal) } // Apply overrides from YAML - for key := range copy.TestVarsOverrides { - copy.Vars[key] = fmt.Sprintf("%%{%s}", key) + for key := range testCopy.TestVarsOverrides { + testCopy.Vars[key] = fmt.Sprintf("%%{%s}", key) } - e.TestHCLText = ExecuteTemplate(copy, copy.ConfigPath, true) + e.TestHCLText = ExecuteTemplate(testCopy, testCopy.ConfigPath, true) } func ExecuteTemplate(e any, templatePath string, appendNewline bool) string { @@ -235,114 +255,6 @@ func ExecuteTemplate(e any, templatePath string, appendNewline bool) string { return rs } -// func (e *Examples) config_documentation(pwd) { -// docs_defaults = { -// PROJECT_NAME: 'my-project-name', -// CREDENTIALS: 'my/credentials/filename.json', -// REGION: 'us-west1', -// ORG_ID: '123456789', -// ORG_DOMAIN: 'example.com', -// ORG_TARGET: '123456789', -// BILLING_ACCT: '000000-0000000-0000000-000000', -// MASTER_BILLING_ACCT: '000000-0000000-0000000-000000', -// SERVICE_ACCT: 'my@service-account.com', -// CUST_ID: 'A01b123xz', -// IDENTITY_USER: 'cloud_identity_user', -// PAP_DESCRIPTION: 'description' -// } -// @vars ||= {} -// @test_env_vars ||= {} -// body = lines(compile_file( -// { -// vars:, -// test_env_vars: test_env_vars.to_h { |k, v| [k, docs_defaults[v]] }, -// primary_resource_id: -// }, -// "//{pwd}///{config_path}" -// )) - -// // Remove region tags -// body = body.gsub(/// \[[a-zA-Z_ ]+\]\n/, '') -// body = body.gsub(/\n// \[[a-zA-Z_ ]+\]/, '') -// lines(compile_file( -// { content: body }, -// "//{pwd}/templates/terraform/examples/base_configs/documentation.tf.erb" -// )) -// } - -// func (e *Examples) config_test(pwd) { -// body = config_test_body(pwd) -// lines(compile_file( -// { -// content: body -// }, -// "//{pwd}/templates/terraform/examples/base_configs/test_body.go.erb" -// )) -// } - -// rubocop:disable Style/FormatStringToken -// func (e *Examples) config_test_body(pwd) { -// @vars ||= {} -// @test_env_vars ||= {} -// @test_vars_overrides ||= {} - -// // Construct map for vars to inject into config - will have -// // - "a-example-var-value%{random_suffix}"" -// // - "%{my_var}" for overrides that have custom Golang values -// rand_vars = vars.map do |k, v| -// // Some resources only allow underscores. -// testv = if v.include?('-') -// "tf-test-//{v}" -// elsif v.include?('_') -// "tf_test_//{v}" -// else -// // Some vars like descriptions shouldn't have prefix -// v -// end -// // Random suffix is 10 characters and standard name length <= 64 -// testv = "//{testv[0...54]}%{random_suffix}" -// [k, testv] -// end - -// rand_vars = rand_vars.to_h -// overrides = test_vars_overrides.to_h { |k, _| [k, "%{//{k}}"] } -// body = lines(compile_file( -// { -// vars: rand_vars.merge(overrides), -// test_env_vars: test_env_vars.to_h { |k, _| [k, "%{//{k}}"] }, -// primary_resource_id:, -// primary_resource_type: -// }, -// "//{pwd}///{config_path}" -// )) - -// // Remove region tags -// body = body.gsub(/// \[[a-zA-Z_ ]+\]\n/, '') -// body = body.gsub(/\n// \[[a-zA-Z_ ]+\]/, '') -// substitute_test_paths body -// } - -// func (e *Examples) config_oics(pwd) { -// @vars ||= [] -// @oics_vars_overrides ||= {} - -// rand_vars = vars.to_h { |k, str| [k, "//{str}-${local.name_suffix}"] } - -// // Examples with test_env_vars are skipped elsewhere -// body = lines(compile_file( -// { -// vars: rand_vars.merge(oics_vars_overrides), -// primary_resource_id: -// }, -// "//{pwd}///{config_path}" -// )) - -// // Remove region tags -// body = body.gsub(/// \[[a-zA-Z_ ]+\]\n/, '') -// body = body.gsub(/\n// \[[a-zA-Z_ ]+\]/, '') -// substitute_example_paths body -// } - func (e *Examples) OiCSLink() string { v := url.Values{} // TODO Q2: Values.Encode() sorts the values by key alphabetically. This will produce diff --git a/mmv1/products/pubsub/go_Subscription.yaml b/mmv1/products/pubsub/go_Subscription.yaml index 6475ecb3fc16..e21927fbab71 100644 --- a/mmv1/products/pubsub/go_Subscription.yaml +++ b/mmv1/products/pubsub/go_Subscription.yaml @@ -22,9 +22,9 @@ references: 'Managing Subscriptions': 'https://cloud.google.com/pubsub/docs/admin#managing_subscriptions' api: 'https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions' docs: - note: 'You can retrieve the email of the Google Managed Pub/Sub Service Account used for forwarding -by using the `google_project_service_identity` resource. -' + note: | + You can retrieve the email of the Google Managed Pub/Sub Service Account used for forwarding + by using the `google_project_service_identity` resource. base_url: 'projects/{{project}}/subscriptions' create_verb: 'PUT' update_url: 'projects/{{project}}/subscriptions/{{name}}' diff --git a/mmv1/products/pubsub/go_Topic.yaml b/mmv1/products/pubsub/go_Topic.yaml index f22cb68f4d7e..8bf902dd89c2 100644 --- a/mmv1/products/pubsub/go_Topic.yaml +++ b/mmv1/products/pubsub/go_Topic.yaml @@ -21,9 +21,9 @@ references: 'Managing Topics': 'https://cloud.google.com/pubsub/docs/admin#managing_topics' api: 'https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics' docs: - note: 'You can retrieve the email of the Google Managed Pub/Sub Service Account used for forwarding -by using the `google_project_service_identity` resource. -' + note: | + You can retrieve the email of the Google Managed Pub/Sub Service Account used for forwarding + by using the `google_project_service_identity` resource. base_url: 'projects/{{project}}/topics' create_verb: 'PUT' update_url: 'projects/{{project}}/topics/{{name}}' diff --git a/mmv1/provider/template_data.go b/mmv1/provider/template_data.go index 63ab416c88f8..797064d39689 100644 --- a/mmv1/provider/template_data.go +++ b/mmv1/provider/template_data.go @@ -71,20 +71,21 @@ func subtract(a, b int) int { } var TemplateFunctions = template.FuncMap{ - "title": google.SpaceSeparatedTitle, - "replace": strings.Replace, - "camelize": google.Camelize, - "underscore": google.Underscore, - "plural": google.Plural, - "contains": strings.Contains, - "join": strings.Join, - "lower": strings.ToLower, - "upper": strings.ToUpper, - "dict": wrapMultipleParams, - "format2regex": google.Format2Regex, - "orderProperties": api.OrderProperties, - "hasPrefix": strings.HasPrefix, - "sub": subtract, + "title": google.SpaceSeparatedTitle, + "replace": strings.Replace, + "camelize": google.Camelize, + "underscore": google.Underscore, + "plural": google.Plural, + "contains": strings.Contains, + "join": strings.Join, + "lower": strings.ToLower, + "upper": strings.ToUpper, + "dict": wrapMultipleParams, + "format2regex": google.Format2Regex, + "orderProperties": api.OrderProperties, + "hasPrefix": strings.HasPrefix, + "sub": subtract, + "formatDocDescription": api.FormatDocDescription, } var GA_VERSION = "ga" diff --git a/mmv1/templates/terraform/property_documentation.html.markdown.tmpl b/mmv1/templates/terraform/property_documentation.html.markdown.tmpl index e791ca08df37..60dc8df96638 100644 --- a/mmv1/templates/terraform/property_documentation.html.markdown.tmpl +++ b/mmv1/templates/terraform/property_documentation.html.markdown.tmpl @@ -2,36 +2,36 @@ * `{{ underscore $.Name }}` - {{- if and (eq $.MinVersion "beta") (not (eq $.ResourceMetadata.MinVersion "beta")) }} {{- if $.Required }} - (Required, [Beta](https://terraform.io/docs/providers/google/guides/provider_versions.html){{ if $.DeprecationMessage }}, Deprecated {{ end }}) + (Required, [Beta](https://terraform.io/docs/providers/google/guides/provider_versions.html){{ if $.DeprecationMessage }}, Deprecated{{ end }}) {{- else if not $.Output }} - (Optional, [Beta](https://terraform.io/docs/providers/google/guides/provider_versions.html){{ if $.DeprecationMessage }}, Deprecated {{ end }}) + (Optional, [Beta](https://terraform.io/docs/providers/google/guides/provider_versions.html){{ if $.DeprecationMessage }}, Deprecated{{ end }}) {{- else if and $.Output $.ParentMetadata }} - (Output, [Beta](https://terraform.io/docs/providers/google/guides/provider_versions.html){{ if $.DeprecationMessage }}, Deprecated {{ end }}) + (Output, [Beta](https://terraform.io/docs/providers/google/guides/provider_versions.html){{ if $.DeprecationMessage }}, Deprecated{{ end }}) {{- else }} - ([Beta](https://terraform.io/docs/providers/google/guides/provider_versions.html){{ if $.DeprecationMessage }}, Deprecated {{ end }}) + ([Beta](https://terraform.io/docs/providers/google/guides/provider_versions.html){{ if $.DeprecationMessage }}, Deprecated{{ end }}) {{- end}} {{- else }} {{- if $.Required }} - (Required{{ if $.DeprecationMessage }}, Deprecated {{ end }}) + (Required{{ if $.DeprecationMessage }}, Deprecated{{ end }}) {{- else if not $.Output }} - (Optional{{ if $.DeprecationMessage }}, Deprecated {{ end }}) + (Optional{{ if $.DeprecationMessage }}, Deprecated{{ end }}) {{- else if and $.Output $.ParentMetadata }} - (Output{{ if $.DeprecationMessage }}, Deprecated {{ end }}) + (Output{{ if $.DeprecationMessage }}, Deprecated{{ end }}) {{- else if $.DeprecationMessage }} (Deprecated) {{- end}} {{- end }} - {{ $.Description }} + {{ formatDocDescription $.Description -}} {{- if and (and ($.IsA "Array") ($.ItemType.IsA "Enum")) (and (not $.Output) (not $.ItemType.SkipDocsValues))}} - {{- if not (or $.ItemType.DefaultValue (eq $.ItemType.DefaultValue "")) }} - Default value is [`{{ $.ItemType.DefaultValue }}`]. + {{- if $.ItemType.DefaultValue }} + Default value is `{{ $.ItemType.DefaultValue }}`. {{- end }} Each value may be one of: {{ $.ItemType.EnumValuesToString "`" false }}. {{- else if and ($.IsA "Enum") (and (not $.Output) (not (and $.ItemType $.ItemType.SkipDocsValues)))}} - {{- if not (or $.DefaultValue (eq $.DefaultValue "")) }} - Default value is [`{{ $.DefaultValue }}`]. + {{- if $.DefaultValue }} + Default value is `{{ $.DefaultValue }}`. {{- end }} - Possible values are: {{ $.EnumValuesToString "`" false }}. + Possible values are: {{ $.EnumValuesToString "`" false }}. {{- end }} {{- if $.Sensitive }} **Note**: This property is sensitive and will not be displayed in the plan. diff --git a/mmv1/templates/terraform/resource.go.tmpl b/mmv1/templates/terraform/resource.go.tmpl index c60a8ff2fe1a..54a9854728c0 100644 --- a/mmv1/templates/terraform/resource.go.tmpl +++ b/mmv1/templates/terraform/resource.go.tmpl @@ -742,7 +742,7 @@ func resource{{ $.ResourceName -}}Update(d *schema.ResourceData, meta interface{ log.Printf("[DEBUG] Updating {{ $.Name }} %q: %#v", d.Id(), obj) headers := make(http.Header) -{{ if $.UpdateMask -}} +{{- if $.UpdateMask -}} {{template "UpdateMask" $ -}} {{end}} {{- if $.CustomCode.PreUpdate -}} diff --git a/mmv1/templates/terraform/resource.html.markdown.tmpl b/mmv1/templates/terraform/resource.html.markdown.tmpl index 06d22f525203..a9bb6ee8ab17 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: |- - {{$.Description -}} + {{ formatDocDescription $.Description }} --- # {{$.TerraformName}} @@ -54,16 +54,15 @@ To get more information about {{$.Name}}, see: * [{{$title}}]({{$link}}) {{- end }} {{- end }} -{{- end }} +{{ end }} {{- if $.Docs.Warning}} ~> **Warning:** {{$.Docs.Warning}} {{- end }} {{- if $.Docs.Note}} - -~> **Note:** {{$.Docs.Note}} +~> **Note:** {{$.Docs.Note }} {{- end }} -{{ if $.SensitiveProps }} +{{- if $.SensitiveProps }} ~> **Warning:** All arguments including the following potentially sensitive values will be stored in the raw state as plain text: {{ $.SensitivePropsToString }}. [Read more about sensitive data in state](https://www.terraform.io/language/state/sensitive-data). @@ -188,4 +187,4 @@ $ terraform import {{$.TerraformName}}.default {{$idFormat}} ## User Project Overrides This resource supports [User Project Overrides](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference#user_project_override). -{{- end }} \ No newline at end of file +{{ end }} \ No newline at end of file