tfplugindocs Tool

6 minute read

tfplugindocs Overview

tfplugindocs is the official tool for generating Terraform provider documentation. It extracts schema information and combines it with templates and examples to create comprehensive documentation.

Installation

Install via Go

go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@latest

Verify Installation

tfplugindocs --version

Basic Usage

Generate Documentation

# Generate all documentation
tfplugindocs generate

# Generate with specific output directory
tfplugindocs generate --provider-dir=. --examples-dir=examples

Validate Documentation

# Validate existing documentation
tfplugindocs validate

# Validate specific directory
tfplugindocs validate --provider-dir=.

Project Structure

tfplugindocs expects this structure:

terraform-provider-cachecloud/
├── docs/                      # Generated documentation (committed)
│   ├── index.md
│   ├── data-sources/
│   │   └── cache.md
│   └── resources/
│       └── cache.md
├── templates/                 # Templates for customization (optional)
│   ├── index.md.tmpl
│   ├── resources.md.tmpl
│   └── data-sources.md.tmpl
├── examples/                  # Example configurations
│   ├── provider/
│   │   └── provider.tf
│   ├── resources/
│   │   └── cachecloud_cache/
│   │       ├── resource.tf
│   │       └── import.sh
│   └── data-sources/
│       └── cachecloud_cache/
│           └── data-source.tf
├── main.go
└── go.mod

Templates

Default Templates

tfplugindocs uses built-in templates. Override them with custom templates:

templates/
├── index.md.tmpl              # Provider overview
├── resources.md.tmpl          # Resource pages
└── data-sources.md.tmpl       # Data source pages

Provider Template

<!-- templates/index.md.tmpl -->
---
page_title: "Provider: {{ .ProviderShortName }}"
description: |-
  {{ .Description }}
---

# {{ .ProviderShortName }} Provider

{{ .Description }}

## Example Usage

{{tffile "examples/provider/provider.tf"}}

{{ .SchemaMarkdown }}

## Authentication

The provider supports the following authentication methods:

### API Key

Set the `api_key` attribute or use the `CACHECLOUD_API_KEY` environment variable.

### Configuration File

Create `~/.cachecloud/credentials`:

