xml-feed-specs

Important

This repository generates documentation that may not yet be fully accurate or complete. For production use, please always verify information against the official documentation until this project reaches stable version v1.0.0.

Model-first documentation generator for Heureka Offer Feed XML specification. Generates MkDocs documentation from programmatically defined field models using Jinja2 templates.

Installation

uv sync --dev

Usage

Generate documentation:

uv run heureka-generator

Custom paths:

uv run heureka-generator --template-dir templates --output-dir docs

Project Structure

src/heureka_generator/
├── models.py      # Field data models and enums
├── fields.py      # Field definitions (required + DELIVERY + GIFT)
├── generator.py   # Template rendering engine
└── main.py        # CLI interface

templates/         # Jinja2 templates
├── field.md.j2    # Individual field pages
└── index.md.j2    # Documentation index

docs/              # Generated output
├── index.md       # Overview page
└── fields/        # Individual field documentation (autogenerated, do not update manually)

Development

This project uses pre-commit hooks to ensure code quality and consistent commit messages.

uv run pre-commit install
uv run pre-commit install --hook-type commit-msg
uv run pre-commit run --all-files

Generate and serve documentation:

uv run heureka-generator
uv run mkdocs serve

Then open http://127.0.0.1:8000 to view the documentation.

Run type checking:

uv run mypy src/heureka_generator

Run linting:

uv run ruff check src/

Format code:

uv run ruff format src/