terraform-documentation-generator
Generates documentation for Terraform modules using terraform-docs tool to auto-generate README files with input/output tables, usage examples, and requirements. This skill should be used when users need to document Terraform modules, create or update README files, or maintain consistent module documentation.
When & Why to Use This Skill
The Terraform Documentation Generator is a specialized Claude skill designed to automate the lifecycle of Infrastructure-as-Code (IaC) documentation. By leveraging the terraform-docs tool, it transforms Terraform configuration files into professional, structured README files featuring detailed input/output tables, provider requirements, and usage examples. This tool is essential for DevOps engineers and SREs who aim to maintain high standards of documentation consistency and clarity without the manual overhead of manual updates.
Use Cases
- Automated README Generation: Quickly bootstrap comprehensive documentation for new Terraform modules by extracting metadata directly from HCL files.
- Documentation Syncing: Automatically update reference tables and descriptions whenever variables or outputs are modified, effectively eliminating documentation drift.
- Standardization: Enforce a consistent documentation style across multiple repositories and teams using centralized configuration files (.terraform-docs.yml).
- CI/CD Integration: Incorporate documentation generation into GitHub Actions or pre-commit hooks to ensure all infrastructure changes are documented before code is merged.
| name | terraform-documentation-generator |
|---|---|
| description | Generates documentation for Terraform modules using terraform-docs tool to auto-generate README files with input/output tables, usage examples, and requirements. This skill should be used when users need to document Terraform modules, create or update README files, or maintain consistent module documentation. |
Terraform Documentation Generator
This skill helps generate and maintain Terraform module documentation using terraform-docs.
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
Using terraform-docs
Installation
# 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
Basic Usage
# 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
Configuration File
Create .terraform-docs.yml in module root for consistent formatting:
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
}
{{ .Requirements }} {{ .Providers }} {{ .Inputs }} {{ .Outputs }} {{ .Resources }}
output: file: "README.md" mode: inject template: |- {{ .Content }}
sort: enabled: true by: required
### Auto-Generate Documentation
```bash
# With config file
terraform-docs .
# Inject into existing README between markers
terraform-docs markdown table --output-file README.md --output-mode inject .
Output Formats
# Markdown table (most common)
terraform-docs markdown table .
# Markdown document
terraform-docs markdown document .
# JSON
terraform-docs json .
# YAML
terraform-docs yaml .
Documentation Best Practices
Add Header Comments
Add description at top of main.tf:
/**
* # 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.
Document Variables Clearly
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
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
Add to .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 Integration
# GitHub Actions example
- name: Generate terraform docs
uses: terraform-docs/gh-actions@v1
with:
working-dir: .
output-file: README.md
output-method: inject
Quick Reference
# 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
Documentation Checklist
- terraform-docs installed
-
.terraform-docs.ymlconfig 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)