🍽️📖 Plating

Documentation generation system for Terraform/OpenTofu providers

Plating is a powerful documentation system that brings culinary elegance to technical documentation. Just as a chef carefully plates a dish, Plating helps you present your Terraform provider documentation beautifully.

✨ Key Features

• 🎯 Automatic Documentation Generation - Generate comprehensive docs from your provider code
• ✨ Smart Component Adorning - Automatically create documentation templates for undocumented components
• 🍽️ Beautiful Plating - Render documentation with examples, schemas, and rich formatting
• 🔍 Component Discovery - Automatically find and document resources, data sources, and functions
• 📝 Jinja2 Templates - Flexible templating with custom functions and filters
• 🔄 Schema Integration - Extract and format provider schemas automatically
• 🎯 Capability-First Organization - Group documentation by feature (Math, Utilities, Lens) instead of just type
• 📍 Smart Navigation - Auto-generated mkdocs.yml with capability-first structure
• 📚 Guide Support - Built-in support for provider guides and tutorials

Quick Start

1. Install: uv tool install plating
2. Read the Documentation
3. Try plating adorn to create documentation templates

Installation

Note: Plating is in pre-release. Some APIs may change during the pre-release series.

Version Info: The version 0.3.0 is a pre-release identifier indicating active development. Expect the API and features to evolve. Some APIs may change during the pre-release series.

# Install from PyPI
uv tool install plating

Quick Install from Git

# Install directly from GitHub
uv tool install git+https://github.com/provide-io/plating.git

Documentation

• Documentation index

Development

Quick Start

# Set up environment
uv sync

# Run common tasks
we run test       # Run tests
we run lint       # Check code
we run format     # Format code
we tasks          # See all available commands

See CLAUDE.md for detailed development instructions and architecture information.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📜 License

Apache 2.0

📦 Prerequisites

Important: This project uses uv for Python environment and package management.

Install UV

Visit UV Documentation for more information.

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Update UV to latest version
uv self update

📚 Usage Examples

1. Adorn Your Components

First, create .plating bundles for your undocumented components:

# Adorn all missing components
plating adorn

# Adorn only resources
plating adorn --component-type resource

2. Customize Templates

Edit the generated templates in .plating/docs/:

---
page_title: "Resource: my_resource"
---

# my_resource

{{ "{{ example('basic') }}" }}

## Schema

{{ "{{ schema() }}" }}

3. Generate Documentation

Render your documentation:

# Generate docs in ./docs directory
plating plate

# Custom output directory
plating plate --output-dir ./documentation

📂 Bundle Structure

Each component has a .plating bundle containing documentation templates, examples, and optional test fixtures. See Authoring Bundles Guide for complete bundle structure and template function reference.

🎯 Capability-First Organization

Organize documentation by capability (subcategory) instead of just by component type. Add a subcategory field to your template frontmatter, and Plating automatically groups components by capability in the navigation.

See Capabilities Guide for standard subcategories, custom categories, and guide support.

🔍 Validation

Validate your generated documentation:

# Validate all documentation
plating validate

# Validate in custom directory
plating validate --output-dir ./documentation

🛡️ Foundation Integration

Plating is built on provide.foundation patterns for enterprise-grade reliability:

• 🔄 Automatic Retries: Built-in retry policies with exponential backoff for I/O operations
• 📊 Metrics & Observability: Integrated performance tracking and operation metrics
• ⚡ Circuit Breakers: Prevents cascading failures in distributed systems
• 📝 Structured Logging: Foundation logger integration with contextual information
• 🚀 Async-First Design: High-performance async operations throughout

🔧 Advanced Usage

Filter to Specific Package

By default, Plating searches all installed packages for components. You can filter to a specific package:

plating adorn --package-name pyvider.components
plating plate --package-name pyvider.components

Generate Executable Examples

Generate standalone executable Terraform examples alongside documentation:

plating plate --generate-examples

Customize example output directories:

plating plate --generate-examples \
  --examples-dir examples/ \
  --grouped-examples-dir examples/integration/

🔧 Configuration

Configure Plating in your pyproject.toml:

[tool.pyvider]
# Provider name (auto-detected if not specified)
name = "my_provider"
# Packages to discover components in
component_packages = ["my_provider.components"]

Plating reads pyvider's own section, so a provider configures its name once and both tools agree on it. [tool.plating] provider_name is still honoured for projects that set it, as is the top-level [pyvider] table, and provider_name is accepted wherever name is.

Note: Other options like output_dir and component_types must be passed as CLI flags:

plating plate --output-dir docs --component-type resource

🏗️ Architecture

Plating follows a modular architecture:

• PlatingBundle - Represents documentation bundles
• PlatingPlater - Renders documentation
• PlatingAdorner - Creates documentation templates
• PlatingDiscovery - Finds components and bundles
• SchemaProcessor - Extracts provider schemas

🙏 Acknowledgments

Built with ❤️ using:

• attrs - Python classes without boilerplate
• Jinja2 - Powerful templating
• pyvider - Terraform provider framework
• click - Command line interface
• rich - Beautiful terminal output

Plating - Making documentation as delightful as a well-plated dish 🍽️

Copyright (c) provide.io LLC.