misc: use tfplugindocs to generate docs.

Rather than constructing docs manually and running them through a linter, use
tfplugindocs to generate them. We move examples into the examples/ directory,
and override default templates in the templates/ directory. We also add new
make targets to generate docs and check that the generated docs match the code.

Resolves #490.

Author: jmcarp

Makefile

@@ -1,4 +1,5 @@
 # Build variables
+SHELL := /usr/bin/env bash
 VERSION ?= $(shell cat $(CURDIR)/VERSION)
 BINARY ?= terraform-provider-oxide_$(VERSION)
 BINARY_LOCATION ?= bin/$(BINARY)
@@ -47,9 +48,18 @@ test:
 	@ echo "-> Running unit tests for $(BINARY)"
 	@ go test $(TEST_PACKAGE) $(TEST_ARGS) $(TESTUNITARGS)
 
+.PHONY: docs
+docs:
+	@ $(GOBIN)/tfplugindocs generate
+
+.PHONY: check-docs
+check-docs:
+	@ $(GOBIN)/tfplugindocs generate
+	@ if ! git diff --exit-code docs; then echo 'Generated docs have changed. Re-generate with `make docs`.'; fi
+
 ## Lints all of the source files
 .PHONY: lint
-lint: golangci-lint tfproviderdocs terrafmt tfproviderlint # configfmt
+lint: golangci-lint tfproviderdocs terrafmt tfproviderlint check-docs # configfmt
 
 .PHONY: tfproviderlint
 tfproviderlint: tools
@@ -117,6 +127,7 @@ VERSION_GOLANGCILINT:=v1.64.8
 VERSION_TFPROVIDERDOCS:=v0.12.1
 VERSION_TERRAFMT:=v0.5.4
 VERSION_TFPROVIDERLINT:=v0.31.0
+VERSION_TFPLUGINDOCS:=v0.22.0
 VERSION_WHATSIT:=053446d
 
 tools: $(GOBIN)/golangci-lint $(GOBIN)/tfproviderdocs $(GOBIN)/terrafmt $(GOBIN)/tfproviderlint 
@@ -170,3 +181,6 @@ $(GOBIN)/whatsit: $(VERSION_DIR)/.version-whatsit-$(VERSION_WHATSIT) | $(GOBIN)
 	@ echo "-> Installing whatsit..."
 	@ cargo install --git ssh://[email protected]/oxidecomputer/whatsit.git#$(VERSION_WHATSIT) --branch main --root ./ 
 
+$(GOBIN)/tfplugindocs:
+	@ echo "-> Installing tfplugindocs..."
+	@ go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@$(VERSION_TFPLUGINDOCS)

docs/data-sources/oxide_anti_affinity_group.md renamed to docs/data-sources/anti_affinity_group.md

@@ -1,14 +1,18 @@
 ---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "oxide_anti_affinity_group Data Source - terraform-provider-oxide"
+subcategory: ""
+description: |-
+  
 ---
 
 # oxide_anti_affinity_group (Data Source)
 
-Retrieve information about a specified anti-affinity group.
+
 
 ## Example Usage
 
-```hcl
+```terraform
 data "oxide_anti_affinity_group" "example" {
   project_name = "my-project"
   name         = "my-group"
@@ -18,6 +22,7 @@ data "oxide_anti_affinity_group" "example" {
 }
 ```
 
+<!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
@@ -27,31 +32,21 @@ data "oxide_anti_affinity_group" "example" {
 
 ### Optional
 
-- `timeouts` (Attribute, Optional) (see [below for nested schema](#nestedatt--timeouts))
+- `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))
 
 ### Read-Only
 
-- `description` (String) Description of the anti-affinity group.
+- `description` (String) Description for the anti-affinity group.
 - `failure_domain` (String) Describes the scope of affinity for the purposes of co-location.
-- `id` (String) Unique, immutable, system-controlled identifier for the anti-affinity group.
+- `id` (String) Unique, immutable, system-controlled identifier of the anti-affinity group.
 - `policy` (String) Affinity policy used to describe what to do when a request cannot be satisfied.
 - `project_id` (String) ID of the project that contains the anti-affinity group.
 - `time_created` (String) Timestamp of when this anti-affinity group was created.
 - `time_modified` (String) Timestamp of when this anti-affinity group was last modified.
 
 <a id="nestedatt--timeouts"></a>
