Skip to content

Plating Documentation

Welcome to Plating - An async-first documentation generation system for Terraform/OpenTofu providers.

What is Plating?

Plating is a modern documentation generator that transforms your Terraform provider code into beautiful, Terraform Registry-compliant documentation. Built on foundation patterns for enterprise reliability, Plating makes documentation as delightful as a well-plated dish.

Key Features

  • 🚀 Async-First Architecture: High-performance parallel processing
  • 📝 Automatic Template Generation: Create documentation templates automatically
  • 🎨 Beautiful Documentation: Generate Terraform Registry-compliant markdown
  • 🔍 Smart Discovery: Automatically find components via foundation.hub
  • ⚡ Foundation Integration: Built-in retry policies, metrics, and circuit breakers
  • 📊 Registry Pattern: Centralized component management and statistics
  • 🛡️ Enterprise Ready: Production-grade resilience and observability

Part of the provide.io Ecosystem

This project is part of a larger ecosystem of tools for Python and Terraform development.

View Ecosystem Overview →

Understand how provide-foundation, pyvider, flavorpack, and other projects work together.

Quick Start

Installation

Beta Status

plating is in beta. Core build orchestration features are functional, but the API may evolve.

  • Current version: v0.0.1026
  • Status: Beta (Development Status: 4)
  • Installation: Install from source (not yet on PyPI)

Installation:

$ git clone https://github.com/provide-io/plating.git
$ cd plating
$ uv sync
// Installing dependencies...
Successfully installed plating

$ plating --help
Plating - Modern async documentation generator

Coming soon to PyPI: uv add plating

Adorn Components with Templates

Create .plating bundles for your undocumented components:

$ plating adorn --component-type resource
// Discovering components...
🎨 Adorning 5 component types...
📦 Processing 10 resource(s)...
✅ Generated 8 templates
📦 Processed 10 components

Generate Documentation

Render your documentation from templates:

$ plating plate --output-dir docs/
// Discovering plating bundles...
🍽️ Plating documentation...
✅ Generated 10 files in 0.52s
📦 Processed 10 bundles
📄 Generated files:
  • docs/resources/example_resource.md
  • docs/data-sources/example_data.md
  • docs/functions/example_function.md
  ... and 7 more

Validate Documentation

Validate your generated documentation:

$ plating validate --output-dir docs/
// Validating documentation in docs/...
📊 Validation results:
  • Total files: 10
  • Passed: 10
  • Failed: 0
  • Duration: 0.23s
✅ All validations passed

Python API Usage

import asyncio
from plating import Plating, PlatingContext
from plating.types import ComponentType
from pathlib import Path

async def main():
    # Initialize plating API with foundation context
    context = PlatingContext(
        provider_name="my_provider",
        log_level="INFO",
        no_color=False
    )
    api = Plating(context, package_name="pyvider.components")

    # Adorn components with templates
    result = await api.adorn(component_types=[ComponentType.RESOURCE])
    print(f"Generated {result.templates_generated} templates")

    # Plate documentation (validation runs automatically if validate_markdown=True)
    result = await api.plate(output_dir=Path("docs"), validate_markdown=True)
    print(f"Generated {result.files_generated} files")

    # Note: validate_markdown=True runs validation during generation
    # No need to call validate() separately unless you want to run it standalone

# Run the async main function
asyncio.run(main())

Documentation

Getting Started

Reference

Advanced Topics

API Documentation

Component Types Supported

  • Resources: Terraform resources (e.g., aws_s3_bucket)
  • Data Sources: Terraform data sources (e.g., aws_ami)
  • Functions: Provider functions (e.g., timestamp())
  • Providers: Provider configuration documentation

Architecture Overview

Plating follows a clean, modular architecture:

Plating API (async-first)
    ├── Registry (component discovery)
    ├── Template Engine (Jinja2)
    ├── Schema Processor (extraction)
    └── Foundation Integration
        ├── Retry Policies
        ├── Circuit Breakers
        └── Metrics & Observability