Merge pull request #2 from terraform-tencentcloud/gendoc

 add terraform docs generator

Author: Himer

gendoc/README.md

@@ -0,0 +1,130 @@
+# Terraform docs generator
+
+## Why
+
+经过观察，大部分友商的 Terraform Plugins 文档都是人肉编写的，它们或多或少都有这样的问题：
+
+* 风格难以统一，比如：章节顺序、空行数量、命名风格在不同产品之间有明显差异
+* 细节存在问题，比如：空格数量、缩进多少、中下划线出现不统一，甚至还夹带中文符号
+* 内容存在问题，比如：参数必须或选填跟代码不一致，列表中漏写参数或属性
+
+然而，最大的问题是写文档需要消耗大量的时间和精力去整理内容整理格式，最后还发现总有这样那样的问题，甚至有时还会文档更新不及时。
+机器可以一如始终，完全无误差地完成各项有规律的重复性工作，而且不会出错，自动地生成文档也是 golang 所推动的标准做法。
+
+## How
+
+Terraform Plugins 文档，不管是 resource 还是 data_source，主要都分以下这几个主题：
+
+* name
+* description
+* example usage
+* argument reference
+* attributes reference
+
+### name
+
+name 是 resource 及 data_source 的完整命名，它来源于 Provider 的 DataSourcesMap(data_source) 及 ResourcesMap(resource) 定义。
+例如以下 DataSourcesMap 中的 tencentcloud_vpc 与 tencentcloud_mysql_instance 就是一个标准的 name(for resource or data_source)：
+
+```go
+DataSourcesMap: map[string]*schema.Resource{
+    "tencentcloud_vpc": dataSourceTencentCloudVpc(),
+    "tencentcloud_mysql_instance": dataSourceTencentCloudMysqlInstance(),
+}
+```
+
+### description & example usage
+
+description 包括一个用于表头的一句话描述，与一个用于正文的详细说明。
+example usage 则是一个或几个使用示例。
+
+description & example usage 需要在对应 resource 及 data_source 定义的文件中出现，它是符合 golang 标准文档注释的写法。例如：
+
+    /*
+    Use this data source to get information about a MySQL instance.
+    \n
+    ~> **NOTE:** The terminate operation of mysql does NOT take effect immediately，maybe takes for several hours.
+    \n
+    Example Usage
+    \n
+    ```hcl
+    data "tencentcloud_mysql_instance" "database"{
+      mysql_id = "my-test-database"
+      result_output_file = "mytestpath"
+    }
+    ```
+    */
+    package tencentcloud
+
+以上注释的格式要求如下：
+
+    /*
+    一句话描述
+    \n
+    在一句话描述基础上的补充描述，可以比较详细地说明各项内容，可以有多个段落。
+    \n
+    Example Usage
+    \n
+    Example Usage 是 必须的，在 Example Usage 以下的内容都会当成 Example Usage 填充到文档中。
+    */
+    package tencentcloud
+
+符合以上要求的注释将会自动提取并填写到文档中的对应位置。
+
+### argument reference & attributes reference
+
+Terraform 用 schema.Schema 来描述 argument reference & attributes reference，每个 schema.Schema 都会有一个 Description 字段。
+如果 Description 的内容不为空，那么这个 schema.Schema 将会被认为是需要写到文档里面的，如果 Optional 或 Required 设置了，它会被认为是一个参数，如果 Computed 为 true 则认为是一个属性。例如：
+
+#### argument
+
+```go
+map[string]*schema.Schema{
+    "instance_name": {
+        Type:         schema.TypeString,
+        Required:     true,
+        ValidateFunc: validateStringLengthInRange(1, 100),
+        Description:  "The name of a mysql instance.",
+    },
+}
+```
+
+#### attributes
+
+```go
+map[string]*schema.Schema{
+    "mysql_id": {
+        Type:     schema.TypeString,
+        Computed: true,
+        Description:  "Instance ID, such as cdb-c1nl9rpv. It is identical to the instance ID displayed in the database console page.",
+    },
+}
+```
+
+#### attributes list
+
+属性中 Type 为 schema.TypeList 的 schema.Schema 也是支持的，它会被认为是一个列表，里面的子 schema.Schema 会依次列出填充到文档中。
+
+```go
+map[string]*schema.Schema{
+    "instance_list": {
+        Type:     schema.TypeList,
+        Computed: true,
+        Description: "A list of instances. Each element contains the following attributes:",
+        Elem: &schema.Resource{
+            Schema: map[string]*schema.Schema{
+                "mysql_id": {
+                    Type:     schema.TypeString,
+                    Computed: true,
+                    Description:  "Instance ID, such as cdb-c1nl9rpv. It is identical to the instance ID displayed in the database console page.",
+                },
+                "instance_name": {
+                    Type:     schema.TypeString,
+                    Computed: true,
+                    Description:  "Name of mysql instance.",
+                },
+            }
+        }
+    }
+}
+```

