用途:为 Terraform Registry 创建、更新和审阅 Terraform Provider 文档,遵循 HashiCorp 推荐模式、tfplugindocs 模板与 schema 描述。
主要能力:
- 将代码变更映射到具体文档目标:provider 索引、资源、数据源、临时资源、列表资源、函数、动作或指南。
- 决定内容来自 schema 描述、模板或两者。
- 按 HashiCorp 推荐模板路径在 docs/ 下管理模板,如 docs/index.md.tmpl、docs/resources/<name>.md.tmpl、docs/data-sources/<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、docs/guides/<name>.md.tmpl。
- 用 tfplugindocs 生成文档,并在每次 schema 或模板改动后重新生成。
- 校验生成 markdown,核对示例 HCL 与参数/属性名、必填/可选/计算语义是否与 schema 一致。
- 发布前应用 Registry 规则:语义化版本标签以 v 开头(如 v1.2.3)、从默认分支打标签、仓库根保留 terraform-registry-manifest.json。
使用方式:先写 schema 描述,再在 docs/ 添加或更新模板;模板聚焦概览与示例,字段级细节依赖生成段。HCL 示例放在 examples/ 目录,每文件一个示例,用 tffile 引入模板,示例不得包含 terraform、provider 或 output 块。优先用仓库默认 go generate ./...,否则运行 go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>。生成后校验 docs/、示例与语义。必要时按 HashiCorp 预览流程检查渲染结果;Registry 缺文档时检查标签格式、来源分支、manifest 文件与发布状态。
限制与质量要求:文档须行为准确,不描述不支持的参数或属性;示例保持最小、真实、可运行;术语命名一致;避免在手工模板中重复生成的参数/属性块;文档变更尽量与 schema/API 变更同一 PR。按需读取 references/hashicorp-provider-docs.md 中与当前改动相关的章节。其他细节暂未提供。