tfplugindocs で Terraform Provider のドキュメントを生成する

この記事は [terraform Advent Calendar 2023](https://qiita.com/advent-calendar/2023/terraform) の5日目の記事です

Terraform Provider を自作するときにドキュメントの書き方について調べたのでまとめようと思います。

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

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

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

```go
//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`

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

```hcl
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 上では以下のように表示されます。

[![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/69029/adfb04ec-da49-83c6-6fcb-e23cadbcfd50.png)](https://registry.terraform.io/providers/bgpat/travis/latest/docs/resources/env_var#example-usage)

### Import

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

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

```bash
terraform import travis_env_var.public_value bgpat/test/PUBLIC_VALUE
```

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

```bash
# ${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 上では以下のように表示されます。
[![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/69029/3a2a52e5-cada-fff4-f741-adda67b07d29.png)](https://registry.terraform.io/providers/bgpat/travis/latest/docs/resources/env_var#import)

## まとめ

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