Adapt provider to generate docs automatically

[t0mk]

fixes equinix/terraform-provider-equinix#201

This PR migrates docs from the old style to template-style, so that the provider can take advantage of https://github.com/hashicorp/terraform-plugin-docs and generate TF website documentation automatically.

It's mainly about creating content in templates/ and examples/ dirs, and moving generic resource/datasource description from markdown files in docs/ to the resource Description attribute in code.

What needs to be done

• create index template
• create templates for guides
• add Description attribute to existing resources and datasources in metal/. Use content from existing docs.
• add examples to examples/resources/.. and examples/datasources/... Use content from existing docs.
• consider automatic doc generation with //go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs

The docs can also be generated manually with tfplugindocs validate && tfplugindocs generate.

[t0mk]

@displague take a look please. You don't have to go thought the whole diff, just check how generated metal_device doc look:
https://github.com/equinix/terraform-provider-metal/pull/132/files#diff-ec99d3005acccacc6feb97265143c7f156ce6ccbd20258aa4186a6328d358bdc

For some reason the doc generation doesn't pick the nested attributes, although they are described, e.g. the network:
https://github.com/t0mk/terraform-provider-metal/blob/generate_docs_3/metal/resource_metal_device.go#L211

Anyway, all there is to define a resource doc is

• Description string of the resource in code
• Description strings of the attributes
• example HCL in examples/resoources/<name>/resource.tf

These inputs will be processed to create docs/resources/<name>.md. That's very lightweight and easy to maintain and write. It's also possible to define template per resource or datasource, but maybe we should do that only when we really need to say sth out of the examples.

If you OK the format of metal_device doc, I will convert other resources and datasources.

I am not sure if the doc generation should be done with go generate. Maybe it's cleaner to do it manually with the cli tool before release. What do you think?

[displague]

I am not sure if the doc generation should be done with go generate. Maybe it's cleaner to do it manually with the cli tool before release. What do you think?

We can include a make gen and fail the build if the code has changed. https://github.com/packethost/packet-cli/blob/master/.github/workflows/ci.yml#L36-L37 does this.

The expectation is that anyone making a PR to supply resource updates will also update the docs when needed.

[displague]

For some reason the doc generation doesn't pick the nested attributes, although they are described, e.g. the network:
https://github.com/t0mk/terraform-provider-metal/blob/generate_docs_3/metal/resource_metal_device.go#L211

hashicorp/terraform-plugin-docs#64

[displague]

kreuzwerker/terraform-provider-docker#193 points out some other issues we should be aware of:

• for default values: feat: add default values to attributes to documentation hashicorp/terraform-plugin-docs#65
• for rendering read-only blocks: bug: attribute descriptions are not rendered in read-only nested block hashicorp/terraform-plugin-docs#66

hashicorp/terraform-plugin-docs#69 is a little concerning.

[displague]

Generally, @t0mk, I think we can merge and move forward. If we lose some detail in the docs, we will drive for fixes or changes in terraform-plugin-docs. It seems we'll have everything we need to generate (rather than hand maintain) good docs.

[ocobles]

The issue linked to this PR has been transferred to equinix/terraform-provider-equinix: equinix/terraform-provider-equinix#201

This draft is outdated and the migration to the new provider repository introduces more complexity than a fresh start. I will add a reference to this draft in the transferred issue to take advantage of the conversation and the templates already created