Skip to content

Commit

Permalink
go rewrite - fix some more documentation diffs (GoogleCloudPlatform#1…
Browse files Browse the repository at this point in the history
c2thorn authored May 30, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent fd55ea7 commit 78c5509
Showing 8 changed files with 79 additions and 155 deletions.
12 changes: 12 additions & 0 deletions mmv1/api/resource.go
Original file line number Diff line number Diff line change
@@ -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)
}
142 changes: 27 additions & 115 deletions mmv1/api/resource/examples.go
Original file line number Diff line number Diff line change
@@ -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": "[email protected]",
"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: '[email protected]',
// 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
6 changes: 3 additions & 3 deletions mmv1/products/pubsub/go_Subscription.yaml
Original file line number Diff line number Diff line change
@@ -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}}'
6 changes: 3 additions & 3 deletions mmv1/products/pubsub/go_Topic.yaml
Original file line number Diff line number Diff line change
@@ -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}}'
29 changes: 15 additions & 14 deletions mmv1/provider/template_data.go
Original file line number Diff line number Diff line change
@@ -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"
26 changes: 13 additions & 13 deletions mmv1/templates/terraform/property_documentation.html.markdown.tmpl
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion mmv1/templates/terraform/resource.go.tmpl
Original file line number Diff line number Diff line change
@@ -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 -}}
11 changes: 5 additions & 6 deletions mmv1/templates/terraform/resource.html.markdown.tmpl
Original file line number Diff line number Diff line change
@@ -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 }}
{{ end }}

0 comments on commit 78c5509

Please sign in to comment.