adjust doc gen to support the usage title and usage description

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" {

website/docs/r/ccn_bandwidth_limit.html.markdown

@@ -13,7 +13,7 @@ Provides a resource to limit CCN bandwidth.
 
 ## Example Usage
 
-Set the upper limit of regional outbound bandwidth
+### Set the upper limit of regional outbound bandwidth
 
 ```hcl
 variable "other_region1" {
@@ -33,7 +33,7 @@ resource "tencentcloud_ccn_bandwidth_limit" "limit1" {
 }
 ```
 
-Set the upper limit between regions
+### Set the upper limit between regions
 
 ```hcl
 variable "other_region1" {

website/docs/r/cdn_domain.html.markdown

@@ -48,7 +48,7 @@ resource "tencentcloud_cdn_domain" "foo" {
 }
 ```
 
-Example Usage of cdn uses cache and request headers
+### Example Usage of cdn uses cache and request headers
 
 ```hcl
 resource "tencentcloud_cdn_domain" "foo" {
@@ -105,7 +105,7 @@ resource "tencentcloud_cdn_domain" "foo" {
 }
 ```
 
-Example Usage of COS bucket url as origin
+### Example Usage of COS bucket url as origin
 
 ```hcl
 resource "tencentcloud_cos_bucket" "bucket" {

website/docs/r/cdn_url_purge.html.markdown

@@ -21,7 +21,7 @@ resource "tencentcloud_cdn_url_purge" "foo" {
 }
 ```
 
-argument to request new purge task with same urls
+### argument to request new purge task with same urls
 
 ```hcl
 resource "tencentcloud_cdn_url_purge" "foo" {

website/docs/r/cdn_url_push.html.markdown

@@ -19,7 +19,7 @@ resource "tencentcloud_cdn_url_push" "foo" {
 }
 ```
 
-argument to request new push task with same urls
+### argument to request new push task with same urls
 
 ```hcl
 resource "tencentcloud_cdn_url_push" "foo" {

website/docs/r/cfs_auto_snapshot_policy.html.markdown

@@ -13,7 +13,7 @@ Provides a resource to create a cfs auto_snapshot_policy
 
 ## Example Usage
 
-use day of week
+### use day of week
 
 ```hcl
 resource "tencentcloud_cfs_auto_snapshot_policy" "auto_snapshot_policy" {
@@ -24,7 +24,7 @@ resource "tencentcloud_cfs_auto_snapshot_policy" "auto_snapshot_policy" {
 }
 ```
 
-use day of month
+### use day of month
 
 ```hcl
 resource "tencentcloud_cfs_auto_snapshot_policy" "auto_snapshot_policy" {
@@ -35,7 +35,7 @@ resource "tencentcloud_cfs_auto_snapshot_policy" "auto_snapshot_policy" {
 }
 ```
 
-use interval days
+### use interval days
 
 ```hcl
 resource "tencentcloud_cfs_auto_snapshot_policy" "auto_snapshot_policy" {

website/docs/r/ckafka_acl.html.markdown

@@ -13,7 +13,7 @@ Provides a resource to create a Ckafka Acl.
 
 ## Example Usage
 
-Ckafka Acl
+### Ckafka Acl
 
 ```hcl
 resource "tencentcloud_ckafka_acl" "foo" {

website/docs/r/ckafka_instance.html.markdown

@@ -15,7 +15,7 @@ Use this resource to create ckafka instance.
 
 ## Example Usage
 
-Basic Instance
+### Basic Instance
 
 ```hcl
 variable "vpc_id" {
@@ -58,7 +58,7 @@ resource "tencentcloud_ckafka_instance" "kafka_instance" {
 }
 ```
 
-Multi zone Instance
+### Multi zone Instance
 
 ```hcl
 variable "vpc_id" {

website/docs/r/ckafka_user.html.markdown

@@ -13,7 +13,7 @@ Provides a resource to create a Ckafka user.
 
 ## Example Usage
 
-Ckafka User
+### Ckafka User
 
 ```hcl
 resource "tencentcloud_ckafka_user" "foo" {

website/docs/r/clb_instance.html.markdown

@@ -13,7 +13,7 @@ Provides a resource to create a CLB instance.
 
 ## Example Usage
 
-INTERNAL CLB
+### INTERNAL CLB
 
 ```hcl
 resource "tencentcloud_clb_instance" "internal_clb" {
@@ -29,7 +29,7 @@ resource "tencentcloud_clb_instance" "internal_clb" {
 }
 ```
 
-OPEN CLB
+### OPEN CLB
 
 ```hcl
 resource "tencentcloud_clb_instance" "open_clb" {
@@ -47,7 +47,7 @@ resource "tencentcloud_clb_instance" "open_clb" {
 }
 ```
 
-Default enable
+### Default enable
 
 ```hcl
 resource "tencentcloud_subnet" "subnet" {
@@ -90,7 +90,7 @@ resource "tencentcloud_clb_instance" "open_clb" {
 }
 ```
 
-CREATE multiple instance
+### CREATE multiple instance
 
 ```hcl
 resource "tencentcloud_clb_instance" "open_clb1" {
@@ -100,7 +100,7 @@ resource "tencentcloud_clb_instance" "open_clb1" {
 }
 ```
 
-CREATE instance with log
+### CREATE instance with log
 
 ```hcl
 resource "tencentcloud_vpc" "vpc_test" {