名称：terraform-documentation-generator 描述：使用terraform-docs工具为Terraform模块生成文档，自动创建包含输入/输出表格、使用示例和要求的README文件。当用户需要为Terraform模块撰写文档、创建或更新README文件，或维护一致的模块文档时，应使用此技能。

Terraform 文档生成器

这个技能帮助使用terraform-docs生成和维护Terraform模块文档。

何时使用

在以下情况使用此技能：

为新模块创建README.md
模块更改后更新文档
自动生成输入/输出参考表格
确保模块间文档一致性

使用 terraform-docs

安装

# macOS
brew install terraform-docs

# Linux
curl -sSLo ./terraform-docs.tar.gz https://terraform-docs.io/dl/latest/terraform-docs-linux-amd64.tar.gz
tar -xzf terraform-docs.tar.gz
chmod +x terraform-docs
mv terraform-docs /usr/local/bin/

# 或使用 Go
go install github.com/terraform-docs/terraform-docs@latest

基本用法

# 生成Markdown文档
terraform-docs markdown table . > README.md

# 预览而不写入
terraform-docs markdown table .

# 为特定目录生成
terraform-docs markdown table ./modules/vpc > ./modules/vpc/README.md

配置文件

在模块根目录创建.terraform-docs.yml以保持格式一致：

formatter: "markdown table"

header-from: main.tf

sections:
  show:
    - header
    - requirements
    - providers
    - inputs
    - outputs
    - resources

content: |-
  {{ .Header }}
  
  ## 使用示例
  
  ```hcl
  module "example" {
    source = "./modules/example"
    
    # 在此添加示例
  }

output: file: “README.md” mode: inject template: |-  {{ .Content }}

sort: enabled: true by: required


### 自动生成文档

```bash
# 使用配置文件
terraform-docs .

# 注入到现有README标记之间
terraform-docs markdown table --output-file README.md --output-mode inject .

输出格式

# Markdown表格（最常用）
terraform-docs markdown table .

# Markdown文档
terraform-docs markdown document .

# JSON
terraform-docs json .

# YAML
terraform-docs yaml .

文档最佳实践

添加头部注释

在main.tf顶部添加描述：

/**
 * # Terraform AWS VPC模块
 *
 * 创建一个跨多个可用区的公共和私有子网的VPC。
 *
 * ## 功能
 *
 * - 多可用区VPC带公共和私有子网
 * - 私有子网互联网访问的NAT网关
 * - 可配置的CIDR块
 */

resource "aws_vpc" "main" {
  # ...
}

terraform-docs将使用此作为README头部。

清晰文档化变量

variable "vpc_cidr" {
  description = "VPC的CIDR块（例如，10.0.0.0/16）"
  type        = string
  
  validation {
    condition     = can(cidrhost(var.vpc_cidr, 0))
    error_message = "必须是有效的IPv4 CIDR。"
  }
}

variable "enable_nat_gateway" {
  description = "为私有子网互联网访问启用NAT网关"
  type        = bool
  default     = true
}

文档化输出

output "vpc_id" {
  description = "VPC的ID"
  value       = aws_vpc.main.id
}

output "private_subnet_ids" {
  description = "私有子网ID列表，供内部资源使用"
  value       = aws_subnet.private[*].id
}

工作流集成

预提交钩子

添加到.pre-commit-config.yaml：

repos:
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: "v0.16.0"
    hooks:
      - id: terraform-docs-go
        args: ["markdown", "table", "--output-file", "README.md", "."]

CI/CD集成

# GitHub Actions示例
- name: 生成terraform文档
  uses: terraform-docs/gh-actions@v1
  with:
    working-dir: .
    output-file: README.md
    output-method: inject

快速参考

# 为当前目录生成文档
terraform-docs markdown table . > README.md

# 更新现有README（标记之间）
terraform-docs markdown table --output-file README.md --output-mode inject .

# 为所有模块生成
find . -type f -name "*.tf" -exec dirname {} \; | sort -u | xargs -I {} terraform-docs markdown table {} --output-file {}/README.md

# 验证文档是否最新
terraform-docs markdown table . | diff - README.md

文档检查清单

[ ] terraform-docs已安装
[ ] 创建.terraform-docs.yml配置（可选）
[ ] 在main.tf添加了头部注释
[ ] 所有变量都有清晰的描述
[ ] 所有输出都有描述
[ ] 在README中添加了使用示例
[ ] 使用terraform-docs生成了文档
[ ] 配置了预提交钩子（可选）