Initial resource documentation templating (GoogleCloudPlatform#10266)

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
 // ====================

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

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

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

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