feat!: generate docs from code

[ctreatma]

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 is to keep docs in a file named <resource>.md (without the equinix_ prefix), and the terraform-plugin-docs tool strictly follows this recommendation. 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. Updating specific templates is the responsibility of each engineering team.

Closes #201

[displague]

The generated markdown does not include the subcategory frontmatter (Metal, Fabric, ...).

The generated example .tf files look promising. It should make it easier to validate that the examples are accurate.
How are they derived? Are they embedded in the rendered documentation?

Validated examples could help with crossplane-contrib/provider-jet-equinix#29 (comment)

[ctreatma]

The generated markdown does not include the subcategory frontmatter (Metal, Fabric, ...).

PR was in a weird state, none of the templates were present.

The generated example .tf files look promising. It should make it easier to validate that the examples are accurate.
How are they derived? Are they embedded in the rendered documentation?

The examples were extracted from the hand-written docs during tfplugindocs migrate. They are referenced in the templates for inclusion in the generated docs.

The templates are all generated from the existing docs, so there isn't a whole lot of true generation happening in this PR yet. In the few places where templates have been updated to use more generation (provider and device resource as of now), there is still quite a bit of work to do to move or reproduce descriptions and the like so that they are picked up by the generator to reduce the diff between the hard-coded and generated docs.

[ctreatma]

Might as well wait for #683 before pursuing docs generation

[displague]

Could include or rebase off #685

[ctreatma]

This PR is now based on & blocked by #683.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

Attention: Patch coverage is 68.18182% with 7 lines in your changes missing coverage. Please review.

Project coverage is 34.44%. Comparing base (503d9e1) to head (0fd2754).
Report is 83 commits behind head on main.

Files	Patch %	Lines
internal/provider/provider.go	0.00%	7 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #645      +/-   ##
==========================================
- Coverage   37.91%   34.44%   -3.47%     
==========================================
  Files         120      151      +31     
  Lines       19476    20634    +1158     
==========================================
- Hits         7384     7108     -276     
- Misses      11884    13364    +1480     
+ Partials      208      162      -46     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[ctreatma]

@equinix/governor-digin-fabric @equinix/governor-ne-network-edge-engineering please take a look. This PR does not change the contents of your documentation, although it does change the URL for some pages to match the convention recommended by Hashicorp and used by the vast majority of terraform providers (for example /equinix_metal_device => /metal_device or /equinix_network_ssh_key => /network_ssh_key; some Fabric resources already had the correct URL).

[ocobles]

looks pretty good! I like the docs-check approach too simple and useful

[thogarty]

All good from a Fabric perspective. Looking forward to a point where we can start reducing the number of templates to allow the process to handle generation fresh once we get a handle on it.

Thanks, Charles!