mcpField
P
provider-docs

provider-docs

github.com/hashicorp開発9093.2k 回インストール今日更新
リポジトリ

provider-docs について

スキーマの説明、テンプレート、tfplugindocs を使って Terraform Provider のドキュメントを作成するワークフローガイドです。生成ドキュメントや例の正確性を保ち、検証と Registry 公開の準備を支援します。

主な機能

  1. 01コード変更をドキュメント対象に対応付け
  2. 02スキーマ説明とテンプレートの作成
  3. 03tfplugindocs によるドキュメント生成
  4. 04生成 Markdown と HCL 例の検証
  5. 05Registry 公開要件の確認

活用シーン

  1. 01Provider のリソースやデータソースの文書化
  2. 02スキーマ変更後のドキュメント更新
  3. 03Provider ドキュメントの Registry 公開準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/hashicorp/agent-skills --skill provider-docs

インストール後、Claude Code で/provider-docsを入力して読み込まれたか確認します。

同梱ファイルagents/openai.yamlreferences/hashicorp-provider-docs.md

詳細

Terraform Provider のドキュメント

次のワークフローに従う

  1. 対象範囲とドキュメントの対象を確認します。
  • コードの変更を、プロバイダーのインデックス、リソース、データソース、一時リソース、リストリソース、関数、アクション、ガイドのうち、該当する正確なドキュメントの対象に対応付けます。
  • 内容をスキーマの説明、テンプレート、またはその両方から作成するかを決めます。
  1. まずスキーマの説明を作成します。
  • 生成されるドキュメントが動作と一致するように、スキーマフィールドにユーザー向けの正確な説明を追加します。
  • 引数の目的、制約、デフォルト値、計算される動作を具体的に記述します。
  1. 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/actions/<name>.md.tmpl（tfplugindocs は Terraform v1.14.0+ でアクションのドキュメントを生成します）
    • docs/guides/<name>.md.tmpl
  • テンプレートは概要と例に絞り、フィールドごとの詳細は生成されるセクションに任せます。
  • HCL の例はテンプレートに直接記述せず、examples/ ディレクトリに配置してください。ファイルごとに例を 1 つ作成し、tffile でテンプレートに取り込みます（references/hashicorp-provider-docs.md の「Example File Conventions」を参照）。例には terraform、provider、output ブロックを含めないでください。
  • アクションのページでは、references/hashicorp-provider-docs.md の「Action Pages」セクションにある構成に従います。例には action ブロックと action_trigger のライフサイクル設定の両方を示し、アクションには属性／出力セクションを設けません。
  1. tfplugindocs でドキュメントを生成します。
  • リポジトリにデフォルト設定がある場合は、そちらを優先します。
go generate ./...
  • それ以外の場合は、ジェネレーターを直接実行します。
go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>
  • スキーマまたはテンプレートを編集するたびに、生成を再実行します。
  1. 生成された Markdown を検証します。
  • docs/ のファイルが現在のプロバイダーの実装と一致することを確認します。
  • 例が有効な HCL であり、現在の引数名／属性名を反映していることを確認します。
  • ドキュメントに記載された必須／任意／計算済みの意味が、スキーマの動作と一致することを確認します。
  1. リリース前に Registry の公開ルールを適用します。
  • v を先頭に付けたセマンティックバージョンのタグを使用します（例：v1.2.3）。
  • デフォルトブランチからリリースタグを作成します。
  • terraform-registry-manifest.json をリポジトリのルートに置きます。
  • ドキュメントは Registry でバージョン管理され、バージョンセレクターで切り替えられるようになります。
  1. 必要に応じて、公開をプレビューまたはトラブルシューティングします。
  • 正確性に懸念がある場合は、リリース前に HashiCorp のプレビュープロセスを使って、レンダリングされたドキュメントを確認します。
  • Registry にドキュメントが表示されない場合は、タグの形式、タグの作成元ブランチ、マニフェストファイルの有無、プロバイダーの公開状況を確認します。

品質基準を徹底する

  • ドキュメントを実際の動作に正確に合わせ、サポートされていない引数や属性について記述しないでください。
  • 例は簡潔で現実的なものにし、実行できる状態にしてください。
  • プロバイダー、リソース、データソース全体で、用語と命名を統一してください。
  • 手動のテンプレートで、生成される引数／属性ブロックを重複させないでください。
  • 可能な限り、ドキュメントの変更をスキーマ／API の変更と同じ PR に含めてください。

必要に応じてリファレンスを読み込む

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

コメント

Markdown 対応