Template System Guide

Angreal’s template system allows you to generate files and directories from templates. This guide explains how to use the template functions effectively.

The template system consists of three main components:

1. Render Template - Render individual template files
2. Render Directory - Render entire directories of templates
3. Generate Context - Create context variables for templates

Angreal uses Tera (a Rust template engine similar to Jinja2) for template rendering.

Templates can include variables using the {{ variable }} syntax:

# {{ project_name }}

A project created by {{ author }}

## Installation

These variables are replaced with actual values when the template is rendered.

To render a single template file:

import angreal

def create_readme():
    # Create context with variables
    context = {
        "project_name": "My Awesome Project",
        "author": "Jane Smith",
        "year": 2025
    }

    # Render a template
    angreal.render_template(
        source_template="templates/README.md.tera",
        target_path="README.md",
        context=context
    )

To render an entire directory of templates:

import angreal

def create_project():
    # Create context with variables
    context = {
        "project_name": "My Awesome Project",
        "author": "Jane Smith",
        "year": 2025,
        "use_pytest": True
    }

    # Render a directory
    angreal.render_directory(
        source_directory="templates/project",
        target_directory="my-project",
        context=context
    )

This will process all files in the templates/project directory, replacing variables with values from the context.

Template and directory paths can be:

1. Absolute paths - Starting with /
2. Relative paths - Relative to the current directory

Example:

import angreal
import os

# Get absolute paths
template_dir = os.path.join(angreal.get_root(), "templates")

# Render using absolute path
angreal.render_template(
    source_template=os.path.join(template_dir, "README.md.tera"),
    target_path="README.md",
    context={"project_name": "My Project"}
)

The template context contains the variables available in templates. You can generate a context interactively:

import angreal

def initialize_project():
    # Generate context interactively
    context = angreal.generate_context(
        template_path="templates/project",
        interactive=True
    )

    # Render the project
    angreal.render_directory(
        source_directory="templates/project",
        target_directory=context.get("project_name", "new-project"),
        context=context
    )

This will prompt the user for values defined in the template configuration.

Templates can include conditional logic:

# {{ project_name }}

{% if use_pytest %}
## Testing

This project uses pytest for testing.
{% else %}
## Testing

This project uses unittest for testing.
{% endif %}

• render_template - Full API reference for angreal.render_template
• render_directory - Full API reference for angreal.render_directory
• generate_context - Full API reference for angreal.generate_context
• Tera Documentation - Documentation for the Tera template engine