plating 0.0.1100

Documentation generation system for Terraform/OpenTofu providers

🍽️ Plating

A sophisticated 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.

✨ 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

📦 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"

# Using pipx (if you prefer)
pipx install uv

# Update UV to latest version
uv self update

🚀 Getting Started

Installation

Note: Plating is currently in pre-release. Install from source for now.

Version Info: The version 0.0.1000-0 is a pre-release identifier indicating active development. Expect the API and features to evolve as the project matures.

# Clone the repository
git clone https://github.com/provide-io/plating.git
cd plating

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate  # On Linux/macOS
# or
.venv\Scripts\activate     # On Windows

# Install dependencies
uv sync

Coming soon to PyPI:

# PyPI installation (not yet available)
# uv add plating

Quick Install from Git

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

📚 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:

my_resource.plating/
├── docs/
│   ├── my_resource.tmpl.md    # Main template
│   └── _partial.md             # Reusable partials (optional)
├── examples/
│   ├── basic.tf                # Example configurations
│   ├── advanced.tf             # (optional)
│   └── full_stack/             # Grouped examples (optional)
│       └── main.tf             # Required entry point
└── fixtures/                   # Test fixtures (optional)
    └── data.json               # Test data files

Note: The examples/ directory can contain:

• .tf files for resources/data sources (flat examples)
• .py files for Python API examples
• Subdirectories with main.tf for grouped examples that combine multiple components

🎨 Template Functions

Plating provides powerful template functions:

• {{ "{{ schema() }}" }} - Render component schema as markdown table
• {{ "{{ example('name') }}" }} - Include an example file in a terraform code block
• {{ "{{ include('filename') }}" }} - Include a static partial file
• {{ "{{ render('filename') }}" }} - Render a dynamic template partial with current context

🎯 Capability-First Organization

Plating now supports organizing documentation by capability (subcategory) instead of just by component type. This makes it easier to find related functionality across resource types.

How It Works

1. Add Subcategory to Templates

   Add a subcategory field to your component template frontmatter:

   ---
   page_title: "sqrt Function"
   subcategory: "Math"
   description: |-
     Calculate square root of a number
   ---
   

2. Automatic Organization

   Components are automatically grouped by capability in generated documentation:

   ## Math
   ### Functions
   - add
   - subtract
   - multiply
   
   ## String Utilities
   ### Functions
   - format
   - join
   - split
   
   ## Utilities
   ### Resources
   - pyvider_file_content
   ### Data Sources
   - pyvider_env_variables
   

3. MkDocs Navigation

   The mkdocs.yml navigation is automatically generated with capability-first structure:

   nav:
     - Overview: index.md
     - Math:
         Functions:
           add: functions/add.md
           subtract: functions/subtract.md
     - String Utilities:
         Functions:
           format: functions/format.md
           join: functions/join.md
     - Utilities:
         Resources:
           file_content: resources/file_content.md
   

Standard Subcategories

• Math - Numeric operations (add, subtract, multiply, etc.)
• String Utilities - String manipulation (format, join, split, etc.)
• Collections - List/map operations (contains, length, lookup)
• Type Conversion - Type casting functions
• Lens - Data transformation components (JQ integration)
• Utilities - General-purpose resources and data sources
• Test Mode - Components for testing (always appears last)

Custom Subcategories

You can use any custom subcategory name. Just add it to your template frontmatter:

---
page_title: "Custom Component"
subcategory: "My Custom Category"
---

Guide Support

Add provider-level guides in .plating/guides/:

.plating/
├── guides/
│   ├── getting-started.tmpl.md
│   ├── authentication.tmpl.md
│   └── troubleshooting.tmpl.md
└── docs/
    └── components.tmpl.md

Guides are automatically discovered and added to the documentation structure and navigation.

🔍 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.plating]
# Provider name (auto-detected if not specified)
provider_name = "my_provider"

Note: Currently only provider_name can be configured in pyproject.toml. 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

🤝 Contributing

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

📜 License

Apache 2.0

🙏 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 🍽️