Generate docs with go generator

[displague]

It is now possible to generate provider docs using the https://www.terraform.io/docs/registry/providers/docs.html#generating-documentation generator and fields embedded in the provider.

Can we generate all of our documentation identically in this way?

The generator is noted to have some weakness handling deep structures.

Some example repositories using this method:

• https://registry.terraform.io/providers/hashicorp/boundary/latest/docs
• https://registry.terraform.io/providers/paultyng/unifi/latest/docs
• https://registry.terraform.io/providers/paultyng/sql/latest/docs

[t0mk]

I have just tried tfplugindocs in this provider. It nicely generated all the markdown files to the docs/ dir.

However, to take full advantage of tfplugindocs (to have docs build on go generate from the repo root) we'd need to

• copy description from our written docs to Description attr of each field of the resource schema
• update terraform-plugin-sdk to (at least) newest 1x version, so that we can add Description field of schema.Resource for every resource (and I guess datasource too)
• create examples/{data-sources,provider,resources} dirs with contents described in https://github.com/hashicorp/terraform-plugin-docs#conventional-paths
• reformat all the examples from the current docs into files like e.g. examples/resources/metal_device/resource.tf
• add tfplugindocs as "tools model" dependency, i.e. in tools/tools.go:

  // +build tools
  
  package tools
  
  //go:generate go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
  
  import (
    // docs generator
    _ "github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs"
  )
  

• add //go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs to <repo_dir>/main.go

[ocobles]

The drafts pull request https://github.com/equinix/terraform-provider-metal/pull/15 and https://github.com/equinix/terraform-provider-metal/pull/132 created at equinix/terraform-provider-metal have been closed without resolution due to the complexity of migrating that work to this repository. Any related work must be recreated. Relevant information from the conversation is linked below:

https://github.com/equinix/terraform-provider-metal/pull/15#issuecomment-750300896

Have a look at this thread, https://github.com/tinkerbell/terraform-provider-tinkerbell/pull/20#discussion_r542100422 and this commit https://github.com/tinkerbell/terraform-provider-tinkerbell/commit/1d2377da4208ffc773fe6738b3ff2d08c3c9a317.

I think this provides a cleaner approach to introducing this bit of tooling without adding dozens of new requirements.

[ctreatma]

The provider will likely need to adopt documentation generation in a major version release, because we cannot generate docs in the current structure where files are prefix with equinix_: (https://github.com/hashicorp/terraform-plugin-docs/issues/347). Our current file naming convention does not align with the standards proposed by Hashicorp and implemented in the generator.

Rather than fork the generator or do extra workarounds to rename files after generation, we should align with the standards that are implemented by the generator and that are used by other providers; that means breaking existing docs pages because there's no way to redirect those old URLs.