Terraform Provider Docs

このワークフローに従う

1. スコープとドキュメント対象を確認する。

• コード変更をドキュメント対象にマッピングする: プロバイダーインデックス、リソース、データソース、エフェメラルリソース、リストリソース、関数、またはガイド。
• コンテンツがスキーマ説明、テンプレート、またはその両方から来るかを決定する。

2. スキーマ説明を最初に書く。

• スキーマフィールドに正確なユーザー向けの説明を追加して、生成されたドキュメントが動作と一致するようにする。
• 引数の目的、制約、デフォルト値、および計算された動作に固有の表現を保つ。

3. docs/ にテンプレートファイルを追加または更新する。

• 実装されたプロバイダーオブジェクトにマッピングされるファイルのみを作成する。
• HashiCorp推奨のテンプレートパスを使用する:
  • docs/index.md.tmpl
  • docs/data-sources/<name>.md.tmpl
  • docs/resources/<name>.md.tmpl
  • docs/ephemeral-resources/<name>.md.tmpl
  • docs/list-resources/<name>.md.tmpl
  • docs/functions/<name>.md.tmpl
  • docs/guides/<name>.md.tmpl
• テンプレートは概要と例に焦点を当て、フィールドごとの詳細は生成セクションに依存する。

4. tfplugindocs でドキュメントを生成する。

• 設定された場合はリポジトリデフォルトを優先する:

go generate ./...

• それ以外の場合はジェネレーターを直接実行する:

go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>

• スキーマまたはテンプレート編集のたびに生成を再実行する。

5. 生成された Markdown を検証する。

• docs/ 内のファイルが現在のプロバイダー実装と一致することを確認する。
• 例が有効な HCL であり、現在の引数/属性名を反映していることを確認する。
• ドキュメント内の必須/オプション/計算済みセマンティクスがスキーマ動作と一致することを確認する。

6. リリース前に Registry 公開ルールを適用する。

• v で始まるセマンティックバージョンタグを使用する (例: v1.2.3)。
• デフォルトブランチからリリースタグを作成する。
• リポジトリルートに terraform-registry-manifest.json を保つ。
• ドキュメントが Registry でバージョン管理され、バージョンセレクターで切り替え可能になることを想定する。

7. 必要に応じてプレビューまたは公開のトラブルシューティングを行う。

• 精度リスクが高い場合は、HashiCorp プレビュープロセスを使用してリリース前にレンダリングされたドキュメントを検査する。
• ドキュメントが Registry に表示されていない場合は、タグ形式、タグソースブランチ、マニフェストファイルの存在、およびプロバイダー公開ステータスを確認する。

品質基準を強制する

• ドキュメントを動作的に正確に保つ; サポートされていない引数または属性について説明しない。
• 例は最小限、現実的、かつ実行可能に保つ。
• プロバイダー、リソース、およびデータソース全体で用語と命名を一貫して保つ。
• 手動テンプレートで生成された引数/属性ブロックの重複を避ける。
• スキーマ/API 変更と同じ PR にドキュメント変更を関連付ける。

必要に応じて参照を読み込む

• ソースに基づいたルールと公式リンクについては references/hashicorp-provider-docs.md を読む。
• コンテキストをリーンに保つために、現在の変更に必要なセクションのみを読み込む。