adjust doc gen to support the usage title and usage description (#1932)

* adjust doc gen to support the usage title and usage description

* adjust README.md

Author: lyu571

gendoc/README.md

@@ -38,7 +38,7 @@ DataSourcesMap: map[string]*schema.Resource{
 description 包括一个用于表头的一句话描述，与一个用于正文的详细说明。
 example usage 则是一个或几个使用示例。
 
-description & example usage 需要在对应 resource 及 data_source 定义的文件中出现，它是符合 golang 标准文档注释的写法。例如：
+description & example usage & usage description 需要在对应 resource 及 data_source 定义的文件中出现，它是符合 golang 标准文档注释的写法。例如：
 
     /*
     Use this data source to get information about a MySQL instance.
@@ -47,6 +47,21 @@ description & example usage 需要在对应 resource 及 data_source 定义的
     \n
     Example Usage
     \n
+    Scenario1 title
+    \n
+    Description of the Scenario1
+    \n
+    ```hcl
+    data "tencentcloud_mysql_instance" "database"{
+      mysql_id = "my-test-database"
+      result_output_file = "mytestpath"
+    }
+    ```
+    \n
+    Scenario2 title
+    \n
+    Description of the Scenario2
+    \n
     ```hcl
     data "tencentcloud_mysql_instance" "database"{
       mysql_id = "my-test-database"
@@ -65,7 +80,16 @@ description & example usage 需要在对应 resource 及 data_source 定义的
     \n
     Example Usage
     \n
-    Example Usage 是必须的，在 Example Usage 以下的内容都会当成 Example Usage 填充到文档中。
+    Example Usage 是必须的，在 Example Usage 以下的内容都会填充到文档中。
+    Example Usage 由一个到多个Scenario(场景)构成。
+    每个Scenario 由 Scenario title 和 Scenario description 构成。
+    \n
+    Usage1 title
+    \n
+    Description of the Usage1
+    \n
+    Scenario title 是必须的。
+    Scenario description 是可选的，可以根据情况填写。
     */
     package tencentcloud
 

gendoc/main.go

@@ -28,8 +28,9 @@ const (
 )
 
 var (
-	hclMatch  = regexp.MustCompile("(?si)([^`]+)?```(hcl)?(.*?)```")
-	bigSymbol = regexp.MustCompile("([\u007F-\uffff])")
+	hclMatch   = regexp.MustCompile("(?si)([^`]+)?```(hcl)?(.*?)```")
+	usageMatch = regexp.MustCompile(`(?s)(?m)^([^ \n].*?)(?:\n{2}|$)(.*)`)
+	bigSymbol  = regexp.MustCompile("([\u007F-\uffff])")
 )
 
 func main() {
@@ -407,16 +408,32 @@ func formatHCL(s string) string {
 		for _, v := range m {
 			p := strings.TrimSpace(v[1])
 			if p != "" {
-				p = fmt.Sprintf("\n%s\n\n", p)
+				p = formatUsageDesc(p)
 			}
 			b := hclwrite.Format([]byte(strings.TrimSpace(v[3])))
-			rr = append(rr, fmt.Sprintf("%s```hcl\n%s\n```", p, string(b)))
+			rr = append(rr, fmt.Sprintf("\n%s\n\n```hcl\n%s\n```", p, string(b)))
 		}
 	}
 
 	return strings.TrimSpace(strings.Join(rr, "\n"))
 }
 
+func formatUsageDesc(s string) string {
+	var rr []string
+	s = strings.TrimSpace(s)
+	m := usageMatch.FindAllStringSubmatch(s, -1)
+
+	for _, v := range m {
+		title := strings.TrimSpace(v[1])
+		descp := strings.TrimSpace(v[2])
+
+		rr = append(rr, fmt.Sprintf("### %s\n\n%s", title, descp))
+	}
+
+	ret := strings.TrimSpace(strings.Join(rr, "\n\n"))
+	return ret
+}
+
 // checkDescription check description format
 func checkDescription(k, s string) {
 	if s == "" {

website/docs/d/cbs_storages.html.markdown

@@ -20,7 +20,7 @@ data "tencentcloud_cbs_storages" "storages" {
 }
 ```
 
-The following snippet shows the new supported query params
+### The following snippet shows the new supported query params
 
 ```hcl
 data "tencentcloud_cbs_storages" "whats_new" {

website/docs/d/cynosdb_instance_slow_queries.html.markdown

@@ -13,7 +13,7 @@ Use this data source to query detailed information of cynosdb instance_slow_quer
 
 ## Example Usage
 
-Query slow queries of instance
+### Query slow queries of instance
 
 ```hcl
 variable "cynosdb_cluster_id" {
@@ -32,7 +32,7 @@ data "tencentcloud_cynosdb_instance_slow_queries" "instance_slow_queries" {
 }
 ```
 
-Query slow queries by time range
+### Query slow queries by time range
 
 ```hcl
 variable "cynosdb_cluster_id" {
@@ -48,7 +48,7 @@ data "tencentcloud_cynosdb_instance_slow_queries" "instance_slow_queries" {
 }
 ```
 
-Query slow queries by user and db name
+### Query slow queries by user and db name
 
 ```hcl
 variable "cynosdb_cluster_id" {

website/docs/d/dbbrain_top_space_tables.html.markdown

@@ -13,7 +13,7 @@ Use this data source to query detailed information of dbbrain top_space_tables
 
 ## Example Usage
 
-Sort by PhysicalFileSize
+### Sort by PhysicalFileSize
 
 ```hcl
 data "tencentcloud_dbbrain_top_space_tables" "top_space_tables" {
@@ -23,7 +23,7 @@ data "tencentcloud_dbbrain_top_space_tables" "top_space_tables" {
 }
 ```
 
-Sort by TotalLength
+### Sort by TotalLength
 
 ```hcl
 data "tencentcloud_dbbrain_top_space_tables" "top_space_tables" {

website/docs/d/dnspod_records.html.markdown

@@ -24,7 +24,7 @@ output "result" {
 }
 ```
 
-Use verbose filter
+### Use verbose filter
 
 ```hcl
 data "tencentcloud_dnspod_records" "record" {

website/docs/r/api_gateway_service.html.markdown

@@ -13,7 +13,7 @@ Use this resource to create API gateway service.
 
 ## Example Usage
 
-Shared Service
+### Shared Service
 
 ```hcl
 resource "tencentcloud_api_gateway_service" "service" {
@@ -32,7 +32,7 @@ resource "tencentcloud_api_gateway_service" "service" {
 }
 ```
 
-Exclusive Service
+### Exclusive Service
 
 ```hcl
 resource "tencentcloud_api_gateway_service" "service" {

website/docs/r/as_scaling_config.html.markdown

@@ -43,7 +43,7 @@ resource "tencentcloud_as_scaling_config" "launch_configuration" {
 }
 ```
 
-Using SPOT charge type
+### Using SPOT charge type
 
 ```hcl
 resource "tencentcloud_as_scaling_config" "launch_configuration" {

website/docs/r/cam_role.html.markdown

@@ -13,7 +13,7 @@ Provides a resource to create a CAM role.
 
 ## Example Usage
 
-Create normally
+### Create normally
 
 ```hcl
 resource "tencentcloud_cam_role" "foo" {
@@ -40,7 +40,7 @@ EOF
 }
 ```
 
-Create with SAML provider
+### Create with SAML provider
 
 ```hcl
 resource "tencentcloud_cam_role" "boo" {

website/docs/r/ccn.html.markdown

@@ -13,7 +13,7 @@ Provides a resource to create a CCN instance.
 
 ## Example Usage
 
-Create a prepaid CCN
+### Create a prepaid CCN
 
 ```hcl
 resource "tencentcloud_ccn" "main" {
@@ -25,7 +25,7 @@ resource "tencentcloud_ccn" "main" {
 }
 ```
 
-Create a post-paid regional export speed limit type CCN
+### Create a post-paid regional export speed limit type CCN
 
 ```hcl
 resource "tencentcloud_ccn" "main" {
@@ -37,7 +37,7 @@ resource "tencentcloud_ccn" "main" {
 }
 ```
 
-Create a post-paid inter-regional rate limit type CNN
+### Create a post-paid inter-regional rate limit type CNN
 
 ```hcl
 resource "tencentcloud_ccn" "main" {