documentation: generate docs from provider schemas (#248)

We make use of
[tfplugindocs](https://github.com/hashicorp/terraform-plugin-docs) and
refacor the codebase so that all documentation files are generated from
the schemas in the source code. To ensure that developers don't forget
to update the documentation in the future we add a CI step that verifies
that the generated documentation matches the docs checked into git.
Additionally we add an indicator to the documentation description of
each attribute for which `ForceNew == true`.

---------

Co-authored-by: Philipp Sauter <philipp.sauter@exoscale.ch>

.github/actions/setup/action.yaml

@@ -0,0 +1,7 @@
+name: "Shared setup steps"
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-go@v2
+      with:
+        go-version: '~1.18'

.github/workflows/main.yml

@@ -13,13 +13,18 @@ on:
     - 'v*' # Don't run CI tests on release tags
 
 jobs:
+  check-docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ./.github/actions/setup
+    - name: Check documentation is up to date
+      run: './scripts/check-documentation-clean.sh'
   test:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
-    - uses: actions/setup-go@v2
-      with:
-        go-version: '~1.18'
+    - uses: ./.github/actions/setup
     - name: Run tests
       run: |
         git submodule update --init --recursive go.mk

README.md

@@ -25,7 +25,9 @@ Terraform configuration files referencing [Exoscale provider
 resources][tf-exo-doc]:
 
 ```console
-$ terraform init
+terraform init
+
+Output:
 
 Initializing the backend...
 

docs/data-sources/affinity.md

@@ -1,23 +1,22 @@
 ---
-page_title: "Exoscale: exoscale_affinity"
-subcategory: "Deprecated"
-description: |-
+page_title: "exoscale_affinity Data Source - terraform-provider-exoscale"
+subcategory: "Deprecated
+"description: |-
   Fetch Exoscale Anti-Affinity Groups data.
 ---
 
-# exoscale\_affinity
+# exoscale_affinity (Data Source)
 
 !> **WARNING:** This data source is DEPRECATED and will be removed in the next major version. Please use [exoscale_anti_affinity_group](./anti_affinity_group.md) instead.
 
 
-## Arguments Reference
 
-* `id` - The anti-affinity group ID to match (conflicts with `name`)
-* `name` - The group name to match (conflicts with `id`)
+<!-- schema generated by tfplugindocs -->
+## Schema
 
+### Optional
 
-## Attributes Reference
+- `id` (String) The anti-affinity group ID to match (conflicts with `name`)
+- `name` (String) The group name to match (conflicts with `id`)
 
-In addition to the arguments listed above, the following attributes are exported:
 
-* n/a

docs/data-sources/anti_affinity_group.md

@@ -1,19 +1,21 @@
 ---
-page_title: "Exoscale: exoscale_anti_affinity_group"
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "exoscale_anti_affinity_group Data Source - terraform-provider-exoscale"
+subcategory: ""
 description: |-
-  Fetch Exoscale Anti-Affinity Groups data.
+  Fetch Exoscale Anti-Affinity Groups https://community.exoscale.com/documentation/compute/anti-affinity-groups/ data.
+  Corresponding resource: exoscaleantiaffinity_group ../resources/anti_affinity_group.md.
 ---
 
-# exoscale\_anti\_affinity\_group
+# exoscale_anti_affinity_group (Data Source)
 
 Fetch Exoscale [Anti-Affinity Groups](https://community.exoscale.com/documentation/compute/anti-affinity-groups/) data.
 
 Corresponding resource: [exoscale_anti_affinity_group](../resources/anti_affinity_group.md).
 
+## Example Usage
 
-## Usage
-
-```hcl
+```terraform
 data "exoscale_anti_affinity_group" "my_anti_affinity_group" {
   name = "my-anti-affinity-group"
 }
@@ -26,15 +28,16 @@ output "my_anti_affinity_group_id" {
 Please refer to the [examples](https://github.com/exoscale/terraform-provider-exoscale/tree/master/examples/)
 directory for complete configuration examples.
 
+<!-- schema generated by tfplugindocs -->
+## Schema
 
-## Arguments Reference
+### Optional
 
-* `id` - The anti-affinity group ID to match (conflicts with `name`).
-* `name` - The group name to match (conflicts with `id`).
+- `id` (String) The anti-affinity group ID to match (conflicts with `name`).
+- `name` (String) The group name to match (conflicts with `id`).
 
+### Read-Only
 
-## Attributes Reference
+- `instances` (Set of String) The list of attached [exoscale_compute_instance](../resources/compute_instance.md) (IDs).
 
-In addition to the arguments listed above, the following attributes are exported:
 
-* `instances` - The list of attached [exoscale_compute_instance](../resources/compute_instance.md) (IDs).

docs/data-sources/compute.md

@@ -1,34 +1,37 @@
 ---
-page_title: "Exoscale: exoscale_compute"
+page_title: "exoscale_compute Data Source - terraform-provider-exoscale"
 subcategory: "Deprecated"
 description: |-
   Fetch Exoscale Compute Instances data.
 ---
 
-# exoscale\_compute
+# exoscale_compute (Data Source)
 
 !> **WARNING:** This data source is **DEPRECATED** and will be removed in the next major version. Please use [exoscale_compute_instance](./compute_instance.md) instead.
 
-## Arguments Reference
 
-* `id` - The compute instance ID to match.
-* `hostname` - The instance hostname to match.
-* `tags` - The instance tags to match (map of key/value).
 
+<!-- schema generated by tfplugindocs -->
+## Schema
 
-## Attributes Reference
+### Optional
 
-In addition to the arguments listed above, the following attributes are exported:
+- `hostname` (String) The instance hostname to match.
+- `id` (String) The compute instance ID to match.
+- `tags` (Map of String) The instance tags to match (map of key/value).
+
+### Read-Only
+
+- `cpu` (Number) Number of cpu the Compute instance is running with
+- `created` (String) Date when the Compute instance was created
+- `disk_size` (Number) Size of the Compute instance disk
+- `ip6_address` (String) Compute instance public ipv6 address (if ipv6 is enabled)
+- `ip_address` (String) Compute instance public ipv4 address
+- `memory` (Number) Memory allocated for the Compute instance
+- `private_network_ip_addresses` (List of String) List of Compute instance private IP addresses (in managed Private Networks only)
+- `size` (String) Current size of the Compute instance
+- `state` (String) State of the Compute instance
+- `template` (String) Name of the template for the Compute instance
+- `zone` (String) Name of the availability zone for the Compute instance
 
-* `zone` - Exoscale Zone name.
-* `cpu` - The compute instance number of CPUs.
-* `created` - The instance creation date.
-* `disk_size` - The instance disk size (GiB).
-* `ip_address` - The instance (main network interface) IPv4 address.
-* `ip6_address` - The instance (main network interface) IPv6 address (if enabled).
-* `memory` - The instance allocated memory.
-* `size` - The instance size.
-* `state` - The current instance state.
-* `template` - The instance template.
 
-* `private_network_ip_addresses` - List of compute private IPv4 addresses (in *managed* private networks only).

docs/data-sources/compute_instance.md

@@ -1,19 +1,21 @@
 ---
-page_title: "Exoscale: exoscale_compute_instance"
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "exoscale_compute_instance Data Source - terraform-provider-exoscale"
+subcategory: ""
 description: |-
-  Fetch Exoscale Compute Instances data.
+  Fetch Exoscale Compute Instances https://community.exoscale.com/documentation/compute/ data.
+  Corresponding resource: exoscalecomputeinstance ../resources/compute_instance.md.
 ---
 
-# exoscale\_compute\_instance
+# exoscale_compute_instance (Data Source)
 
 Fetch Exoscale [Compute Instances](https://community.exoscale.com/documentation/compute/) data.
 
 Corresponding resource: [exoscale_compute_instance](../resources/compute_instance.md).
 
+## Example Usage
 
-## Usage
-
-```hcl
+```terraform
 data "exoscale_compute_instance" "my_instance" {
   zone = "ch-gva-2"
   name = "my-instance"
@@ -27,40 +29,38 @@ output "my_instance_id" {
 Please refer to the [examples](https://github.com/exoscale/terraform-provider-exoscale/tree/master/examples/)
 directory for complete configuration examples.
 
+<!-- schema generated by tfplugindocs -->
+## Schema
 
-## Arguments Reference
-
-[zone]: https://www.exoscale.com/datacenters/
-
-* `zone` - (Required) The Exoscale [Zone][zone] name.
+### Required
 
-* `id` - The compute instance ID to match (conflicts with `name`).
-* `name` - The instance name to match (conflicts with `id`).
+- `zone` (String) The Exoscale [Zone](https://www.exoscale.com/datacenters/) name.
 
+### Optional
 
-## Attributes Reference
+- `anti_affinity_group_ids` (Set of String) The list of attached [exoscale_anti_affinity_group](../resources/anti_affinity_group.md) (IDs).
+- `id` (String) The compute instance ID to match (conflicts with `name`).
+- `labels` (Map of String) A map of key/value labels.
+- `name` (String) The instance name to match (conflicts with `id`).
 
-[cloud-init]: http://cloudinit.readthedocs.io/en/latest/
+### Read-Only
 
-In addition to the arguments listed above, the following attributes are exported:
+- `created_at` (String) The compute instance creation date.
+- `deploy_target_id` (String) A deploy target ID.
+- `disk_size` (Number) The instance disk size (GiB).
+- `elastic_ip_ids` (Set of String) The list of attached [exoscale_elastic_ip](../resources/elastic_ip.md) (IDs).
+- `ipv6` (Boolean) Whether IPv6 is enabled on the instance.
+- `ipv6_address` (String) The instance (main network interface) IPv6 address (if enabled).
+- `manager_id` (String) The instance manager ID, if any.
+- `manager_type` (String) The instance manager type (instance pool, SKS node pool, etc.), if any.
+- `private_network_ids` (Set of String) The list of attached [exoscale_private_network](../resources/private_network.md) (IDs).
+- `public_ip_address` (String) The instance (main network interface) IPv4 address.
+- `reverse_dns` (String) Domain name for reverse DNS record.
+- `security_group_ids` (Set of String) The list of attached [exoscale_security_group](../resources/security_group.md) (IDs).
+- `ssh_key` (String) The [exoscale_ssh_key](../resources/ssh_key.md) (name) authorized on the instance.
+- `state` (String) The instance state.
+- `template_id` (String) The instance [exoscale_compute_template](./compute_template.md) ID.
+- `type` (String) The instance type.
+- `user_data` (String) The instance [cloud-init](http://cloudinit.readthedocs.io/en/latest/) configuration.
 
-* `created_at` - The compute instance creation date.
-* `deploy_target_id` - A deploy target ID.
-* `disk_size` - The instance disk size (GiB).
-* `ipv6_address` - The instance (main network interface) IPv6 address (if enabled).
-* `ipv6` - Whether IPv6 is enabled on the instance.
-* `labels` - A map of key/value labels.
-* `manager_id` - The instance manager ID, if any.
-* `manager_type` - The instance manager type (instance pool, SKS node pool, etc.), if any.
-* `public_ip_address` - The instance (main network interface) IPv4 address.
-* `reverse_dns` - Domain name for reverse DNS record.
-* `ssh_key` - The [exoscale_ssh_key](../resources/ssh_key.md) (name) authorized on the instance.
-* `state` - The instance state.
-* `template_id` - The instance [exoscale_compute_template](./compute_template.md) ID.
-* `type` - The instance type.
-* `user_data` - The instance [cloud-init][cloud-init] configuration.
 
-* `affinity_group_ids` - The list of attached [exoscale_anti_affinity_group](../resources/anti_affinity_group.md) (IDs).
-* `elastic_ip_ids` - The list of attached [exoscale_elastic_ip](../resources/elastic_ip.md) (IDs).
-* `network_ids` - The list of attached [exoscale_private_network](../resources/private_network.md) (IDs).
-* `security_group_ids` - The list of attached [exoscale_security_group](../resources/security_group.md) (IDs).

docs/data-sources/compute_instance_list.md

@@ -1,19 +1,21 @@
 ---
-page_title: "Exoscale: exoscale_compute_instance_list"
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "exoscale_compute_instance_list Data Source - terraform-provider-exoscale"
+subcategory: ""
 description: |-
-  List Exoscale Compute Instances.
+  List Exoscale Compute Instances https://community.exoscale.com/documentation/compute/.
+  Corresponding resource: exoscalecomputeinstance ../resources/compute_instance.md.
 ---
 
-# exoscale\_compute\_instance_list
+# exoscale_compute_instance_list (Data Source)
 
 List Exoscale [Compute Instances](https://community.exoscale.com/documentation/compute/).
 
 Corresponding resource: [exoscale_compute_instance](../resources/compute_instance.md).
 
+## Example Usage
 
-## Usage
-
-```hcl
+```terraform
 data "exoscale_compute_instance_list" "my_compute_instance_list" {
   zone = "ch-gva-2"
 
@@ -37,15 +39,60 @@ output "my_compute_instance_ids" {
 Please refer to the [examples](https://github.com/exoscale/terraform-provider-exoscale/tree/master/examples/)
 directory for complete configuration examples.
 
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- `created_at` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `deploy_target_id` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `disk_size` (Number) Match against this int
+- `id` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `ipv6` (Boolean) Match against this bool
+- `ipv6_address` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `labels` (Map of String) Match against key/values. Keys are matched exactly, while values may be matched as a regex if you supply a string that begins and ends with "/"
+- `manager_id` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `manager_type` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `name` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `public_ip_address` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `reverse_dns` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `ssh_key` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `state` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `template_id` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `type` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `user_data` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+- `zone` (String) Match against this string. If you supply a string that begins and ends with a "/" it will be matched as a regex.
+
+### Read-Only
+
+- `instances` (List of Object) The list of [exoscale_compute_instance](./compute_instance.md). (see [below for nested schema](#nestedatt--instances))
+
+<a id="nestedatt--instances"></a>
+### Nested Schema for `instances`
+
+Read-Only:
+
+- `anti_affinity_group_ids` (Set of String)
+- `created_at` (String)
+- `deploy_target_id` (String)
+- `disk_size` (Number)
+- `elastic_ip_ids` (Set of String)
+- `id` (String)
+- `ipv6` (Boolean)
+- `ipv6_address` (String)
+- `labels` (Map of String)
+- `manager_id` (String)
+- `manager_type` (String)
+- `name` (String)
+- `private_network_ids` (Set of String)
+- `public_ip_address` (String)
+- `reverse_dns` (String)
+- `security_group_ids` (Set of String)
+- `ssh_key` (String)
+- `state` (String)
+- `template_id` (String)
+- `type` (String)
+- `user_data` (String)
+- `zone` (String)
 
-## Arguments Reference
-
-[zone]: https://www.exoscale.com/datacenters/
-
-* `zone` - (Required) The Exoscale [Zone][zone] name.
-
-You may filter instances by any string, bool, int or map[string]string attribute of [exoscale_compute_instance](./compute_instance.md) as in the example above. If you supply a string that begins and ends with a "/" it will be matched as a regex. 
-
-## Atributes Reference
 
-* `instances` - The list of [exoscale_compute_instance](./compute_instance.md).