mcpField
P
provider-docs

provider-docs

github.com/hashicorp开发9093.2k 次安装今天更新
代码仓库

关于 provider-docs

使用 Schema 描述、模板和 tfplugindocs 编写 Terraform Provider 文档的工作流指南，帮助维护生成文档、示例和验证的准确性，并检查 Registry 发布准备情况。

主要功能

  1. 01将代码变更对应到文档目标
  2. 02编写 Schema 描述和模板
  3. 03使用 tfplugindocs 生成文档
  4. 04校验生成的 Markdown 和 HCL 示例
  5. 05检查 Registry 发布要求

适用场景

  1. 01编写 Provider 资源或数据源文档
  2. 02Schema 变更后更新文档
  3. 03准备向 Registry 发布 Provider 文档

安装

复制下面的命令，在终端中运行。

$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. 确认范围和文档目标。
  • 将代码更改映射到确切的文档目标：Provider 索引、资源、数据源、临时资源、列表资源、函数、操作或指南。
  • 确定内容应来自架构描述、模板，还是两者兼有。
  1. 先编写架构描述。
  • 为架构字段添加准确的面向用户的描述，使生成的文档与实际行为保持一致。
  • 确保措辞具体说明参数用途、约束、默认值和计算行为。
  1. 在 docs/ 中添加或更新模板文件。
  • 只创建与已实现的 Provider 对象对应的文件。
  • 使用 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/ 目录中——每个文件放一个示例，并通过 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/ 中的文件与当前 Provider 实现一致。
  • 确认示例是有效的 HCL，并反映当前的参数和属性名称。
  • 确认文档中的必填、可选和计算语义与架构行为一致。
  1. 发布前遵循 Registry 发布规则。
  • 使用带 v 前缀的语义化版本标签（例如 v1.2.3）。
  • 从默认分支创建发布标签。
  • 在仓库根目录保留 terraform-registry-manifest.json。
  • 预计文档会在 Registry 中按版本管理，并可通过版本选择器切换。
  1. 按需预览发布效果或排查问题。
  • 如果准确性风险较高，请使用 HashiCorp 的预览流程，在发布前检查渲染后的文档。
  • 如果文档未显示在 Registry 中，请检查标签格式、标签来源分支、清单文件是否存在，以及 Provider 的发布状态。

遵守质量标准

  • 确保文档准确描述实际行为；绝不描述不受支持的参数或属性。
  • 示例应简洁、贴近实际且可运行。
  • 确保 Provider、资源和数据源中的术语与命名保持一致。
  • 避免在手动编写的模板中重复生成的参数或属性代码块。
  • 尽可能将文档更改与架构或 API 更改放在同一个 PR 中。

按需加载参考资料

  • 阅读 references/hashicorp-provider-docs.md，了解有源代码依据的规则和官方链接。
  • 仅加载当前更改所需的章节，以精简上下文。

评论

支持 Markdown