Development Setup¶

Complete guide for setting up a SlideGen development environment.

Prerequisites¶

Python 3.9 or higher
Git
pip (Python package manager)

Initial Setup¶

1. Clone Repository¶

git clone https://github.com/nicolairobles/slidegen.git
cd slidegen

2. Create Virtual Environment¶

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

3. Install Dependencies¶

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

This installs: - SlideGen package (editable) - Development dependencies (pytest, mypy, ruff) - Runtime dependencies (python-pptx, pyyaml, etc.)

4. Verify Installation¶

# Check SlideGen is installed
slidegen --version

# Run tests
pytest

# Type check
mypy slidegen/

# Lint
ruff check slidegen/

Project Structure¶

slidegen/
├── slidegen/              # Main package
│   ├── cli/              # CLI commands
│   ├── core/             # Core generator
│   ├── layouts/          # Layout renderers
│   ├── llm/              # LLM integration
│   ├── theming/          # Theme management
│   └── validator/        # Schema validation
├── tests/                # Test suite
├── docs/                 # Documentation
├── examples/             # Example schemas
├── schema/               # Schema specification
├── pyproject.toml        # Project configuration
└── README.md            # Project README

Development Tools¶

Testing¶

# Run all tests
pytest

# Run specific test file
pytest tests/core/test_generator.py

# Run with coverage
pytest --cov=slidegen --cov-report=html

# Run specific test
pytest tests/core/test_generator.py::test_from_schema

Type Checking¶

# Check all code
mypy slidegen/

# Check specific module
mypy slidegen/core/

Linting¶

# Check for issues
ruff check slidegen/

# Auto-fix issues
ruff check --fix slidegen/

# Format code
ruff format slidegen/

Running the CLI¶

During development, use the installed CLI:

# From project root
slidegen --version
slidegen init test-project
slidegen validate examples/quarterly-results.yaml
slidegen build examples/quarterly-results.yaml -o test.pptx

Or run directly:

python -m slidegen.cli.main --version

Building Documentation¶

MkDocs Setup¶

# Install MkDocs and plugins
pip install mkdocs mkdocs-material mkdocstrings[python]

Serve Documentation Locally¶

# From project root
mkdocs serve

Open http://127.0.0.1:8000 in your browser.

Build Documentation¶

# Build static site
mkdocs build

# Output in site/ directory

Common Development Tasks¶

Adding a New Layout¶

Create layout renderer in slidegen/layouts/:

# slidegen/layouts/custom.py
from slidegen.layouts.base import LayoutRenderer

class CustomLayoutRenderer(LayoutRenderer):
    def render(self, slide, data, presentation):
        # Implementation
        pass

Register in slidegen/core/generator.py:

from slidegen.layouts.custom import CustomLayoutRenderer

def _register_default_layouts(registry):
    # ... existing registrations ...
    registry.register("custom", CustomLayoutRenderer())

Add tests in tests/layouts/test_custom.py
Update schema in schema/spec/slide-schema.json
Update documentation

Adding a CLI Command¶

Create command in slidegen/cli/:

# slidegen/cli/custom.py
import click

@click.command()
def custom_cmd():
    """Custom command description."""
    click.echo("Custom command")

Register in slidegen/cli/main.py:

from slidegen.cli.custom import custom_cmd

cli.add_command(custom_cmd, name="custom")

Add tests in tests/cli/test_custom.py

Debugging¶

Enable Debug Logging¶

export SLIDEGEN_LOG_LEVEL=DEBUG
slidegen build deck.yaml -o output.pptx

Python Debugger¶

import pdb; pdb.set_trace()  # Breakpoint

Verbose Output¶

slidegen build deck.yaml -o output.pptx --verbose

Continuous Integration¶

CI runs on every PR:

Tests: pytest
Type checking: mypy slidegen/
Linting: ruff check slidegen/
Documentation build: mkdocs build

Release Process¶

Update version in pyproject.toml
Update CHANGELOG.md
Create git tag: git tag v0.1.0
Push tag: git push origin v0.1.0
CI builds and publishes to PyPI

Troubleshooting¶

Import Errors¶

# Reinstall in editable mode
pip install -e ".[dev]"

Test Failures¶

# Clear pytest cache
pytest --cache-clear

# Run with verbose output
pytest -v

Type Check Errors¶

# Check specific file
mypy slidegen/core/generator.py

# Ignore specific errors (temporary)
# mypy: ignore-errors