```ini
[default]
api_key = your-api-key
endpoint = https://api.example.com



### Resource Template


```markdown
<!-- templates/resources.md.tmpl -->
---
page_title: "{{.Type}} {{.Name}} - {{.ProviderShortName}}"
subcategory: ""
description: |-
{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
---

# {{.Type}}: {{.Name}}

{{ .Description | trimspace }}

{{ if .HasExample -}}
## Example Usage

{{ tffile .ExampleFile }}
{{- end }}

{{ .SchemaMarkdown | trimspace }}

{{ if .HasImport -}}
## Import

{{ .ImportDetails | trimspace }}
{{- end }}

Examples

Provider Example

# examples/provider/provider.tf
provider "cachecloud" {
  # API key for authentication
  api_key = var.cachecloud_api_key
  
  # Optional: API endpoint (defaults to https://api.cachecloud.io)
  endpoint = "https://api.cachecloud.example.com"
  
  # Optional: Enable debug logging
  debug = false
}

Resource Example

# examples/resources/cachecloud_cache/resource.tf
resource "cachecloud_cache" "example" {
  name      = "my-cache"
  engine    = "redis"
  node_type = "cache.t3.micro"
  num_nodes = 1
  
  tags = {
    Environment = "dev"
    ManagedBy   = "terraform"
  }
}

Import Example

# examples/resources/cachecloud_cache/import.sh
# Caches can be imported using the cache ID
terraform import cachecloud_cache.example cache-123456

# For composite IDs, use region/id format
terraform import cachecloud_cache.example us-east-1/cache-123456

Data Source Example

# examples/data-sources/cachecloud_cache/data-source.tf
data "cachecloud_cache" "example" {
  name = "my-cache"
}

output "cache_endpoint" {
  description = "Cache endpoint for application configuration"
  value       = data.cachecloud_cache.example.endpoint
}

Schema Documentation

tfplugindocs automatically generates schema documentation from your resource/data source schemas:

Schema Annotations

Use schema descriptions for better documentation:

"name": schema.StringAttribute{
    Required: true,
    Description: "The name of the cache. Must be unique within your account. " +
        "Names must be 3-63 characters, start with a lowercase letter, " +
        "and contain only lowercase letters, numbers, and hyphens.",
},
"engine": schema.StringAttribute{
    Required: true,
    Description: "The cache engine type. Valid values: `redis`, `memcached`.",
    Validators: []validator.String{
        stringvalidator.OneOf("redis", "memcached"),
    },
},
"tags": schema.MapAttribute{
    ElementType: types.StringType,
    Optional:    true,
    Description: "Key-value map of resource tags. Maximum 50 tags.",
},

Generated documentation:

### Required

- `name` (String) The name of the cache. Must be unique within your account. Names must be 3-63 characters, start with a lowercase letter, and contain only lowercase letters, numbers, and hyphens.
- `engine` (String) The cache engine type. Valid values: `redis`, `memcached`.

### Optional

- `tags` (Map of String) Key-value map of resource tags. Maximum 50 tags.

Deprecation Notices

"legacy_mode": schema.BoolAttribute{
    Optional:           true,
    DeprecationMessage: "This attribute is deprecated and will be removed in version 2.0. Use 'mode' instead.",
    Description:        "Enable legacy compatibility mode.",
},

Generates:

### Optional

- `legacy_mode` (Boolean, Deprecated) Enable legacy compatibility mode.

**Deprecated:** This attribute is deprecated and will be removed in version 2.0. Use 'mode' instead.

Customization

Custom Descriptions

Add frontmatter to override generated descriptions:

<!-- templates/resources.md.tmpl -->
---
page_title: "Resource: cachecloud_cache"
subcategory: "Compute"
description: |-
  Manages a CacheCloud cache instance with support for Redis and Memcached engines.
---

Adding Sections

Add custom sections to templates:

## Timeouts

The following [Timeouts](https://www.terraform.io/docs/configuration/blocks/resources/syntax.html#operation-timeouts) are supported:

- `create` - (Default `30m`) How long to wait for cache creation
- `update` - (Default `20m`) How long to wait for cache updates
- `delete` - (Default `30m`) How long to wait for cache deletion

## Notes

### Multi-AZ Deployments

When deploying across multiple availability zones, ensure at least 2 nodes are configured.

### Engine Versions

Supported engine versions:
- Redis: 6.0, 6.2, 7.0
- Memcached: 1.6

Check the [API documentation](https://docs.example.com) for the latest supported versions.

Validation

Validate Generated Docs

tfplugindocs validate

Common validation errors:

Error: missing required example file
  File: examples/resources/cachecloud_cache/resource.tf

Error: resource documentation missing import section
  Resource: cachecloud_cache

Warning: data source example references undefined resource
  File: examples/data-sources/cachecloud_cache/data-source.tf

Fix Validation Errors

# Create missing example
mkdir -p examples/resources/cachecloud_cache
cat > examples/resources/cachecloud_cache/resource.tf <<EOF
resource "cachecloud_cache" "example" {
  name      = "my-cache"
  engine    = "redis"
  node_type = "cache.t3.micro"
}
EOF

# Add import example
cat > examples/resources/cachecloud_cache/import.sh <<EOF
terraform import cachecloud_cache.example cache-123456
EOF

# Regenerate
tfplugindocs generate

CI/CD Integration

GitHub Actions

# .github/workflows/documentation.yml
name: Documentation

on:
  push:
    branches: [main]
    paths:
      - 'internal/provider/**'
      - 'templates/**'
      - 'examples/**'
  pull_request:
    paths:
      - 'docs/**'
      - 'templates/**'
      - 'examples/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.21'
      
      - name: Install tfplugindocs
        run: go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@latest
      
      - name: Generate documentation
        run: tfplugindocs generate
      
      - name: Validate documentation
        run: tfplugindocs validate
      
      - name: Check for changes
        run: |
          if ! git diff --exit-code docs/; then
            echo "Documentation is out of date!"
            echo "Run 'tfplugindocs generate' and commit the changes."
            exit 1
          fi

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Generating documentation..."
tfplugindocs generate

if ! git diff --exit-code --quiet docs/; then
    echo "Documentation updated. Adding to commit..."
    git add docs/
fi

Makefile Integration

# Makefile
.PHONY: docs docs-validate docs-check

docs:
	@echo "Generating documentation..."
	@tfplugindocs generate

docs-validate:
	@echo "Validating documentation..."
	@tfplugindocs validate

docs-check: docs
	@echo "Checking for documentation changes..."
	@git diff --exit-code docs/ || (echo "Documentation needs regeneration" && exit 1)

.PHONY: help
help:
	@echo "Available targets:"
	@echo "  docs          - Generate documentation"
	@echo "  docs-validate - Validate documentation"
	@echo "  docs-check    - Check if docs are up to date"

Troubleshooting

Issue: Documentation Not Generated

Problem: tfplugindocs doesn’t generate any files

Solution:

  1. Ensure provider is built: go build
  2. Check examples directory exists
  3. Verify schema descriptions are set
  4. Run with verbose output: tfplugindocs generate -v

Issue: Missing Schema Documentation

Problem: Attributes missing from generated docs

Solution:

// ❌ Bad: No description
"name": schema.StringAttribute{
    Required: true,
},

// ✅ Good: With description
"name": schema.StringAttribute{
    Required:    true,
    Description: "The name of the cache.",
},

Issue: Example Not Included

Problem: Example code doesn’t appear in docs

Solution:

  1. Verify example file path matches resource name
  2. Check template uses `` directive
  3. Ensure example is valid Terraform code

Best Practices

1. Descriptive Schema Documentation

// ✅ Good: Comprehensive description
"num_nodes": schema.Int64Attribute{
    Optional:    true,
    Computed:    true,
    Description: "Number of cache nodes in the cluster. " +
        "Valid range: 1-90. " +
        "Defaults to 1. " +
        "Memcached supports up to 20 nodes.",
},

// ❌ Bad: Minimal description
"num_nodes": schema.Int64Attribute{
    Optional:    true,
    Description: "Node count.",
},

2. Complete Examples

# ✅ Good: Realistic, complete example
resource "cachecloud_cache" "example" {
  name      = "session-cache"
  engine    = "redis"
  node_type = "cache.t3.micro"
  num_nodes = 2
  
  backup_enabled        = true
  backup_retention_days = 7
  backup_window         = "03:00-05:00"
  
  tags = {
    Environment = "production"
    Application = "web-app"
  }
}

# ❌ Bad: Minimal example
resource "cachecloud_cache" "example" {
  name = "cache"
}

3. Clear Import Instructions

# ✅ Good: Clear instructions
# Import using cache ID
terraform import cachecloud_cache.example cache-123456

# For multi-region deployments, use region/id format
terraform import cachecloud_cache.example us-east-1/cache-123456

# ❌ Bad: No explanation
terraform import cachecloud_cache.example id

Key Takeaways

  • ✅ Use tfplugindocs for automated documentation generation
  • ✅ Structure examples directory properly
  • ✅ Write comprehensive schema descriptions
  • ✅ Provide realistic, complete examples
  • ✅ Include import examples for all resources
  • ✅ Validate documentation before committing
  • ✅ Integrate documentation generation into CI/CD
  • ✅ Use templates for customization
  • ✅ Keep documentation up to date
  • ✅ Test all example code

What’s Next?

Learn how to write comprehensive resource documentation with examples and references.

Next: Resource Documentation →

Previous: ← Documentation Generation

Last updated: June 30, 2026

Updated:

You may also enjoy