Migrating to auto-generated Terraform Registry documentation

For the longest time, Terraform Registry documentation has been manually updated as the resource is created or modified. This has always been painful to remember and keep in sync given the number of sources of documentation already out there for the Cloudflare provider. However, that is all changing with terraform-plugin-docs.

terraform-plugin-docs uses the provider schema to generate consistent and automatic documentation. As of v0.9.0, the tool is mature and configurable enough for most providers. So, how do we migrate to it?

Repository changes

At a high level, terraform-plugin-docs has some inbuilt concepts for the directory structure.

• docs/{resources,data-sources,guides}: This is where the generated output ends up.
• examples/{resources,data-sources,guides}: Sub directories of examples. Each directory contains the Terraform resource examples that are used for the “example usage” sections of the documentation.
• templates/{resources,data-sources,guides}: Templates are the files used as a blueprint to generate the outputs. In this directory, files with the extension ".md" (markdown) are copied over verbatim whereas files with the extension "md.tmpl" (templated markdown) are parsed through Go’s text/template package before rendering.

The Terraform documentation touches on some of these steps, however, leaves alot to be desired when it comes to migrating from an existing setup. Here are the steps I took:

• Move website/docs to a top level templates directory. This will allow us to copy over the existing documentation verbatim.
• Expand inner subdirectories to be their full representations.
  • docs/d => docs/data-sources
  • docs/r => docs/resources
• Change file suffixes from .html.markdown or .html.md to .md.
• Rename all files to match the resource/datasource names. This is important as otherwise, it will try to generate them all and you’ll end up with duplicate documentation.
• Moved contributing docs to a top level directory.
• Add make targets for generating documentation.

For a Pull Request demonstrating the change, check out cloudflare/terraform-provider-cloudflare#1680.

Using this approach allows us to keep our existing documentation until we explicitly cut over the resources to automatic generation.

Resource/datasource/guide changes

As for individual resources, there are only two (well, technically 3) steps:

• Update the schema fields to be decorated with Description attributes.
• Delete the old documentation from the respective templates directory.
• Run make docs and commit the changes.

Again, for a Pull Request demonstrating the change, have a look at migrating cloudflare_rulesets via cloudflare/terraform-provider-cloudflare#1677.