-
 ### Nested Schema for `timeouts`
 
 Optional:
 
-- `read` (String, Default `10m`)
-
-<a id="nestedobject--digest"></a>
-
-### Nested Schema for `digest`
-
-Read-Only:
-
-- `type` (String) Digest type.
-- `value` (String) Digest type value.
+- `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).

docs/data-sources/floating_ip.md

@@ -0,0 +1,50 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "oxide_floating_ip Data Source - terraform-provider-oxide"
+subcategory: ""
+description: |-
+  
+---
+
+# oxide_floating_ip (Data Source)
+
+
+
+## Example Usage
+
+```terraform
+data "oxide_floating_ip" "example" {
+  project_name = "my-project"
+  name         = "app-ingress"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) Unique, mutable, user-controlled identifier for the floating IP.
+- `project_name` (String) Project name where this floating IP is located.
+
+### Optional
+
+- `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))
+
+### Read-Only
+
+- `description` (String) Human-readable free-form text about the floating IP.
+- `id` (String) Unique, immutable, system-controlled identifier for the floating IP.
+- `instance_id` (String) Instance ID that this floating IP is attached to, if presently attached.
+- `ip` (String) IP address for this floating IP. If unset an IP address will be chosen from the given ip_pool_id.
+- `ip_pool_id` (String) IP pool ID to allocate this floating IP from. If unset the silo's default IP pool is used.
+- `project_id` (String) Project ID where this floating IP is located.
+- `time_created` (String) Timestamp when this floating IP was created.
+- `time_modified` (String) Timestamp when this floating IP was last modified.
+
+<a id="nestedatt--timeouts"></a>
+### Nested Schema for `timeouts`
+
+Optional:
+
+- `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Read operations occur during any refresh or planning operation when refresh is enabled.

docs/data-sources/oxide_image.md renamed to docs/data-sources/image.md

@@ -1,14 +1,18 @@
 ---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "oxide_image Data Source - terraform-provider-oxide"
+subcategory: ""
+description: |-
+  
 ---
 
 # oxide_image (Data Source)
 
-Retrieve information about a specified image.
+
 
 ## Example Usage
 
-```hcl
+```terraform
 data "oxide_image" "example" {
   project_name = "my-project"
   name         = "my-image"
@@ -18,6 +22,7 @@ data "oxide_image" "example" {
 }
 ```
 
+<!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
@@ -26,32 +31,31 @@ data "oxide_image" "example" {
 
 ### Optional
 
-- `project_name` (String) Name of the project that contains the image. Necessary if the image visibility is scoped to a single project.
-- `timeouts` (Attribute, Optional) (see [below for nested schema](#nestedatt--timeouts))
+- `project_name` (String) Name of the project which contains the images
+- `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))
 
 ### Read-Only
 
 - `block_size` (Number) Block size in bytes.
 - `description` (String) Description of the image.
