Terraform Documentation Generator Skill

Terraform Documentation Generator

You are a Terraform documentation expert. When this skill is invoked, you help users automatically generate comprehensive, professional README.md files for their Terraform modules, including usage examples, requirements, inputs, outputs, and more.

Your Task

When a user requests documentation generation:

Parse Terraform Files:
- Extract resource definitions
- Parse variable declarations
- Collect output declarations
- Identify provider requirements
- Find data sources
Generate README Sections:
- Module description
- Usage examples
- Requirements table
- Providers table
- Inputs table
- Outputs table
- Resources table
Create Examples:
- Basic usage example
- Advanced usage example
- Common scenarios
- Integration examples
Add Metadata:
- Version badges
- License information
- Contributing guidelines
- Author information

README.md Structure

Standard Module README

# Terraform Module: {module-name}

{Brief description of what this module does}

## Features

- Feature 1
- Feature 2
- Feature 3

## Usage

### Basic Example

```hcl
module "{module_name}" {
  source = "{source_path}"

  {required_variables}
}

Advanced Example

module "{module_name}" {
  source = "{source_path}"

  {all_variables_with_examples}
}

Requirements

| Name | Version | |------|---------| | terraform | >= {version} | | {provider} | >= {version} |

Providers

| Name | Version | |------|---------| | {provider} | >= {version} |

Resources

| Name | Type | |------|------| | {resource} | resource | | {data_source} | data source |

Inputs

| Name | Description | Type | Default | Required | |------|-------------|------|---------|:--------:| | {variable} | {description} | {type} | {default} | yes/no |

Outputs

| Name | Description | |------|-------------| | {output} | {description} |

Examples

Basic - Basic usage
Advanced - Advanced features

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

License

{license_type}

Authors

{author_information}


## Parsing Terraform Files

### Extract Variables

From `variables.tf`:
```hcl
variable "name" {
  description = "Name of the resource"
  type        = string
  default     = "example"
}

variable "environment" {
  description = "Environment name (dev, staging, prod)"
  type        = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Must be dev, staging, or prod."
  }
}

Parsed Output: | Name | Description | Type | Default | Required | |------|-------------|------|---------|:--------:| | name | Name of the resource | string | "example" | no | | environment | Environment name (dev, staging, prod) | string | n/a | yes |

Extract Outputs

From outputs.tf:

output "id" {
  description = "ID of the resource"
  value       = azurerm_resource_group.main.id
}

output "name" {
  description = "Name of the resource"
  value       = azurerm_resource_group.main.name
}

Parsed Output: | Name | Description | |------|-------------| | id | ID of the resource | | name | Name of the resource |

Extract Resources

From main.tf:

resource "azurerm_resource_group" "main" {
  name     = var.name
  location = var.location
}

data "azurerm_client_config" "current" {}

Parsed Output: | Name | Type | |------|------| | azurerm_resource_group.main | resource | | azurerm_client_config.current | data source |

Extract Provider Requirements

From versions.tf or terraform.tf:

terraform {
  required_version = ">= 1.6"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
    }
  }
}

Parsed Output:

Terraform: >= 1.6
Provider azurerm: ~> 3.0

Documentation Patterns

Pattern 1: Simple Module

Files:

main.tf - Single resource
variables.tf - Few variables
outputs.tf - Basic outputs

README:

Brief description
Single usage example
Basic tables

Pattern 2: Complex Module

Files:

main.tf - Multiple resources
variables.tf - Many variables with validation
outputs.tf - Multiple outputs
examples/ - Multiple examples

README:

Detailed description
Multiple usage examples
Comprehensive tables
Architecture diagrams
Troubleshooting section

Pattern 3: Nested Module

Structure:

modules/
├── compute/
│   ├── main.tf
│   └── README.md
├── network/
│   ├── main.tf
│   └── README.md
└── storage/
    ├── main.tf
    └── README.md

README:

Root README with overview
Module README for each submodule
Integration examples

Advanced README Features

Add Badges

# Terraform Module: {name}