gendoc/main.go

@@ -0,0 +1,169 @@
+package main
+
+import (
+	"fmt"
+	"github.com/hashicorp/terraform/helper/schema"
+	cloud "github.com/terraform-providers/terraform-provider-tencentcloud/tencentcloud"
+	"go/parser"
+	"go/token"
+	"log"
+	"os"
+	"path/filepath"
+	"reflect"
+	"runtime"
+	"sort"
+	"strings"
+	"text/template"
+)
+
+const (
+	cloudMark      = "tencentcloud"
+	cloudTitle     = "TencentCloud"
+	cloudMarkShort = "tc"
+	docRoot        = "../website/docs"
+)
+
+func main() {
+	provider := cloud.Provider()
+	vProvider := runtime.FuncForPC(reflect.ValueOf(cloud.Provider).Pointer())
+
+	fname, _ := vProvider.FileLine(0)
+	fpath := filepath.Dir(fname)
+	log.Printf("generating doc from: %s\n", fpath)
+
+	// DataSourcesMap
+	for k, v := range provider.DataSourcesMap {
+		genDoc("data_source", fpath, k, v)
+	}
+
+	// ResourcesMap
+	for k, v := range provider.ResourcesMap {
+		genDoc("resource", fpath, k, v)
+	}
+}
+
+// genDoc generating doc for resource
+func genDoc(dtype, fpath, name string, resource *schema.Resource) {
+	data := map[string]string{
+		"name":              name,
+		"dtype":             strings.Replace(dtype, "_", "", -1),
+		"resource":          name[len(cloudMark)+1:],
+		"cloud_mark":        cloudMark,
+		"cloud_title":       cloudTitle,
+		"example":           "",
+		"description":       "",
+		"description_short": "",
+	}
+
+	fname := fmt.Sprintf("%s_%s_%s.go", dtype, cloudMarkShort, data["resource"])
+	log.Printf("get description from file: %s\n", fname)
+
+	description, err := getFileDescription(fmt.Sprintf("%s/%s", fpath, fname))
+	if err != nil {
+		log.Printf("[SKIP]get description failed, skip: %s", err)
+		return
+	}
+
+	description = strings.TrimSpace(description)
+	if description == "" {
+		log.Printf("[SKIP]description empty, skip: %s\n", fname)
+		return
+	}
+
+	pos := strings.Index(description, "\nExample Usage\n")
+	if pos != -1 {
+		data["example"] = strings.TrimSpace(description[pos+15:])
+		description = strings.TrimSpace(description[:pos])
+	} else {
+		log.Printf("[SKIP]example usage missing, skip: %s\n", fname)
+		return
+	}
+
+	data["description"] = description
+	pos = strings.Index(description, "\n\n")
+	if pos != -1 {
+		data["description_short"] = strings.TrimSpace(description[:pos])
+	} else {
+		data["description_short"] = description
+	}
+
+	requiredArgs := []string{}
+	optionalArgs := []string{}
+	attributes := []string{}
+
+	for k, v := range resource.Schema {
+		if v.Description == "" {
+			continue
+		}
+		if v.Required {
+			opt := "Required"
+			if v.ForceNew {
+				opt += ", ForceNew"
+			}
+			requiredArgs = append(requiredArgs, fmt.Sprintf("* `%s` - (%s) %s", k, opt, v.Description))
+		} else if v.Optional {
+			opt := "Optional"
+			if v.ForceNew {
+				opt += ", ForceNew"
+			}
+			optionalArgs = append(optionalArgs, fmt.Sprintf("* `%s` - (%s) %s", k, opt, v.Description))
+		} else if v.Computed {
+			if v.Type == schema.TypeList {
+				listAttributes := []string{}
+				for kk, vv := range v.Elem.(*schema.Resource).Schema {
+					if vv.Description == "" {
+						continue
+					}
+					if v.Computed {
+						listAttributes = append(listAttributes, fmt.Sprintf("  * `%s` - %s", kk, vv.Description))
+					}
+				}
+				slistAttributes := ""
+				sort.Strings(listAttributes)
+				if len(listAttributes) > 0 {
+					slistAttributes = "\n" + strings.Join(listAttributes, "\n")
+				}
+				attributes = append(attributes, fmt.Sprintf("* `%s` - %s%s", k, v.Description, slistAttributes))
+			} else {
+				attributes = append(attributes, fmt.Sprintf("* `%s` - %s", k, v.Description))
+			}
+		}
+	}
+
+	sort.Strings(requiredArgs)
+	sort.Strings(optionalArgs)
+	sort.Strings(attributes)
+
+	requiredArgs = append(requiredArgs, optionalArgs...)
+	data["arguments"] = strings.Join(requiredArgs, "\n")
+	data["attributes"] = strings.Join(attributes, "\n")
+
+	fname = fmt.Sprintf("%s/%s/%s.html.markdown", docRoot, dtype[0:1], data["resource"])
+	fd, err := os.OpenFile(fname, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0644)
+	if err != nil {
+		log.Printf("[FAIL]open file %s failed: %s", fname, err)
+		return
+	}
+
+	defer fd.Close()
+	t := template.Must(template.New("t").Parse(docTPL))
+	err = t.Execute(fd, data)
+	if err != nil {
+		log.Printf("[FAIL]write file %s failed: %s", fname, err)
+		return
+	}
+
+	log.Printf("[SUCC]write doc to file success: %s", fname)
+}
+
+// getFileDescription get description from go file
+func getFileDescription(fname string) (string, error) {
+	fset := token.NewFileSet()
+
+	parsedAst, err := parser.ParseFile(fset, fname, nil, parser.ParseComments)
+	if err != nil {
+		return "", err
+	}
+
+	return parsedAst.Doc.Text(), nil
+}

