Add examples, test, improve pre-commit hook

Author: dannyadair

.gitignore

@@ -8,6 +8,7 @@ wheels/
 # Cache
 /.pytest_cache
 /.ruff_cache
+.coverage
 
 # venv
 /.venv

.pre-commit-config.yaml

@@ -45,3 +45,10 @@ repos:
       - id: pylint
         args:
           - --rcfile=.pylintrc
+        additional_dependencies:
+          - "cairosvg"
+          - "click"
+          - "jinja2"
+          - "pypdf"
+          - "pytest"
+          - "pyyaml"

.pylintrc

@@ -1,7 +1,7 @@
 [MASTER]
 score=n
 generated-members=PyPDF2.*
-ignored-modules=cairosvg,click,jinja2,pypdf,yaml
+reports=no
 
 [REPORTS]
 msg-template={path}:{line}: [{msg_id}({symbol}), {obj}] {msg}

README.md

@@ -57,6 +57,14 @@ This will produce your PDF files in a `dist/` directory where your configuration
 lives. It will also create a `build/` directory with intermediate files, which is only
 kept if you specify `--debug`.
 
+## Examples
+
+For working examples, see the [examples](examples) directory.<br> Create all PDFs with:
+
+```bash
+pdfbaker bake examples/examples.yml
+```
+
 ## Documentation
 
 - [Overview](docs/overview.md)
@@ -65,3 +73,45 @@ kept if you specify `--debug`.
 - [Custom Processing](docs/custom_processing.md)
 
 ( [on GitHub](https://github.com/pythonnz/pdfbaker/tree/main/docs) )
+
+## Development
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management. The
+`uv.lock` file ensures reproducible builds.
+
+Create and activate the virtual environment:
+
+```bash
+uv venv
+source .venv/bin/activate
+```
+
+Install development dependencies:
+
+```bash
+uv sync --dev
+```
+
+### Tests
+
+Run tests:
+
+```bash
+pytest
+```
+
+View test coverage:
+
+```bash
+pytest --cov=pdfbaker --cov-report=term-missing
+```
+
+### Pre-commit hook
+
+If you want to commit changes, install [pre-commit](https://pre-commit.com) and run
+
+```bash
+pre-commit install
+```
+
+This ensures the same checks run locally as in GitHub CI.

docs/configuration.md

@@ -4,8 +4,8 @@
 
 ```
 project/
-├── kiwipycon.yml          # Main configuration
-├── material_specs/        # A document
+├── kiwipycon.yml         # Main configuration
+├── material_specs/       # A document
 │   ├── config.yml        # Document configuration
 │   ├── images/           # Images
 │   ├── pages/            # Page configurations
@@ -82,8 +82,9 @@ Example:
 ```yaml
 # prospectus/config.yml
 
-filename: "Kiwi PyCon {{ conference.year }} - Prospectus"
-compress_pdf: true # Override the main config
+filename: "Kiwi PyCon {{ conference.year }} - Prospectus" # Use config values in config values!
+title: "Sponsorship Prospectus"
+compress_pdf: true
 
 pages:
   - cover

docs/overview.md

@@ -23,12 +23,21 @@ documents with minimal effort.
 
 For a quick introduction, see the [README](../README.md).
 
+## Examples
+
+See the [examples](../examples) directory for simple working examples:
+
+- [minimal](../examples/minimal) - Basic single page
+- [regular](../examples/regular) - Using various features
+- [variants](../examples/variants) - Different PDFs of the same document
+- [custom_processing](../examples/custom_processing) - Custom Python code
+
 ## Example Project Structure
 
 ```
 project/
-├── kiwipycon.yml          # Main configuration
-├── material_specs/        # A document
+├── kiwipycon.yml         # Main configuration
+├── material_specs/       # A document
 │   ├── config.yml        # Document configuration
 │   ├── images/           # Images
 │   ├── pages/            # Page configurations

examples/custom_processing/bake.py

@@ -0,0 +1,37 @@
+"""Custom processing example - fetches latest XKCD comic."""
+
+import base64
+import json
+import urllib.request
+from datetime import datetime
+
+from pdfbaker.document import PDFBakerDocument
+from pdfbaker.errors import PDFBakeError
+
+
+def process_document(document: PDFBakerDocument) -> None:
+    """Process document with live XKCD comic."""
+    try:
+        # Fetch latest XKCD
+        with urllib.request.urlopen("https://xkcd.com/info.0.json") as response:
+            data = json.loads(response.read())
+
+        # Download and encode the image
+        with urllib.request.urlopen(data["img"]) as img_response:
+            img_data = img_response.read()
+            image_data = (
+                f"data:image/png;base64,{base64.b64encode(img_data).decode('utf-8')}"
+            )
+
+        # Update config with XKCD info
+        document.config["xkcd"] = {
+            "title": data["title"],
+            "alt_text": data["alt"],
+            "fetched_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            "image_data": image_data,
+        }
+
+        # Process as usual
+        document.process()
+    except Exception as exc:
+        raise PDFBakeError(f"Failed to process XKCD example: {exc}") from exc

examples/custom_processing/config.yml

@@ -0,0 +1,3 @@
+filename: xkcd_example
+pages:
+  - main

examples/custom_processing/pages/main.yml

@@ -0,0 +1,3 @@
+template: "main.svg.j2"
+title: "Custom Processing Example"
+title2: "pdfbaker data from web request"

examples/custom_processing/templates/main.svg.j2

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="210mm" height="297mm" viewBox="0 0 210 297" version="1.1"
+     xmlns="http://www.w3.org/2000/svg"
+     xmlns:xlink="http://www.w3.org/1999/xlink">
+  <rect width="210" height="297" fill="white"/>
+  <!-- Header -->
+  <text x="105" y="30" font-family="Arial" font-size="12" font-weight="bold" fill="#333" text-anchor="middle">{{ title }}</text>
+  <text x="105" y="50" font-family="Arial" font-size="10" fill="#666" text-anchor="middle">{{ title2 }}</text>
+
+  <!-- XKCD Info -->
+  <text x="105" y="80" font-family="Arial" font-size="10" font-weight="bold" fill="#333" text-anchor="middle">Latest XKCD:</text>
+  <text x="105" y="95" font-family="Arial" font-size="10" fill="#333" text-anchor="middle">{{ xkcd.title }}</text>
+  <text x="105" y="110" font-family="Arial" font-size="6" fill="#666" text-anchor="middle">Fetched at: {{ xkcd.fetched_at }}</text>
+
+  <!-- XKCD Image -->
+  <image x="20" y="120" width="170" height="120" xlink:href="{{ xkcd.image_data }}"/>
+
+  <!-- Alt Text -->
+  <text x="105" y="260" font-family="Arial" font-size="6" fill="#666" text-anchor="middle">Alt text: {{ xkcd.alt_text }}</text>
+</svg>