Development Guide

This guide explains how to set up the development environment and use the project tools.

All tasks are defined in pyproject.toml using Poe the Poet.

Initial Setup

Clone and navigate to the project:
```
cd /path/to/eml2pdf
```
Install in development mode with all dependencies:
```
pip install -e ".[dev]"
```
This installs the package in editable mode with pytest, coverage, Sphinx, and poe.

Or use the automated setup:
```
poe dev-setup
```

Available Commands

Run poe to see all available tasks:

poe

All tasks are defined in the [tool.poe.tasks] section of pyproject.toml.

Common Workflows

Running Tests

# Run all tests
poe test

# Run tests with verbose output
poe test-verbose

# Run tests with coverage report
poe coverage

Coverage reports are generated in:

Terminal: Shows missing lines
HTML: htmlcov/index.html

Linting and Formatting

# Auto-fix all lint issues (Python and Markdown)
poe lint-fix

# Run all checks: lint, format, mypy, and tests
poe check

The check task runs:

ruff check - Linting checks
ruff format --check - Formatting verification
pymarkdownlnt scan - Markdown linting
mypy - Static type checking
pytest - Unit tests

Refer to pyproject.toml tool.ruff sections for project style rules. Basically they are the ruff defaults except 79 chars max linelength and single quotes.

Building Documentation

# Build HTML documentation
poe docs

# Build and serve documentation locally
poe docs-serve

Documentation is generated from:

Google-style docstrings in source code (eml2pdf/*.py)
RST files in docs/ directory
Markdown files (via myst_parser)

View the built docs at docs/_build/html/index.html

Building Distribution Packages

# Build source distribution and wheel
poe build

Output goes to dist/ directory:

eml2pdf-X.Y.Z.tar.gz - Source distribution
eml2pdf-X.Y.Z-py3-none-any.whl - Wheel

Publishing to PyPI

# Test on TestPyPI first
poe upload-test

# Upload to real PyPI
poe upload

Note: Requires PyPI credentials configured in ~/.pypirc or set via environment variables.

Cleaning

# Remove build artifacts and cache
poe clean

# Remove everything including docs
poe clean-all

Project Configuration

All project configuration is in pyproject.toml:

Dependencies

Core dependencies: Required for running the package
[dev]: All development tools (tests + docs)
[test]: Testing tools only
[docs]: Documentation tools only

Install specific groups:

pip install -e ".[test]"   # Just testing tools
pip install -e ".[docs]"   # Just documentation tools
pip install -e ".[dev]"    # Everything

Poe the Poet Tasks

All tasks are defined in [tool.poe.tasks] in pyproject.toml.

Pytest Configuration

Test settings are in [tool.pytest.ini_options].

Sphinx Configuration

Documentation settings are in docs/conf.py.

Extensions: autodoc, napoleon, myst_parser
Theme: Read the Docs
Napoleon settings for Google-style docstrings

Writing Documentation

Docstrings

Use Google-style docstrings in Python code:

Refer to Google Python Style Guide.

RST Files

Create new .rst files in docs/ and add them to the toctree in index.rst.

Don’t document twice. Github shows markdown files. Reuse those instead of rewriting in rst.

Markdown Files

Markdown files are supported via myst_parser. Include them in RST files:

.. include:: ../README.md
   :parser: myst_parser.sphinx_

Scripts

The scripts/ directory contains helper scripts:

check_debian_deps.py - Check if dependencies match Debian stable versions (poe check-debian-deps)
generate_test_emls.py - Generate test EML files (poe generate-test-emls)

Version Management

Version is managed by setuptools_scm based on git tags:

# Create a new version
git tag -a v1.0.0 -m "Release 1.0.0"
git push origin v1.0.0

# Build will use this version
poe build