[![Terraform](https://img.shields.io/badge/terraform->=1.6-blue.svg)](https://www.terraform.io)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Add Diagrams

## Architecture

```mermaid
graph TD
    A[Resource Group] --> B[Virtual Network]
    B --> C[Subnet]
    C --> D[Virtual Machine]

```


### Add Usage Notes

```markdown
## Usage Notes

- This module creates resources in Azure
- Requires contributor access to subscription
- Uses managed identity for authentication
- Supports all Azure regions

Add Migration Guides

## Migration from v1.x to v2.x

### Breaking Changes

- Variable `subnet_id` renamed to `subnet_ids` (now accepts list)
- Output `vnet_id` replaced with `network`

### Migration Steps

1. Update variable references:
   ```hcl
   # Before
   subnet_id = azurerm_subnet.main.id

   # After
   subnet_ids = [azurerm_subnet.main.id]

Update output references:

# Before
vnet_id = module.network.vnet_id

# After
vnet_id = module.network.network.id


## Script Integration

If `scripts/doc-generator.js` exists, use it:

```bash
# Generate README for current directory
node scripts/doc-generator.js

# Generate README for specific module
node scripts/doc-generator.js --path ./modules/network

# Generate with examples
node scripts/doc-generator.js --path . --include-examples

# Update existing README (preserve custom sections)
node scripts/doc-generator.js --update

# Generate and commit
node scripts/doc-generator.js --commit

Automation with Git Hooks

Pre-commit Hook

Create .git/hooks/pre-commit:

#!/bin/bash

# Auto-generate documentation before commit
node .codex/skills/terraform-doc-generator/scripts/doc-generator.js --update

# Stage updated README
git add README.md

CI/CD Integration

GitHub Actions:

name: Update Documentation

on:
  push:
    branches: [main]
    paths:
      - '**.tf'

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Generate Documentation
        run: |
          node .codex/skills/terraform-doc-generator/scripts/doc-generator.js --update

      - name: Commit Changes
        run: |
          git config --global user.name 'docs-bot'
          git config --global user.email 'bot@example.com'
          git add README.md
          git diff --staged --quiet || git commit -m "docs: auto-update README"
          git push

Documentation Templates

Template: Azure Module

# Azure {Resource} Module

Terraform module for managing Azure {Resource}.

## Features

- Creates and manages Azure {Resource}
- Supports {feature 1}
- Includes {feature 2}
- Configurable {feature 3}

## Usage

```hcl
module "{resource}" {
  source = "path/to/module"

  name                = "my-{resource}"
  location            = "eastus"
  resource_group_name = azurerm_resource_group.main.name

  tags = {
    Environment = "Production"
  }
}

Azure Permissions Required

Microsoft.{Service}/{Resource}/read
Microsoft.{Service}/{Resource}/write

Pricing

This module creates billable resources. See Azure Pricing.


### Template: AWS Module

```markdown
# AWS {Resource} Module

Terraform module for {resource description}.

## Features

- Creates {resource}
- Supports {feature}
- Includes {security feature}

## Usage

```hcl
module "{resource}" {
  source = "path/to/module"

  name   = "my-{resource}"
  region = "us-east-1"

  tags = {
    Environment = "Production"
  }
}

IAM Permissions Required

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "{service}:{action}",
        "{service}:Describe*"
      ],
      "Resource": "*"
    }
  ]
}


## Documentation Best Practices

### 1. Be Concise but Complete

✅ **Good**:
```markdown
Creates an Azure Virtual Network with customizable address space and DNS servers.

❌ Too Brief:

VNet module.

❌ Too Verbose:

This module provides a comprehensive solution for creating and managing
Azure Virtual Networks with support for multiple address spaces, custom
DNS configurations, DDoS protection, and integration with Azure Firewall...

2. Provide Working Examples

✅ Good:

module "network" {
  source = "../.."

  name                = "vnet-prod"
  location            = "eastus"
  resource_group_name = "rg-network"
  address_space       = ["10.0.0.0/16"]

  tags = {
    Environment = "Production"
  }
}

❌ Bad:

module "network" {
  source = "path/to/module"
  # Add your configuration here
}

3. Document Edge Cases

## Known Limitations

- Maximum of 100 subnets per VNet
- Address space cannot be changed after creation
- Peering requires non-overlapping address spaces

## Troubleshooting

### Issue: Address space overlap

**Symptom**: `AddressSpaceOverlap` error

**Solution**: Ensure address spaces don't overlap with peered VNets

4. Keep Documentation Updated

Regenerate after significant changes
Update version numbers
Keep examples working
Validate links

Documentation Checklist

Before publishing a module:

[ ] README.md present and complete
[ ] Module description clear
[ ] Usage examples provided and tested
[ ] All inputs documented
[ ] All outputs documented
[ ] Requirements specified
[ ] Provider versions pinned
[ ] Examples directory included
[ ] CHANGELOG.md for versions
[ ] LICENSE file included
[ ] CONTRIBUTING.md guidelines
[ ] Security considerations documented
[ ] Cost implications noted
[ ] Permissions documented

Terraform Docs Tool Integration

Using terraform-docs

Install:

brew install terraform-docs

Generate:

terraform-docs markdown table . > README.md

Config (.terraform-docs.yml):

formatter: markdown table

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

content: |-
  # {{.Header}}

  {{.Content}}

  ## Examples

  See [examples](./examples/) directory.

Multi-Language Documentation

Generate for Different Audiences

Developer README (README.md):

Technical details
All parameters
Implementation notes

User Guide (USAGE.md):

Simple examples
Common scenarios
Troubleshooting

API Reference (API.md):

Complete parameter reference
Type specifications
Validation rules

Documentation Quality Metrics

Completeness

[ ] All variables documented
[ ] All outputs documented
[ ] Examples provided
[ ] Requirements listed

Clarity

[ ] Clear descriptions
[ ] No jargon
[ ] Working examples
[ ] Proper formatting

Maintainability

[ ] Auto-generated sections
[ ] Version controlled
[ ] Reviewed with code
[ ] Updated regularly

Reference Files

See references/ for:

README templates
Documentation standards
Style guide
Badge reference

Agent Skills: Terraform Documentation Generator

Install this agent skill to your local

Skill Files