Terraform Providerのドキュメントは自動生成できる

Terraform Provider のドキュメントの書き方は公式ドキュメント https://developer.hashicorp.com/terraform/registry/providers/docs に記載があります。
この仕様に沿ってドキュメントを書いて適切なパスに配置すれば Terraform Registry 上できれいに表示することができます。

しかし、公式ドキュメント内にもあるように

//go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs

を Provider のコードに書いておけば go generate を実行したときに Provider のソースコードや examples/ 以下のファイルからいい感じにドキュメントを自動生成してくれます。
実はこの tfplugindocs というツールを使えば、公式ドキュメントに書かれているドキュメントの仕様はほとんど意識する必要なくそれっぽいドキュメントが書けてしまいます。

tfplugindocs が自動生成してくれるもの

Provider, Resource, Data Source の Schema は特に意識しなくてもソースコードから自動でドキュメントを生成してくれます。
各 Schema の Description をちゃんと書いておだけでも、そこそこメンテされていそうな Provider に見えます。

tfplugindocs のために用意すべきファイル

ソースコードだけでは自動生成できないドキュメントもあります。
個人的に Terraform Provider を使うときに用意されていてほしい機能2つを紹介します。

Example Usage

examples/ 以下に .tf ファイルを置くとドキュメントの上部に Provider, Resource, Data Source の使い方を入れることができます。

Schema の説明だけでは利用者から見ると何を入れればいいのか分からないことが多いので、使用例があるととても助かります。
個人的に Example Usage が用意されている Provider はちゃんとメンテされているように感じて利用しやすくなる気がします。

普段 .tf ファイルを書くように例を書いて、決められたパスに配置します。

Provider examples/provider/provider.tf
Data Source examples/data-sources/<data source name>/data-source.tf
Resource examples/resources/<resource name>/resource.tf

複数のコードブロックを書くことはできないようなので、複数のリソースを書く場合は空行を使って区切るのがよいと思います。

resource "travis_env_var" "public_value" {
  repository_slug = "bgpat/test"
  name            = "PUBLIC_VALUE"
  public_value    = "public"
}

resource "travis_env_var" "secret_values" {
  for_each      = toset(["foo", "bar", "buzz"])
  repository_id = 2562785
  name          = "SECRET_VALUE_${upper(each.key)}"
  value         = each.value
}

Terraform Registry 上では以下のように表示されます。

Import

examples/ 以下に import.sh を置くとドキュメント下部に terraform import の例のコマンドを書くことができます。
Import は terraform [global options] import [options] ADDR ID の ID に当たる部分の指定が難しいことが多く、使用例が書かれていないと Provider のソースコードを読まないと何を入れていいか分からないので開発者の方にはぜひ書いておいてほしいです。

import.sh の内容はそのままコードブロックとしてドキュメントに挿入されるので、 $ 等は付けずに実行するコマンドをそのまま書きます。

terraform import travis_env_var.public_value bgpat/test/PUBLIC_VALUE

複数の書き方がある場合は # でコメントを書いて空行で分割するのがよいと思います。

# ${repository_id}/${name}
terraform import travis_env_var.public_value bgpat/test/PUBLIC_VALUE

# ${repository_slug}/${name}
terraform import 'travis_env_var.secret_values["foo"]' 2562785/SECRET_VALUE_FOO

Terraform Registry 上では以下のように表示されます。

まとめ

Terraform Providerのドキュメントは tfplugindocs で自動生成できる
tfplugindocs 用に examples/ ディレクトリ以下に使用例を置けば利用者にやさしいドキュメントが生成できる