-- `digest` (Object) Hash of the image contents, if applicable (see [below for nested schema](#nestedobject--digest)).
-- `id` (String) Unique, immutable, system-controlled identifier for the image.
+- `digest` (Attributes) Hash of the image contents, if applicable. (see [below for nested schema](#nestedatt--digest))
+- `id` (String) Unique, immutable, system-controlled identifier of the image.
 - `os` (String) OS image distribution.
-- `project_id` (String) ID of the project that contains the image.
+- `project_id` (String) ID of the project which contains the images
 - `size` (Number) Size of the image in bytes.
 - `time_created` (String) Timestamp of when this image was created.
 - `time_modified` (String) Timestamp of when this image was last modified.
 - `version` (String) Version of the OS.
 
 <a id="nestedatt--timeouts"></a>
-
 ### Nested Schema for `timeouts`
 
 Optional:
 
-- `read` (String, Default `10m`)
+- `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
 
-<a id="nestedobject--digest"></a>
 
+<a id="nestedatt--digest"></a>
 ### Nested Schema for `digest`
 
 Read-Only:

docs/data-sources/oxide_images.md renamed to docs/data-sources/images.md

@@ -1,55 +1,60 @@
 ---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "oxide_images Data Source - terraform-provider-oxide"
+subcategory: ""
+description: |-
+  
 ---
 
 # oxide_images (Data Source)
 
-Retrieve a list of all images belonging to a silo or project.
+
 
 ## Example Usage
 
-```hcl
+```terraform
 data "oxide_images" "example" {}
 ```
 
+<!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Optional
 
-- `timeouts` (Attribute, Optional) (see [below for nested schema](#nestedatt--timeouts))
-- `project_id` (String) ID of the project that contains the images.
+- `project_id` (String) ID of the project which contains the images
+- `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))
 
 ### Read-Only
 
-- `images` (List of Object) A list of all global images (see [below for nested schema](#nestedatt--images))
 - `id` (String) The ID of this resource.
+- `images` (Attributes List) (see [below for nested schema](#nestedatt--images))
 
 <a id="nestedatt--timeouts"></a>
-
 ### Nested Schema for `timeouts`
 
 Optional:
 
-- `read` (String, Default `10m`)
+- `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
 
-<a id="nestedatt--images"></a>
 
+<a id="nestedatt--images"></a>
 ### Nested Schema for `images`
 
 Read-Only:
 
 - `block_size` (Number) Block size in bytes.
 - `description` (String) Description of the image.
-- `digest` (Object) Hash of the image contents, if applicable (see [below for nested schema](#nestedobject--digest)).
-- `os` (String) OS image distribution.
-- `id` (String) Unique, immutable, system-controlled identifier for the image.
+- `digest` (Attributes) Hash of the image contents, if applicable. (see [below for nested schema](#nestedatt--images--digest))
+- `id` (String) Unique, immutable, system-controlled identifier of the image.
 - `name` (String) Name of the image.
+- `os` (String) OS image distribution.
 - `size` (Number) Size of the image in bytes.
 - `time_created` (String) Timestamp of when this image was created.
 - `time_modified` (String) Timestamp of when this image was last modified.
 - `version` (String) Version of the OS.
 
-### Nested Schema for `digest`
+<a id="nestedatt--images--digest"></a>
+### Nested Schema for `images.digest`
 
 Read-Only:
 

docs/data-sources/instance_external_ips.md

@@ -0,0 +1,51 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "oxide_instance_external_ips Data Source - terraform-provider-oxide"
+subcategory: ""
+description: |-
+  
+---
+
+# oxide_instance_external_ips (Data Source)
+
+
+
+## Example Usage
+
+```terraform
+data "oxide_instance_external_ips" "example" {
+  instance_id = "c1dee930-a8e4-11ed-afa1-0242ac120002"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `instance_id` (String) ID of the instance to which the external IPs belong to.
+
+### Optional
+
+- `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))
+
+### Read-Only
+
+- `external_ips` (Attributes List) (see [below for nested schema](#nestedatt--external_ips))
+- `id` (String) The ID of this resource.
+
+<a id="nestedatt--timeouts"></a>
+### Nested Schema for `timeouts`
+
+Optional:
+
+- `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
+
+
+<a id="nestedatt--external_ips"></a>
+### Nested Schema for `external_ips`
+
+Read-Only:
+
+- `ip` (String) External IP address.
+- `kind` (String) Kind of external IP address.

docs/data-sources/ip_pool.md

@@ -0,0 +1,48 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "oxide_ip_pool Data Source - terraform-provider-oxide"
+subcategory: ""
+description: |-
+  
+---
+
+# oxide_ip_pool (Data Source)
+
+
+
+## Example Usage
+
+```terraform
+data "oxide_ip_pool" "example" {
+  name = "default"
+  timeouts = {
+    read = "1m"
+  }
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) Name of the IP pool.
+
+### Optional
+
+- `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))
+
+### Read-Only
+
+- `description` (String) Description for the IP pool.
+- `id` (String) Unique, immutable, system-controlled identifier of the IP pool.
+- `is_default` (Boolean) If a pool is the default for a silo, floating IPs and instance ephemeral IPs will come from that pool when no other pool is specified. There can be at most one default for a given silo.
+- `time_created` (String) Timestamp of when this IP pool was created.
+- `time_modified` (String) Timestamp of when this IP pool was last modified.
+
+<a id="nestedatt--timeouts"></a>
+### Nested Schema for `timeouts`
+
+Optional:
+
+- `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).