Terraform Documentation Generator

Terraform文档生成器

This skill helps generate and maintain Terraform module documentation using terraform-docs.

本功能可帮助您使用terraform-docs生成并维护Terraform模块文档。

When to Use

使用场景

Use this skill when:

Creating README.md for a new module
Updating documentation after module changes
Generating input/output reference tables automatically
Ensuring consistent documentation across modules

在以下场景中使用本功能：

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

Using terraform-docs

使用terraform-docs

Installation

安装

bash

undefined

bash

undefined

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/

Or use Go

go install github.com/terraform-docs/terraform-docs@latest

undefined

go install github.com/terraform-docs/terraform-docs@latest

undefined

Basic Usage

基础用法

bash

undefined

bash

undefined

Generate markdown documentation

terraform-docs markdown table . > README.md

Preview without writing

terraform-docs markdown table .

Generate for specific directory

terraform-docs markdown table ./modules/vpc > ./modules/vpc/README.md

undefined

terraform-docs markdown table ./modules/vpc > ./modules/vpc/README.md

undefined

Configuration File

配置文件

Create

.terraform-docs.yml

in module root for consistent formatting:

yaml

formatter: "markdown table"

header-from: main.tf

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

content: |-
  {{ .Header }}
  
  ## Usage
  
  ```hcl
  module "example" {
    source = "./modules/example"
    
    # Add your example here
  }

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

sort: enabled: true by: required

undefined

在模块根目录创建

.terraform-docs.yml

以确保格式一致：

yaml

formatter: "markdown table"

header-from: main.tf

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

content: |-
  {{ .Header }}
  
  ## Usage
  
  ```hcl
  module "example" {
    source = "./modules/example"
    
    # Add your example here
  }

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

sort: enabled: true by: required

undefined

Auto-Generate Documentation

自动生成文档

bash

undefined

bash

undefined

With config file

terraform-docs .

Inject into existing README between markers

terraform-docs markdown table --output-file README.md --output-mode inject .

undefined

terraform-docs markdown table --output-file README.md --output-mode inject .

undefined

Output Formats

输出格式

bash

undefined

bash

undefined

Markdown table (most common)

terraform-docs markdown table .

Markdown document

terraform-docs markdown document .

JSON

terraform-docs json .

YAML

terraform-docs yaml .

undefined

terraform-docs yaml .

undefined

Documentation Best Practices

文档最佳实践

Add Header Comments

添加头部注释

Add description at top of main.tf:

hcl

/**
 * # Terraform AWS VPC Module
 *
 * Creates a VPC with public and private subnets across multiple availability zones.
 *
 * ## Features
 *
 * - Multi-AZ VPC with public and private subnets
 * - NAT Gateway for private subnet internet access
 * - Configurable CIDR blocks
 */

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

terraform-docs will use this as the README header.

在main.tf顶部添加描述：

hcl

/**
 * # Terraform AWS VPC Module
 *
 * Creates a VPC with public and private subnets across multiple availability zones.
 *
 * ## Features
 *
 * - Multi-AZ VPC with public and private subnets
 * - NAT Gateway for private subnet internet access
 * - Configurable CIDR blocks
 */

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

terraform-docs会将此内容作为README的头部。

Document Variables Clearly

清晰记录变量

hcl

variable "vpc_cidr" {
  description = "CIDR block for VPC (e.g., 10.0.0.0/16)"
  type        = string
  
  validation {
    condition     = can(cidrhost(var.vpc_cidr, 0))
    error_message = "Must be valid IPv4 CIDR."
  }
}

variable "enable_nat_gateway" {
  description = "Enable NAT Gateway for private subnet internet access"
  type        = bool
  default     = true
}

hcl

variable "vpc_cidr" {
  description = "CIDR block for VPC (e.g., 10.0.0.0/16)"
  type        = string
  
  validation {
    condition     = can(cidrhost(var.vpc_cidr, 0))
    error_message = "Must be valid IPv4 CIDR."
  }
}

variable "enable_nat_gateway" {
  description = "Enable NAT Gateway for private subnet internet access"
  type        = bool
  default     = true
}

Document Outputs

记录输出

hcl

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

output "private_subnet_ids" {
  description = "List of private subnet IDs for use with internal resources"
  value       = aws_subnet.private[*].id
}

hcl

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

output "private_subnet_ids" {
  description = "List of private subnet IDs for use with internal resources"
  value       = aws_subnet.private[*].id
}

Workflow Integration

工作流集成

Pre-commit Hook

Pre-commit钩子

Add to

.pre-commit-config.yaml

:

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", "."]

添加到

.pre-commit-config.yaml

：

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 Integration

CI/CD集成

yaml

undefined

yaml

undefined

GitHub Actions example

name: Generate terraform docs uses: terraform-docs/gh-actions@v1 with: working-dir: . output-file: README.md output-method: inject

undefined

name: Generate terraform docs uses: terraform-docs/gh-actions@v1 with: working-dir: . output-file: README.md output-method: inject

undefined

Quick Reference

快速参考

bash

undefined

bash

undefined

Generate docs for current directory

terraform-docs markdown table . > README.md

Update existing README (between markers)

terraform-docs markdown table --output-file README.md --output-mode inject .

Generate for all modules

find . -type f -name "*.tf" -exec dirname {} ; | sort -u | xargs -I {} terraform-docs markdown table {} --output-file {}/README.md

Validate documentation is up to date

terraform-docs markdown table . | diff - README.md

undefined

terraform-docs markdown table . | diff - README.md

undefined

Documentation Checklist

文档检查清单

terraform-docs installed
```
.terraform-docs.yml
```
config created (optional)
Header comment added to main.tf
All variables have clear descriptions
All outputs have descriptions
Usage example added to README
Documentation generated with
```
terraform-docs
```
Pre-commit hook configured (optional)

已安装terraform-docs
已创建
```
.terraform-docs.yml
```
配置（可选）
已在main.tf中添加头部注释
所有变量均有清晰描述
所有输出均有描述
README中已添加使用示例
已使用
```
terraform-docs
```
生成文档
已配置Pre-commit钩子（可选）

terraform-documentation-generator

Original

Translation

Terraform Documentation Generator

Terraform文档生成器

When to Use

使用场景

Using terraform-docs

使用terraform-docs

Installation

安装

macOS

macOS

Linux

Linux

Or use Go

Or use Go

Basic Usage

基础用法

Generate markdown documentation

Generate markdown documentation

Preview without writing

Preview without writing

Generate for specific directory

Generate for specific directory

Configuration File

配置文件

Auto-Generate Documentation

自动生成文档

With config file

With config file

Inject into existing README between markers

Inject into existing README between markers

Output Formats

输出格式

Markdown table (most common)

Markdown table (most common)

Markdown document

Markdown document

JSON

JSON

YAML

YAML

Documentation Best Practices

文档最佳实践

Add Header Comments

添加头部注释

Document Variables Clearly

清晰记录变量

Document Outputs

记录输出

Workflow Integration

工作流集成

Pre-commit Hook

Pre-commit钩子

CI/CD Integration

CI/CD集成

GitHub Actions example

GitHub Actions example

Quick Reference

快速参考

Generate docs for current directory

Generate docs for current directory

Update existing README (between markers)

Update existing README (between markers)

Generate for all modules

Generate for all modules

Validate documentation is up to date

Validate documentation is up to date

Documentation Checklist

文档检查清单