Merge pull request #48 from Awlie/docs/restructure-docs

docs: documentation update and how it's generated

README.md

@@ -101,6 +101,11 @@ make generate-docs
 - To view the documentation:
   Paste `/docs` Markdown file content into https://registry.terraform.io/tools/doc-preview
 
+Note: The description and the subcategory of resource are now automatically generated from the resource's `Description` field within the go file, similar to how the schema's arguments are generated.
+This allows you to define resources descriptions with `My Subcategory --- The description of my resource` and have the subcategory and description filled in correctly. It also works if you don't provide a subcategory, in that case, it will just populate the description.  
+The only caveat is that you can't use additional `---` in your description.  
+Imports and examples are automatically filled in if they are placed and named correctly in `examples/{type}/{resource_name}`
+
 ## Contributing
 
 Refer to [CONTRIBUTING.md](./CONTRIBUTING.md)

cancom/services/cmsmgw/resource_connection.go

@@ -15,6 +15,7 @@ import (
 
 func resourceConnection() *schema.Resource {
 	return &schema.Resource{
+		Description:   "Managed Gateway --- Represents a connection resource.",
 		CreateContext: resourceConnectionCreate,
 		ReadContext:   resourceConnectionRead,
 		UpdateContext: resourceConnectionUpdate,

cancom/services/cmsmgw/resource_gateway.go

@@ -15,6 +15,7 @@ import (
 
 func resourceGateway() *schema.Resource {
 	return &schema.Resource{
+		Description:   "Managed Gateway --- Represents a gateway resource.",
 		CreateContext: resourceGatewayCreate,
 		ReadContext:   resourceGatewayRead,
 		UpdateContext: resourceGatewayUpdate,

cancom/services/cmsmgw/resource_translation.go

@@ -15,6 +15,7 @@ import (
 
 func resourceTranslation() *schema.Resource {
 	return &schema.Resource{
+		Description:   "Managed Gateway --- Represents a translation resource.",
 		CreateContext: resourceTranslationCreate,
 		ReadContext:   resourceTranslationRead,
 		UpdateContext: resourceTranslationUpdate,

cancom/services/dns/resource_record.go

@@ -18,6 +18,7 @@ var resourceRecordApiLock = util.NewLock()
 
 func resourceRecord() *schema.Resource {
 	return &schema.Resource{
+		Description:   "DNS --- Defines a DNS record.",
 		CreateContext: resourceRecordCreate,
 		ReadContext:   resourceRecordRead,
 		UpdateContext: resourceRecordUpdate,

cancom/services/dynamic-cloud/resource_vpc_project.go

@@ -19,6 +19,11 @@ func resourceVpcProject() *schema.Resource {
 	nameRegex := regexp.MustCompile("[a-zA-Zß0-9-_]+")
 	commentRegex := regexp.MustCompile("[a-zA-Zß0-9-_.,;:?!#+ ]+")
 	return &schema.Resource{
+		Description: `Dynamic Cloud --- Manage Dynamic Cloud VPC Projects lifecycle
+
+This creates a Virtual Private Cloud (VPC) Project with the specified name and the optional comment. The parameter ` + "`users`" + ` can be used to specify which user should get access to the VPC Project.
+
+!> Changing the ` + "`name` or `comment`" + ` will force the VPC Project to be recreated, i.e. all resources in the VPC Project will be deleted.`,
 		CreateContext: resourceVpcProjectCreate,
 		ReadContext:   resourceVpcProjectRead,
 		UpdateContext: resourceVpcProjectUpdate,
@@ -27,12 +32,12 @@ func resourceVpcProject() *schema.Resource {
 			"created_by": {
 				Type:        schema.TypeString,
 				Computed:    true,
-				Description: "CRN of the user who created the VPC Project.",
+				Description: "The CRN of the user who created the VPC Project.",
 			},
 			"creation_date": {
 				Type:        schema.TypeString,
 				Computed:    true,
-				Description: "Timestamp of the date when the VPC Project was created.",
+				Description: "The timestamp of the date when the VPC Project was created.",
 			},
 			"limits": {
 				Type:        schema.TypeMap,
@@ -43,10 +48,13 @@ func resourceVpcProject() *schema.Resource {
 				},
 			},
 			"name": {
-				Type:        schema.TypeString,
-				Required:    true,
-				ForceNew:    true,
-				Description: "The user defined name used to construct the OpenStack project name with the schema '\\<tenant\\>-\\<name\\>'.</br>By changing this value the old project will be delete and a new project with the new name will be created.</br> ~> **WARNING:** Changing this value will delete all resources in the VPC Project.",
+				Type:     schema.TypeString,
+				Required: true,
+				ForceNew: true,
+				Description: `The user defined name used to construct the OpenStack project name with the schema ` + "`tenant-name`.  " + `
+By changing this value, the old project will be deleted and a new project with the new name will be created.
+
+!> Changing this value will delete all resources in the VPC Project.`,
 				ValidateDiagFunc: validation.ToDiagFunc(validation.All(
 					validation.StringLenBetween(1, 41),
 					validation.StringMatch(nameRegex, "Name may only contain (a-zA-Zß0-9-_)."),
@@ -58,11 +66,14 @@ func resourceVpcProject() *schema.Resource {
 				Description: "The uuid of the OpenStack Project.",
 			},
 			"project_comment": {
-				Type:             schema.TypeString,
-				Optional:         true,
-				ForceNew:         true,
-				Default:          "",
-				Description:      "A comment to describe what this VPC Project is used for.</br>By changing this value the old project will be delete and a new project will be created.</br> ~> **WARNING:** Changing this value will delete all resources in the VPC Project.",
+				Type:     schema.TypeString,
+				Optional: true,
+				ForceNew: true,
+				Default:  "",
+				Description: `A comment to describe what this VPC Project is used for.  
+By changing this value, the old project will be deleted and a new project will be created.
+
+!> Changing this value will delete all resources in the VPC Project.`,
 				ValidateDiagFunc: validation.ToDiagFunc(validation.StringMatch(commentRegex, "project_comment may only contain (a-zA-Zß0-9-_.,;:?!#+ ).")),
 			},
 			"tenant": {

cancom/services/iam/resource_policy.go

@@ -13,6 +13,7 @@ import (
 
 func resourcePolicy() *schema.Resource {
 	return &schema.Resource{
+		Description:   "IAM --- Generate a new IAM policy and attach it to users, service users and roles.",
 		CreateContext: resourcePolicyCreate,
 		ReadContext:   resourcePolicyRead,
 		UpdateContext: resourcePolicyUpdate,
@@ -25,6 +26,15 @@ func resourcePolicy() *schema.Resource {
 				Description: "The service name to provide permissions for.",
 			},
 			"policy": {
+				Description: `You can choose either a profile or a custom policy.   
+This block allows to setup policies using predefined profiles (` + "`policy.profile`" + `). Profile can either be ` + "`full-access`" + ` or ` + "`reader`" + `, providing either administrative access to the service, or read-only access.  
+If you want to manage policies on a find-grained basis, you can use ` + "`policy.custom`" + ` instead.
+
+~> **Note:** ` + "`profile`" + ` and ` + "`custom`" + ` are not joined into a single policy. If both are provided, ` + "`custom`" + ` is preferred over ` + "`profile`" + `, and ` + "`profile`" + ` will be ignored.
+
+~> **Note:** Either ` + "`profile`" + ` or ` + "`custom`" + ` must be provided. Otherwise, this resource will fail.
+
+.`,
 				Type:     schema.TypeList,
 				Required: true,
 				Elem: &schema.Resource{

cancom/services/iam/resource_role.go

@@ -11,6 +11,7 @@ import (
 
 func resourceRole() *schema.Resource {
 	return &schema.Resource{
+		Description:   "IAM --- Role with short-term credentials.",
 		CreateContext: resourceRoleCreate,
 		ReadContext:   resourceRoleRead,
 		UpdateContext: resourceRoleUpdate,

cancom/services/iam/resource_service_user.go

@@ -11,6 +11,7 @@ import (
 
 func resourceServiceUser() *schema.Resource {
 	return &schema.Resource{
+		Description:   "IAM --- User with long-term credentials for automation purpose.",
 		CreateContext: resourceServiceUserCreate,
 		ReadContext:   resourceServiceUserRead,
 		UpdateContext: resourceServiceUserUpdate,
@@ -25,7 +26,7 @@ func resourceServiceUser() *schema.Resource {
 			"description": {
 				Type:        schema.TypeString,
 				Optional:    true,
-				Description: "Description for what the role is used for.",
+				Description: "Description for what the service user is used for.",
 			},
 			"group": {
 				Type:        schema.TypeString,
@@ -46,6 +47,7 @@ func resourceServiceUser() *schema.Resource {
 				Type:        schema.TypeString,
 				Computed:    true,
 				Description: "Deprecated. Must not be used.",
+				Deprecated:  "`session_hash` is deprecated and might be removed in a future version.",
 			},
 			"created_at": {
 				Type:        schema.TypeString,

cancom/services/iam/resource_user.go

@@ -11,6 +11,7 @@ import (
 
 func resourceUser() *schema.Resource {
 	return &schema.Resource{
+		Description:   "IAM --- IAM user authenticated against the central CANCOM SSO.",
 		CreateContext: resourceUserCreate,
 		ReadContext:   resourceUserRead,
 		UpdateContext: resourceUserUpdate,

cancom/services/ipam/resource_host.go

@@ -11,6 +11,8 @@ import (
 
 func resourceHost() *schema.Resource {
 	return &schema.Resource{
+		Description: `IP Management --- IPAM host allows you to assign host ip-addresses from a network that must be enabled for host assignment. The network is identified by it's id (crn).  
+You manage networks and enable them for host-assignments by using the portal or the network resource of this provider.`,
 		CreateContext: resourceHostCreate,
 		ReadContext:   resourceHostRead,
 		UpdateContext: resourceHostUpdate,

cancom/services/ipam/resource_instance.go

@@ -11,6 +11,7 @@ import (
 
 func resourceInstance() *schema.Resource {
 	return &schema.Resource{
+		Description:   "IP Management --- An IPAM instance.",
 		CreateContext: resourceInstanceCreate,
 		ReadContext:   resourceInstanceRead,
 		UpdateContext: resourceInstanceUpdate,

cancom/services/ipam/resource_network.go

@@ -11,6 +11,7 @@ import (
 
 func resourceNetwork() *schema.Resource {
 	return &schema.Resource{
+		Description:   "IP Management --- IPAM networks are assigned by the service from supernets.",
 		CreateContext: resourceNetworkCreate,
 		ReadContext:   resourceNetworkRead,
 		UpdateContext: resourceNetworkUpdate,

cancom/services/ipam/resource_supernet.go

@@ -11,6 +11,7 @@ import (
 
 func resourceSupernet() *schema.Resource {
 	return &schema.Resource{
+		Description:   "IP Management --- IPAM Supernets are larger aggregates that are further subnetted by the service.",
 		CreateContext: resourceSupernetCreate,
 		ReadContext:   resourceSupernetRead,
 		UpdateContext: resourceSupernetUpdate,

cancom/services/ssl-monitoring/resource_ssl_monitor.go

@@ -11,6 +11,7 @@ import (
 
 func resourceSslMonitor() *schema.Resource {
 	return &schema.Resource{
+		Description:   "SSL Monitoring --- A SSL monitor item.",
 		CreateContext: resourceSslMonitorCreate,
 		ReadContext:   resourceSslMonitorRead,
 		UpdateContext: resourceSslMonitorUpdate,
@@ -55,7 +56,7 @@ func resourceSslMonitor() *schema.Resource {
 			"is_managed_by_cancom": {
 				Type:        schema.TypeBool,
 				Optional:    true,
-				Description: "This item is managed by CANCOM, and a CANCOM employee is responible to renew the certificate. Can only be set by CANCOM emplyoees.",
+				Description: "This item is managed by CANCOM, and a CANCOM employee is responsible to renew the certificate. Can only be set by CANCOM employees.",
 			},
 			"protocol": {
 				Type:        schema.TypeString,

cancom/services/windows-os/data_deployment_progess.go

@@ -8,6 +8,10 @@ import (
 
 func dataWindowsOSDeploymentProgress() *schema.Resource {
 	return &schema.Resource{
+		Description: `Windows OS --- This data objects waits for CANCOM Manged Windows Cloud server deployment-system to complete. 
+		
+This can be used for dependency tracking purposes and returns in case of failure errors.  
+The required` + " `deployment_id` " + `represents the id of` + " `cancom_windows_os_deployment` " + `resource.`,
 		Read: WindowsOSDeploymentProgressRead,
 		Schema: map[string]*schema.Schema{
 			"deployment_id": {

cancom/services/windows-os/resource_deployment.go

@@ -11,6 +11,9 @@ import (
 
 func resourceWindowsOSDeployment() *schema.Resource {
 	return &schema.Resource{
+		Description: `Windows OS --- CANCOM Managed Windows Cloud Server deployment resource allows you to send metadata to CANCOM Windows Server management platform.
+
+ID and customer number need do be assigned to a created virtual machine with CANCOM Windows Images and allows the auto-registration, installation and integration to customer environment.`,
 		CreateContext: resourceWindowsOSCreate,
 		ReadContext:   resourceWindowsOSRead,
 		UpdateContext: resourceWindowsOSUpdate,
@@ -43,7 +46,7 @@ func resourceWindowsOSDeployment() *schema.Resource {
 				Elem: &schema.Schema{
 					Type: schema.TypeString,
 				},
-				Description: "Services deployed and delivered to maschine",
+				Description: "Services deployed and delivered to machine",
 			},
 			"customer_number": {
 				Type:        schema.TypeString,

docs/data-sources/windows_os_deployment_progress.md

@@ -1,17 +1,23 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "cancom_windows_os_deployment_progress Data Source - terraform-provider-cancom"
-subcategory: ""
+subcategory: "Windows OS"
 description: |-
-  This data objects waits for CANCOM Manged Windows Cloud server deplyoment-system to complete. This can be used for dependency tracking purposes and returns in case of failure errors. The required `deployment_id` represents the id of `cancom_windows_os_deployment` resource.
+  This data objects waits for CANCOM Manged Windows Cloud server deployment-system to complete.
+  This can be used for dependency tracking purposes and returns in case of failure errors.The required deployment_id represents the id of cancom_windows_os_deployment resource.
 ---
 
 # cancom_windows_os_deployment_progress (Data Source)
+
+This data objects waits for CANCOM Manged Windows Cloud server deployment-system to complete. 
+
+This can be used for dependency tracking purposes and returns in case of failure errors.  
+The required `deployment_id` represents the id of `cancom_windows_os_deployment` resource.
+
 ## Example Usage
 
 ```terraform
 data "cancom_windows_os_deployment_progress" "progress" {
-    deployment_id = cancom_windows_os_windows_deployment.windows_os.id
+  deployment_id = cancom_windows_os_windows_deployment.windows_os.id
 }
 ```
 
@@ -24,4 +30,5 @@ data "cancom_windows_os_deployment_progress" "progress" {
 
 ### Read-Only
 
-- `id` (String) The ID of this resource.
+- `id` (String) The ID of this resource.
+- `state` (String)

docs/index.md

@@ -1,8 +1,7 @@
 ---
-page_title: "cancom Provider"
-subcategory: ""
+page_title: "CANCOM Provider"
 description: |-
-  
+  Terraform Provider for CANCOM Cloud
 ---
 
 # CANCOM Provider

docs/resources/cmsmgw_connection.md

@@ -1,42 +1,42 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "CANCOM: cmsmgw_connection Resource"
-subcategory: ""
+page_title: "cancom_cmsmgw_connection Resource - terraform-provider-cancom"
+subcategory: "Managed Gateway"
 description: |-
-  Represents a connection resource
+  Represents a connection resource.
 ---
 
 # cancom_cmsmgw_connection (Resource)
 
+Represents a connection resource.
+
 ## Example Usage
 
 ```terraform
 resource "cancom_cmsmgw_connection" "<name of resource>" {
-  mgw_id = "<id of the gateway>"
-  customer_primary_gw_ip = "<ip of the customer gateway"
-  name_tag = "<name>"
-  customer_secondary_gw_ip = ""  // not used corrently
-  connection_profile = "AZURE, CANCOOM-V01-A, CANCOM-V01-B, CANCOM-V01-C"
-  customer_networks = ["cidr-1", "cidr-2", "cidr-n"]
-  cancom_networks = ["100.97.0.0/16"]
-  ipsec_psk_a = "123456abcdefg123456"  //provide a secret or emty to let the service create one
-  ipsec_psk_b = ""  // not used currently
+  mgw_id                   = "<id of the gateway>"
+  customer_primary_gw_ip   = "<ip of the customer gateway"
+  name_tag                 = "<name>"
+  customer_secondary_gw_ip = "" // not used currently
+  connection_profile       = "AZURE, CANCOOM-V01-A, CANCOM-V01-B, CANCOM-V01-C"
+  customer_networks        = ["cidr-1", "cidr-2", "cidr-n"]
+  cancom_networks          = ["100.97.0.0/16"]
+  ipsec_psk_a              = "123456abcdefg123456" // provide a secret or empty to let the service create one
+  ipsec_psk_b              = ""                    // not used currently
 }
 
 resource "cancom_cmsmgw_connection" "conn_tf-01" {
-  mgw_id = cancom_cmsmgw_gateway.gw-tf-03.id
-  customer_primary_gw_ip = "192.168.3.1"
-  name_tag = "testconnection01"
+  mgw_id                   = cancom_cmsmgw_gateway.gw-tf-03.id
+  customer_primary_gw_ip   = "192.168.3.1"
+  name_tag                 = "testconnection01"
   customer_secondary_gw_ip = ""
-  connection_profile = "AZURE"
-  customer_networks = ["10.0.0.0/16", "10.10.0.0/16"]
-  cancom_networks = ["100.97.0.0/16"]
-  ipsec_psk_a = "123456abcdefg123456"
-  ipsec_psk_b = ""
+  connection_profile       = "AZURE"
+  customer_networks        = ["10.0.0.0/16", "10.10.0.0/16"]
+  cancom_networks          = ["100.97.0.0/16"]
+  ipsec_psk_a              = "123456abcdefg123456"
+  ipsec_psk_b              = ""
 }
 ```
 
-
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
@@ -59,3 +59,12 @@ resource "cancom_cmsmgw_connection" "conn_tf-01" {
 
 - `deployment_state` (String)
 - `id` (String) The ID of this resource.
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# You can import this resource by using its `id`
+terraform import cancom_cmsmgw_connection.foo abc123
+```