Docs update (using tfplugindocs tool) (#92)

* First cut of docs generated by tfplugindocs tool

* Add docs index template

* Update provider docs

* Update DNS domain name

* Add example for civo_dns_domain_name

* Add placeholder examples

* Populate example placeholders with real examples

* Update DNS domain record

* Update firewall

* Update firewall rule

* Update instance

* Update cluster

* Remove explicit "(required)" string from resource descriptions

* Update nodepool

* Generate docs for a couple of resources

* Update network

* Update SSH key

* Update volume

* Update volume attachment

* Add import examples and generate docs

* Update README.md

* Improve docs for a few resources

* Add descriptions to various resources and data-sources

* Add dot at the end of data-source filter and sort descriptions

README.md

@@ -1,16 +1,11 @@
-Terraform Provider ![Travis build](https://travis-ci.org/civo/terraform-provider-civo.svg?branch=master)
+Terraform Provider
 ==================
 
-- Website: https://www.terraform.io
-- [![Gitter chat](https://badges.gitter.im/hashicorp-terraform/Lobby.png)](https://gitter.im/hashicorp-terraform/Lobby)
-- [![Build Status](https://github.com/civo/terraform-provider-civo/workflows/Go/badge.svg)](https://github.com/civo/terraform-provider-civo/actions)
-- Mailing list: [Google Groups](http://groups.google.com/group/terraform-tool)
-
 Requirements
 ------------
 
 -   [Terraform](https://www.terraform.io/downloads.html) 0.13.x
--   [Go](https://golang.org/doc/install) 1.14.x (to build the provider plugin)
+-   [Go](https://golang.org/doc/install) 1.14.x or later (to build the provider plugin)
 
 Building The Provider
 ---------------------
@@ -32,14 +27,13 @@ $ make build
 Using the provider
 ----------------------
 
-When the provider is out of beta the documentation will be at [Civo Provider documentation](https://registry.terraform.io/providers/civo/civo/latest/docs),
-but during the beta the best resource for learning about it is [this guide](https://www.civo.com/learn/using-the-civo-terraform-provider)
+The documentation is available at [Civo Provider documentation](https://registry.terraform.io/providers/civo/civo/latest/docs)
 
 
 Developing the Provider
 ---------------------------
 
-If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.11+ is *required*). You'll also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`.
+If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.14.x (or later) is *required*). You'll also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`.
 
 To compile the provider, run `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
 
@@ -71,3 +65,16 @@ $ make testacc TESTARGS='-run=TestAccCivoDomain_Basic'
 ```
 
 For information about writing acceptance tests, see the main Terraform [contributing guide](https://github.com/hashicorp/terraform/blob/master/.github/CONTRIBUTING.md#writing-acceptance-tests).
+
+Documenting the Provider
+---------------------------
+
+As of 10th September 2021, we decided to use [tfplugindocs](https://github.com/hashicorp/terraform-plugin-docs) to auto-generate [docs](docs) from the provider code and [examples](examples).
+
+For reference, you can see an example of the templates and output in [paultyng/terraform-provider-unifi](https://github.com/paultyng/terraform-provider-unifi) and browse the generated docs in the [Terraform Registry](https://registry.terraform.io/providers/paultyng/unifi/latest/docs).
+
+Another example would be [https://github.com/fastly/terraform-provider-fastly](https://github.com/fastly/terraform-provider-fastly) - which rendered in the [Terraform Registry](https://registry.terraform.io/providers/fastly/fastly/latest/docs).
+
+**Caveat**
+
+While the `tfplugindocs` is still in active development by the Hashicorp and works fine for most cases, except when it comes to generating attribute descriptions located in nested schemas. We think this isn't too critical since the attribute keys are self explanatory. However, we will still watch the [issue](https://github.com/hashicorp/terraform-plugin-docs/issues/28) and update the [docs](docs) once it's fixed.

civo/datasource_disk_image.go

@@ -11,10 +11,12 @@ func dataSourceDiskImage() *schema.Resource {
 
 	dataListConfig := &datalist.ResourceConfig{
 		RecordSchema: templateSchema(),
+		Description:  "Get information on an disk image for use in other resources (e.g. creating a instance) with the ability to filter the results.",
 		ExtraQuerySchema: map[string]*schema.Schema{
 			"region": {
-				Type:     schema.TypeString,
-				Optional: true,
+				Type:        schema.TypeString,
+				Optional:    true,
+				Description: "If is used, all disk image will be from this region. Required if no region is set in provider.",
 			},
 		},
 		ResultAttributeName: "diskimages",

civo/datasource_dns_domain_name.go

@@ -3,6 +3,7 @@ package civo
 import (
 	"fmt"
 	"log"
+	"strings"
 
 	"github.com/civo/civogo"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
@@ -13,6 +14,10 @@ import (
 // using the id or the name of the domain
 func dataSourceDNSDomainName() *schema.Resource {
 	return &schema.Resource{
+		Description: strings.Join([]string{
+			"Get information on a domain. This data source provides the name and the id.",
+			"An error will be raised if the provided domain name is not in your Civo account.",
+		}, "\n\n"),
 		Read: dataSourceDNSDomainNameRead,
 		Schema: map[string]*schema.Schema{
 			"id": {
@@ -26,6 +31,7 @@ func dataSourceDNSDomainName() *schema.Resource {
 				Optional:     true,
 				ValidateFunc: validation.NoZeroValues,
 				ExactlyOneOf: []string{"id", "name"},
+				Description:  "The name of the domain",
 			},
 		},
 	}

civo/datasource_dns_domain_record.go

@@ -2,6 +2,7 @@ package civo
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/civo/civogo"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
@@ -12,46 +13,59 @@ import (
 // using the id or the name of the domain
 func dataSourceDNSDomainRecord() *schema.Resource {
 	return &schema.Resource{
+		Description: strings.Join([]string{
+			"Get information on a DNS record. This data source provides the name, TTL, and zone file as configured on your Civo account.",
+			"An error will be raised if the provided domain name or record are not in your Civo account.",
+		}, "\n\n"),
 		Read: dataSourceDNSDomainRecordRead,
 		Schema: map[string]*schema.Schema{
 			"domain_id": {
 				Type:         schema.TypeString,
 				Required:     true,
 				ValidateFunc: validation.NoZeroValues,
+				Description:  "The ID of the domain",
 			},
 			"name": {
 				Type:         schema.TypeString,
 				Required:     true,
 				ValidateFunc: validation.NoZeroValues,
+				Description:  "The name of the record",
 			},
 			// Computed resource
 			"type": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The choice of record type from A, CNAME, MX, SRV or TXT",
 			},
 			"value": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The IP address (A or MX), hostname (CNAME or MX) or text value (TXT) to serve for this record",
 			},
 			"priority": {
-				Type:     schema.TypeInt,
-				Computed: true,
+				Type:        schema.TypeInt,
+				Computed:    true,
+				Description: "The priority of the record",
 			},
 			"ttl": {
-				Type:     schema.TypeInt,
-				Computed: true,
+				Type:        schema.TypeInt,
+				Computed:    true,
+				Description: "How long caching DNS servers should cache this record",
 			},
 			"account_id": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The ID account of the domain",
 			},
 			"created_at": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The date when it was created in UTC format",
 			},
 			"updated_at": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The date when it was updated in UTC format",
 			},
 		},
 	}

civo/datasource_instance.go

@@ -3,6 +3,7 @@ package civo
 import (
 	"fmt"
 	"log"
+	"strings"
 
 	"github.com/civo/civogo"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
@@ -13,6 +14,10 @@ import (
 // using the id or the hostname
 func dataSourceInstance() *schema.Resource {
 	return &schema.Resource{
+		Description: strings.Join([]string{
+			"Get information on an instance for use in other resources. This data source provides all of the instance's properties as configured on your Civo account.",
+			"Note: This data source returns a single instance. When specifying a hostname, an error will be raised if more than one instances found.",
+		}, "\n\n"),
 		Read: dataSourceInstanceRead,
 		Schema: map[string]*schema.Schema{
 			"id": {
@@ -26,89 +31,110 @@ func dataSourceInstance() *schema.Resource {
 				Optional:     true,
 				ValidateFunc: validation.NoZeroValues,
 				ExactlyOneOf: []string{"id", "hostname"},
+				Description:  "The hostname of the Instance",
 			},
 			"region": {
 				Type:         schema.TypeString,
 				Optional:     true,
 				ValidateFunc: validation.NoZeroValues,
+				Description:  "The region of an existing Instance",
 			},
 			// computed attributes
 			"reverse_dns": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "A fully qualified domain name",
 			},
 			"size": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The name of the size",
 			},
 			"cpu_cores": {
-				Type:     schema.TypeInt,
-				Computed: true,
+				Type:        schema.TypeInt,
+				Computed:    true,
+				Description: "Total cpu of the inatance",
 			},
 			"ram_mb": {
-				Type:     schema.TypeInt,
-				Computed: true,
+				Type:        schema.TypeInt,
+				Computed:    true,
+				Description: "Total ram of the instance",
 			},
 			"disk_gb": {
-				Type:     schema.TypeInt,
-				Computed: true,
+				Type:        schema.TypeInt,
+				Computed:    true,
+				Description: "The size of the disk",
 			},
 			"network_id": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "his will be the ID of the network",
 			},
 			"template": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The ID for the disk image/template to used to build the instance",
 			},
 			"initial_user": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The name of the initial user created on the server",
 			},
 			"notes": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The notes of the instance",
 			},
 			"sshkey_id": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The ID SSH key",
 			},
 			"firewall_id": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The ID of the firewall used",
 			},
 			"tags": {
-				Type:     schema.TypeSet,
-				Elem:     &schema.Schema{Type: schema.TypeString},
-				Computed: true,
+				Type:        schema.TypeSet,
+				Elem:        &schema.Schema{Type: schema.TypeString},
+				Computed:    true,
+				Description: "An optional list of tags",
 			},
 			"script": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The contents of a script uploaded",
 			},
 			"initial_password": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "Instance initial password",
 			},
 			"private_ip": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The private IP",
 			},
 			"public_ip": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The public IP",
 			},
 			"pseudo_ip": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "Is the ip that is used to route the public ip from the internet to the instance using NAT",
 			},
 			"status": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The status of the instance",
 			},
 			"created_at": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The date of creation of the instance",
 			},
 		},
 	}