feat!: generate docs from code (#645)

Our existing provider docs are prone to errors because we transcribe
attribute descriptions, deprecations, etc. back and forth between the
code and docs by hand. By generating docs from code, we reduce the
overhead of providing accurate, up-to-date docs for our customers.

Note that this is a breaking change because, prior to this PR, docs for
an Equinix resource or data source were kept in a file named
`equinix_<resource>.md`. The [recommendation from
Hashicorp](https://developer.hashicorp.com/terraform/registry/providers/docs#typical-structure)
is to keep docs in a file named `<resource>.md` (without the `equinix_`
prefix), and the `terraform-plugin-docs` tool [strictly follows this
recommendation](hashicorp/terraform-plugin-docs#347 (comment)).
This means that adopting docs generation would move our existing docs
from, e.g.
`https://registry.terraform.io/providers/equinix/equinix/latest/docs/resources/equinix_metal_vrf`
to
`https://registry.terraform.io/providers/equinix/equinix/latest/docs/resources/metal_vrf`.

This PR adopts docs generation as follows:
- Run `tfplugindocs migrate` to create templates from our existing docs
- Run `tfplugindocs generate` to regenerate the docs from the
newly-created templates

**NOTE** the scope of this PR is to move our docs to align with the
HashiCorp's recommended structure & naming conventions and to provide
[an example of updating existing templates to automatically generate
resource / datasource attribute
details](37c4d06).
Updating specific templates is the responsibility of each engineering
team.

Closes #201

.github/workflows/test.yml

@@ -6,9 +6,28 @@ on:
     branches:
     - main
 
-
 jobs:
 
+  validate_docs:
+    name: Validate docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: './go.mod'
+        id: go
+
+      - name: Get dependencies
+        run: go mod download
+
+      - name: Check that all docs changes are committed
+        run: |
+          make docs-check
+
   test:
     name: Test
     runs-on: ubuntu-latest

CODEOWNERS

@@ -3,9 +3,10 @@
 *                       @equinix/governor-devrel-engineering
 /cmd/migration-tool     @equinix/governor-metal-client-interfaces
 *metal*                 @equinix/governor-metal-client-interfaces
+docs/guides/network_types.md      @equinix/governor-metal-client-interfaces
 *fabric*                @equinix/governor-digin-fabric
 *connection_e2e*        @equinix/governor-digin-fabric
 *resource_network_*     @equinix/governor-ne-network-edge-engineering
-*equinix_network_*      @equinix/governor-ne-network-edge-engineering
+docs/**/network_*      @equinix/governor-ne-network-edge-engineering
 *data_source_network_*  @equinix/governor-ne-network-edge-engineering
 **/edge-networking      @equinix/governor-ne-network-edge-engineering

CONTRIBUTING.md

@@ -19,6 +19,8 @@ Available via [https://github.com/equinix/terraform-provider-equinix/blob/main/.
 
 Please submit change requests and / or features via [Issues](https://github.com/equinix/terraform-provider-equinix/issues). There's no guarantee it'll be changed, but you never know until you try. We'll try to add comments as soon as possible, though.
 
+All resource and data source changes must be reflected in the documentation, including new attributes and changes to existing attributes. The documentation is generated via `make docs`.  For more detailed instructions for updating docs, see ["Documenting the provider" in the development guide](./DEVELOPMENT.md#documenting-the-provider).
+
 ## How to Report a Bug
 
-Bugs are problems in code, in the functionality of an application or in its UI design; you can submit them through [Issues/(https://github.com/equinix/terraform-provider-equinix/issues) as well.
+Bugs are problems in code, in the functionality of an application or in its UI design; you can submit them through [Issues](https://github.com/equinix/terraform-provider-equinix/issues) as well.

DEVELOPMENT.md

@@ -6,6 +6,19 @@
 * [Go](https://golang.org/doc/install) 1.18 (to build the provider plugin)
 * [GNU Make](https://www.gnu.org/software/make) (to build and test easier)
 
+## Documenting the provider
+
+This project uses HashiCorp's [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs) tool to generate docs. In particular, keep the [terraform-plugin-docs conventional paths](https://github.com/hashicorp/terraform-plugin-docs?tab=readme-ov-file#conventional-paths) in mind when adding or updating docs for a resource or data source.  The conventional paths will tell you where to put examples if you are using the default templates.
+
+Templates for documentation are stored in the `templates` directory.  The following default templates exist; try using them first and only add a resource- or data-source-specific template when needed:
+
+- Resource default template: templates/resources.md.tmpl
+- Datasource default template: templates/data-sources.md.tmpl
+
+The documentation can be generated from the `templates` and `examples` directories using the `make docs` task.  The `make check-docs` task is run in CI for every PR to ensure that all necessary docs changes have been committed and pushed to GitHub.
+
+**NOTE**: `terraform-plugin-docs` is focused on provider, resource, and datasource documentation.  Guides must be created in the `templates` directory, but they cannot use templating functions; the `templates/guides` directory is copied to the `docs` directory as-is.
+
 ## Building the provider
 
 *Note:* This project uses [Go Modules](https://blog.golang.org/using-go-modules)

GNUmakefile

@@ -73,6 +73,17 @@ test-compile:
 	fi
 	go test -c $(TEST) $(TESTARGS)
 
+.PHONY: docs docs-check
+
+docs:
+	go generate ./...
+
+docs-check: docs
+	if git status --porcelain | grep docs; then \
+		echo "Uncommitted changes detected. Run 'make docs' and commit changes."; \
+		exit 1; \
+	fi
+
 docs-lint:
 	@echo "==> Checking docs against linters..."
 	@misspell -error -source=text docs/ || (echo; \

docs/data-sources/equinix_fabric_cloud_router.md → docs/data-sources/fabric_cloud_router.md

@@ -11,12 +11,12 @@ description: |-
 Fabric V4 API compatible data resource that allow user to fetch Fabric Cloud Router for a given UUID
 
 Additional documentation:
-* Getting Started: <https://docs.equinix.com/en-us/Content/Interconnection/FCR/FCR-intro.htm#HowItWorks>
-* API: <https://developer.equinix.com/dev-docs/fabric/api-reference/fabric-v4-apis#fabric-cloud-routers>
+* Getting Started: https://docs.equinix.com/en-us/Content/Interconnection/FCR/FCR-intro.htm#HowItWorks
+* API: https://developer.equinix.com/dev-docs/fabric/api-reference/fabric-v4-apis#fabric-cloud-routers
 
 ## Example Usage
 
-```hcl
+```terraform
 data "equinix_fabric_cloud_router" "cloud_router_data_name" {
   uuid = "<uuid_of_cloud_router>"
 }
@@ -63,6 +63,7 @@ output "type" {
 ```
 
 <!-- schema generated by tfplugindocs -->
+
 ## Schema
 
 ### Required
@@ -92,14 +93,15 @@ output "type" {
 - `type` (String) Defines the FCR type like; XF_ROUTER
 
 <a id="nestedatt--account"></a>
+
 ### Nested Schema for `account`
 
 Read-Only:
 
 - `account_number` (Number)
 
-
 <a id="nestedatt--change_log"></a>
+
 ### Nested Schema for `change_log`
 
 Read-Only:
@@ -117,8 +119,8 @@ Read-Only:
 - `updated_by_full_name` (String)
 - `updated_date_time` (String)
 
-
 <a id="nestedatt--location"></a>
+
 ### Nested Schema for `location`
 
 Read-Only:
@@ -128,8 +130,8 @@ Read-Only:
 - `metro_name` (String)
 - `region` (String)
 
-
 <a id="nestedatt--notifications"></a>
+
 ### Nested Schema for `notifications`
 
 Read-Only:
@@ -138,8 +140,8 @@ Read-Only:
 - `send_interval` (String)
 - `type` (String)
 
-
 <a id="nestedatt--order"></a>
+
 ### Nested Schema for `order`
 
 Read-Only:
@@ -149,20 +151,19 @@ Read-Only:
 - `order_number` (String)
 - `purchase_order_number` (String)
 
-
 <a id="nestedatt--package"></a>
+
 ### Nested Schema for `package`
 
 Read-Only:
 
 - `code` (String)
 
-
 <a id="nestedatt--project"></a>
+
 ### Nested Schema for `project`
 
 Read-Only:
 
 - `href` (String)
 - `project_id` (String)
-