When I first started writing my Terraform modules, inside organizations or on my own, I struggled with the idea of creating useful documentation for them, and specially looking at the official Terraform Registry it became obvious there should be a way of keeping my README files up to date and useful without a lot of pain, so I started looking for something to solve these issues.

Eventually I found a tool called "terraform-docs", yeah, pretty straightforward! After testing it for a while it was basically the answer to all my prayers, just to name a few of this tool's capabilities:

• very simple configuration syntax;
• generates markdown valid output;
• replaces or appends to your existing README files;
• can mix the automatic stuff with your own content;
• the results are really useful and look good;

And besides those, when I got to it, there's a handy GitHub Action to make these updates fully automatic even if you commit new stuff without updating the README file, the workflow runs and updates it for you!

Here is the one example of the results:

First: Do It Locally

To achieve this I created a "default" configuration file for terraform-docs named .terraform.docs.yml and it looks something like this:

formatter: "markdown"

recursive:
  enabled: true
  path: examples

output:
  file: "README.md"
  mode: replace

settings:
  color: false
  description: "true"
  hide-empty: true
  read-comments: true
  sensitive: true
  lockfile: true

sort:
  enabled: true
  by: required

Then I downloaded the tool itself following these steps, found on the official guide:

curl -sSLo ./terraform-docs.tar.gz https://terraform-docs.io/dl/v0.16.0/terraform-docs-v0.16.0-$(uname)-amd64.tar.gz
tar -xzf terraform-docs.tar.gz
chmod +x terraform-docs
mv terraform-docs /some-dir-in-your-PATH/terraform-docs

After the download all I had to do was run terraform-docs . from my command line inside of the module's directory and it was done!

Now: Using GitHub Actions

Assuming you have the .terraform-docs.yml file on your repository as shown above you just need to create a new workflow, with whatever name you want it to have, mine is just "Terraform Docs", and it should look like this:

name: Terraform Docs

on:
  push:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: terraform-docs-gh-actions
        uses: terraform-docs/gh-actions@v1.0.0
        with:
          config-file: .terraform-docs.yml
          git-push: true
          git-push-sign-off: true

And, now you just have to wait for it to run, and you will be good to go!

Considerations

The configuration file used for terraform-docs is just an example, and even if it works for me, it may not work for you or your organization, so this is what you need to know to create your own:
terraform-docs configuration guide

Also, the installation process may not work in a non-linux environment, so if you are working on Mac or Windows, you will need to use a different approach like the ones listed here:
terraform-docs installation guide

About GitHub Actions and Workflows, I assumed for this article you know the basics of it, but if you need help seting up your workflow, you should definitely check out this quickstart guide:
GitHub Actions Quickstart

If you are wondering what the official docs on Terraform's Registry look like, here is an example:
Terraform Registry Example

Finally, if you are wondering how to publish your Terraform Modules on the Official Registry, here's how you do it:
How to Publish a Terraform Module on the Official Registry

More Content

If this article helped you or someone you know and you want to know more of these useful tools or tips for your IaC needs, follow me on LinkedIn, here or on GitHub and don't miss my updates!