gendoc/template.go

@@ -0,0 +1,33 @@
+package main
+
+const (
+	docTPL = `---
+layout: "{{.cloud_mark}}"
+page_title: "{{.cloud_title}}: {{.name}}"
+sidebar_current: "docs-{{.cloud_mark}}-{{.dtype}}-{{.resource}}"
+description: |-
+  {{.description_short}}
+---
+
+# {{.name}}
+
+{{.description}}
+
+## Example Usage
+
+{{.example}}
+
+## Argument Reference
+
+The following arguments are supported:
+
+{{.arguments}}
+
+## Attributes Reference
+
+In addition to all arguments above, the following attributes are exported:
+
+{{.attributes}}
+
+`
+)

go.mod

@@ -23,7 +23,6 @@ require (
 	github.com/zqfan/tencentcloud-sdk-go v0.0.0-20181105105106-4c76f78ff2e6
 	golang.org/x/crypto v0.0.0-20190313024323-a1f597ede03a // indirect
 	golang.org/x/net v0.0.0-20190313220215-9f648a60d977 // indirect
-	gopkg.in/natefinch/lumberjack.v2 v2.0.0
 	labix.org/v2/mgo v0.0.0-20140701140051-000000000287 // indirect
 	launchpad.net/gocheck v0.0.0-20140225173054-000000000087 // indirect
 )

go.sum

@@ -446,8 +446,6 @@ gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8
 gopkg.in/cheggaaa/pb.v1 v1.0.27/go.mod h1:V/YB90LKu/1FcN3WVnfiiE5oMCibMjukxqG/qStrOgw=
 gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
 gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
-gopkg.in/natefinch/lumberjack.v2 v2.0.0 h1:1Lc07Kr7qY4U2YPouBjpCLxpiyxIVoxqXgkXLknAOE8=
-gopkg.in/natefinch/lumberjack.v2 v2.0.0/go.mod h1:l0ndWWf7gzL7RNwBG7wST/UCcT4T24xpD6X8LsfU/+k=
 gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
 gopkg.in/yaml.v2 v2.0.0-20170407172122-cd8b52f8269e/go.mod h1:JAlM8MvJe8wmxCU4Bli9HhUf9+ttbYbLASfIpnQbh74=
 gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=