Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

go rewrite - fix some more documentation diffs #10834

Merged
merged 2 commits into from
May 30, 2024
+79 −155
Merged

go rewrite - fix some more documentation diffs #10834

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c83d5e6
go rewrite - fix some documentation diffs
c2thorn May 30, 2024
b27fb3c
Add comment
c2thorn May 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions mmv1/api/resource.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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 {
Expand Down Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions mmv1/products/pubsub/go_Subscription.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}}'
Expand Down
6 changes: 3 additions & 3 deletions mmv1/products/pubsub/go_Topic.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}}'
Expand Down
29 changes: 15 additions & 14 deletions mmv1/provider/template_data.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
26 changes: 13 additions & 13 deletions mmv1/templates/terraform/property_documentation.html.markdown.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion mmv1/templates/terraform/resource.go.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 -}}
Expand Down
11 changes: 5 additions & 6 deletions mmv1/templates/terraform/resource.html.markdown.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
# ----------------------------------------------------------------------------
subcategory: "{{$.ProductMetadata.DisplayName}}"
description: |-
{{$.Description -}}
{{ formatDocDescription $.Description }}
---

# {{$.TerraformName}}
Expand All @@ -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).
Expand Down Expand Up @@ -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 }}