From bda80a6d813eec89cfdc796f16471acb702225f3 Mon Sep 17 00:00:00 2001 From: Cameron Thornton Date: Fri, 22 Mar 2024 16:26:06 -0500 Subject: [PATCH] Initial resource documentation templating (#10266) --- mmv1/api/product.go | 7 +++ mmv1/api/resource.go | 7 +++ mmv1/provider/template_data.go | 51 +++++++++---------- mmv1/provider/terraform.go | 10 ++-- .../terraform/resource.html.markdown.tmpl | 39 +++++++++++++- 5 files changed, 80 insertions(+), 34 deletions(-) diff --git a/mmv1/api/product.go b/mmv1/api/product.go index e3defe678c82..57aee0b50d54 100644 --- a/mmv1/api/product.go +++ b/mmv1/api/product.go @@ -211,6 +211,13 @@ func (p *Product) SetPropertiesBasedOnVersion(version *product.Version) { p.BaseUrl = version.BaseUrl } +func (p *Product) TerraformName() string { + if p.LegacyName != "" { + return google.Underscore(p.LegacyName) + } + return google.Underscore(p.Name) +} + // ==================== // Debugging Methods // ==================== diff --git a/mmv1/api/resource.go b/mmv1/api/resource.go index ad71a8eb23e8..b7a19a4df776 100644 --- a/mmv1/api/resource.go +++ b/mmv1/api/resource.go @@ -764,3 +764,10 @@ func (r Resource) HasZone() bool { func (r Resource) Lineage() string { return r.Name } + +func (r Resource) TerraformName() string { + if r.LegacyName != "" { + return r.LegacyName + } + return fmt.Sprintf("google_%s_%s", r.ProductMetadata.TerraformName(), google.Underscore(r.Name)) +} diff --git a/mmv1/provider/template_data.go b/mmv1/provider/template_data.go index 23ee5ebffd12..a52e6340d331 100644 --- a/mmv1/provider/template_data.go +++ b/mmv1/provider/template_data.go @@ -19,6 +19,7 @@ import ( "go/format" "log" "os" + "path/filepath" "strings" "text/template" @@ -74,40 +75,49 @@ func NewTemplateData(outputFolder string, version product.Version) *TemplateData } func (td *TemplateData) GenerateResourceFile(filePath string, resource api.Resource) { + td.GenerateFile(filePath, "templates/terraform/resource.go.tmpl", resource, true) +} + +func (td *TemplateData) GenerateDocumentationFile(filePath string, resource api.Resource) { + td.GenerateFile(filePath, "templates/terraform/resource.html.markdown.tmpl", resource, false) +} +func (td *TemplateData) GenerateFile(filePath, templatePath string, resource api.Resource, goFormat bool) { log.Printf("Generating %s", filePath) - tmpl, err := template.New("resource.go.tmpl").Funcs(TemplateFunctions).ParseFiles( - "templates/terraform/resource.go.tmpl", + templateFileName := filepath.Base(templatePath) + + tmpl, err := template.New(templateFileName).Funcs(TemplateFunctions).ParseFiles( + templatePath, ) if err != nil { glog.Exit(err) } contents := bytes.Buffer{} - if err = tmpl.ExecuteTemplate(&contents, "resource.go.tmpl", resource); err != nil { + if err = tmpl.ExecuteTemplate(&contents, templateFileName, resource); err != nil { glog.Exit(err) } - if err != nil { - glog.Exit(err) + sourceByte := contents.Bytes() + // Replace import path based on version (beta/alpha) + if td.TerraformResourceDirectory != "google" { + sourceByte = bytes.Replace(sourceByte, []byte("github.com/hashicorp/terraform-provider-google/google"), []byte(td.TerraformProviderModule+"/"+td.TerraformResourceDirectory), -1) } - formatted, err := td.FormatSource(&contents) - if err != nil { - glog.Error(fmt.Errorf("error formatting %s", filePath)) + if goFormat { + sourceByte, err = format.Source(sourceByte) + if err != nil { + glog.Error(fmt.Errorf("error formatting %s", filePath)) + } } - err = os.WriteFile(filePath, formatted, 0644) + err = os.WriteFile(filePath, sourceByte, 0644) if err != nil { glog.Exit(err) } } -func (td *TemplateData) GenerateDocumentationFile(filePath string, resource api.Resource) { - -} - // # path is the output name of the file // # template is used to determine metadata about the file based on how it is // # generated @@ -178,18 +188,3 @@ func (td *TemplateData) GenerateDocumentationFile(filePath string, resource api. // end // end // end - -func (td *TemplateData) FormatSource(source *bytes.Buffer) ([]byte, error) { - sourceByte := source.Bytes() - // Replace import path based on version (beta/alpha) - if td.TerraformResourceDirectory != "google" { - sourceByte = bytes.Replace(sourceByte, []byte("github.com/hashicorp/terraform-provider-google/google"), []byte(td.TerraformProviderModule+"/"+td.TerraformResourceDirectory), -1) - } - - output, err := format.Source(sourceByte) - if err != nil { - return []byte(source.String()), err - } - - return output, nil -} diff --git a/mmv1/provider/terraform.go b/mmv1/provider/terraform.go index 54a91b38f208..9c3acd229f05 100644 --- a/mmv1/provider/terraform.go +++ b/mmv1/provider/terraform.go @@ -127,18 +127,20 @@ func (t *Terraform) GenerateResource(object api.Resource, templateData TemplateD if generateCode { productName := t.Product.ApiName targetFolder := path.Join(outputFolder, t.FolderName(), "services", productName) - if err := os.MkdirAll(targetFolder, os.ModePerm); err != nil { log.Println(fmt.Errorf("error creating parent directory %v: %v", targetFolder, err)) } - targetFilePath := path.Join(targetFolder, fmt.Sprintf("resource_%s.go", t.FullResourceName(object))) - templateData.GenerateResourceFile(targetFilePath, object) } if generateDocs { - templateData.GenerateDocumentationFile(outputFolder, object) + targetFolder := path.Join(outputFolder, "website", "docs", "r") + if err := os.MkdirAll(targetFolder, os.ModePerm); err != nil { + log.Println(fmt.Errorf("error creating parent directory %v: %v", targetFolder, err)) + } + targetFilePath := path.Join(targetFolder, fmt.Sprintf("%s.html.markdown", t.FullResourceName(object))) + templateData.GenerateDocumentationFile(targetFilePath, object) } } diff --git a/mmv1/templates/terraform/resource.html.markdown.tmpl b/mmv1/templates/terraform/resource.html.markdown.tmpl index 80a5c85d93dd..296092c6eba9 100644 --- a/mmv1/templates/terraform/resource.html.markdown.tmpl +++ b/mmv1/templates/terraform/resource.html.markdown.tmpl @@ -25,6 +25,41 @@ # .github/CONTRIBUTING.md. # # ---------------------------------------------------------------------------- - -{{$.ProductMetadata.Name}} {{$.Name}} +subcategory: "{{$.ProductMetadata.DisplayName}}" +description: |- + {{$.Description -}} --- + +# {{$.TerraformName}} +{{- if $.DeprecationMessage }} +~> **Warning:** {{$.DeprecationMessage}} +{{- end }} + +{{$.Description}} + +{{- if eq $.MinVersion "beta"}} +~> **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}} +To get more information about {{$.Name}}, see: + + {{- if $.References.Api}} + +* [API documentation]({{$.References.Api}}) + {{- end }} + {{- if $.References.Guides}} +* How-to Guides + {{- range $title, $link := $.References.Guides }} + * [{{$title}}]({{$link}}) + {{- end }} + {{- end }} +{{- end }} +{{- if $.Docs.Warning}} + +~> **Warning:** {{$.Docs.Warning}} +{{- end }} +{{- if $.Docs.Note}} + +~> **Note:** {{$.Docs.Note}} +{{- end }} \ No newline at end of file