Back to Details

provider-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Terraform Provider Docs

Terraform Provider 文档

Follow This Workflow

遵循以下工作流

  1. Confirm scope and documentation targets.
  • Map code changes to the exact doc targets: provider index, resources, data sources, ephemeral resources, list resources, functions, or guides.
  • Decide whether content should come from schema descriptions, templates, or both.
  1. Write schema descriptions first.
  • Add precise user-facing descriptions to schema fields so generated docs stay aligned with behavior.
  • Keep wording specific to argument purpose, constraints, defaults, and computed behavior.
  1. Add or update template files in 
    docs/
    .
  • Create only files that map to implemented provider objects.
  • Use HashiCorp-recommended template paths: 
    • 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
  • Keep templates focused on overview and examples; rely on generated sections for field-by-field details.
  1. Generate documentation with 
    tfplugindocs
    .
  • Prefer repository defaults when configured:
bash
go generate ./...
  • Otherwise run the generator directly:
bash
go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>
  • Re-run generation after every schema or template edit.
  1. Validate the generated markdown.
  • Verify files in 
    docs/
    match the current provider implementation.
  • Verify examples are valid HCL and reflect current argument/attribute names.
  • Verify required/optional/computed semantics in docs match schema behavior.
  1. Apply Registry publication rules before release.
  • Use semantic version tags prefixed with 
    v
    (for example 
    v1.2.3
    ).
  • Create release tags from the default branch.
  • Keep 
    terraform-registry-manifest.json
    in the repository root.
  • Expect docs to be versioned in Registry and switchable with the version selector.
  1. Preview or troubleshoot publication when needed.
  • Use the HashiCorp preview process to inspect rendered docs before release when accuracy risk is high.
  • If docs are missing in Registry, check tag format, tag source branch, manifest file presence, and provider publication status.
  1. 确认范围和文档目标
  • 将代码变更映射到准确的文档对象：Provider索引页、资源、数据源、临时资源、列表资源、函数或指南
  • 确定内容来源是schema描述、模板，还是两者结合
  1. 优先编写schema描述
  • 为schema字段添加面向用户的精准描述，确保生成的文档与实际行为保持一致
  • 措辞要明确说明参数用途、约束条件、默认值和计算行为
  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/guides/<name>.md.tmpl
  • 模板内容聚焦于概述和示例，字段级别的详细信息依赖自动生成的章节
  1. 使用
    tfplugindocs
    生成文档
  • 仓库已配置默认生成规则时优先使用：
bash
go generate ./...
  • 否则直接运行生成器：
bash
go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>
  • 每次修改schema或模板后都要重新执行生成命令
  1. 验证生成的Markdown文件
  • 确认
    docs/
    目录下的文件与当前Provider实现一致
  • 确认示例是有效的HCL代码，且使用的参数/属性名称与当前版本一致
  • 确认文档中标记的必填/可选/计算语义与schema行为匹配
  1. 发布前遵循Registry发布规则
  • 使用带
    v
    前缀的语义化版本标签（例如
    v1.2.3
    ）
  • 从默认分支创建发布标签
  • 仓库根目录下保留
    terraform-registry-manifest.json
    文件
  • Registry中的文档会自动按版本管理，用户可通过版本选择器切换
  1. 需要时预览发布效果或排查问题
  • 当文档准确性风险较高时，可使用HashiCorp预览流程在发布前检查渲染后的文档
  • 如果Registry中缺失文档，请检查标签格式、标签来源分支、清单文件是否存在，以及Provider发布状态

Enforce Quality Bar

执行质量管控

  • Keep documentation behaviorally accurate; never describe unsupported arguments or attributes.
  • Keep examples minimal, realistic, and runnable.
  • Keep terminology and naming consistent across provider, resources, and data sources.
  • Avoid duplicating generated argument/attribute blocks in manual templates.
  • Keep doc changes tied to the same PR as schema/API changes whenever possible.
  • 保证文档内容与实际行为完全一致，绝不能描述不支持的参数或属性
  • 示例要保持精简、贴合实际场景、可直接运行
  • 整个Provider、资源、数据源的术语和命名保持一致
  • 避免在手动编写的模板中重复自动生成的参数/属性块
  • 尽可能将文档变更与对应的schema/API变更放在同一个PR中提交

Load References On Demand

按需加载参考资料

  • Read 
    references/hashicorp-provider-docs.md
    for source-backed rules and official links.
  • Load only the sections needed for the current change to keep context lean.
  • 阅读
    references/hashicorp-provider-docs.md
    获取有官方来源的规则和官方链接
  • 仅加载当前变更所需的章节，保持上下文精简