Docs

Author: SmileyChris

.github/workflows/docs.yml

@@ -0,0 +1,18 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Deploy to GitHub Pages
+        run: uvx mkdocs gh-deploy --force

.gitignore

@@ -1,3 +1,4 @@
 example.jpg
 dist/
 .coverage
+site

README.md

@@ -1,3 +1,4 @@
+
 # Django easy images
 
 Easily build responsive HTML `<img>` tags by thumbnailing Django images using the VIPS fast image processing library.
@@ -38,7 +39,23 @@ INSTALLED_APPS = [
     # ...
 ]
 ```
+Since this uses pyvips, you'll need to have the [libvips library installed on your system](https://www.libvips.org/install.html).
+
+## Documentation
+
+Project documentation is built using [mkdocs](https://www.mkdocs.org/). To build and serve the documentation locally:
+
+```bash
+pip install mkdocs
+mkdocs serve
+```
+
+Then open http://localhost:8000 in your browser.
 
+The documentation includes:
+- Usage examples
+- API reference
+- Configuration options
 Since this uses pyvips, you'll need to have the [libvips library installed on your system](https://www.libvips.org/install.html).
 
 <table>

docs/advanced-usage.md

@@ -0,0 +1,75 @@
+# Advanced Usage
+
+## Queue Management
+
+### Building Images
+
+Images are built either:
+
+1. Via cron job running `build_img_queue`
+2. Or via task runner using the `queued_img` signal
+
+### Manual Queueing
+
+Queue images manually using the `queue` method:
+
+```python
+from easy_images import Img
+from my_app.models import Product
+
+thumbnail = Img(width=300)
+thumbnail.queue(Product, fields=['main_image'])
+```
+
+### Automatic Queueing
+
+Automatically queue images when a FileField is saved using [signals](#signals): 
+
+```python
+from django.apps import AppConfig
+from my_app.images import thumbnail
+
+class MyAppConfig(AppConfig):
+    def ready(self):
+        from my_app.models import Profile
+        thumbnail.queue(Profile, build="src")
+```
+
+## Performance Tips
+
+1. For high-traffic sites, use `build="src"` to generate base images immediately
+2. Set up Celery for distributed image processing
+3. Use `format="webp"` for best compression/performance balance
+4. Limit `densities` to `[2]` unless high-DPI support is critical (or turn it off entirely)
+5. Consider pre-generating common image sizes during deployment
+
+## Signals
+
+### `file_post_save`
+Triggered when a FileField is saved. Use to automatically queue images:
+
+```python
+from django.apps import AppConfig
+from my_app.images import thumbnail
+
+class MyAppConfig(AppConfig):
+    def ready(self):
+        from my_app.models import Profile
+        thumbnail.queue(Profile, build="src")
+```
+
+### `queued_img` 
+Triggered when images need building. Use with Celery:
+
+```python
+from easy_images.management.process_queue import process_queue
+from easy_images.signals import queued_img
+
+@app.task
+def build_img_queue():
+    process_queue()
+
+# In apps.py:
+queued_img.connect(lambda **kwargs: build_img_queue.delay(), weak=False)
+```
+

docs/api.md

@@ -0,0 +1,76 @@
+# API Reference
+
+## Core Modules
+
+### `easy_images.core`
+
+Main functionality for image processing with these key classes:
+
+#### `Img` - Image Configuration
+```python
+from easy_images import Img
+
+# Basic usage
+img = Img(width=800, format='webp', quality=85)
+processed_img = img(my_model.image_field)
+
+# Chaining configurations
+responsive_img = (
+    Img(width=1200)
+    .extend(width=800, sizes={'768': 600, '480': 400})
+)
+
+# Automatic processing on model save
+img.queue(MyModel)  # Processes all ImageFields on MyModel
+```
+
+#### `ImageBatch` - Batch Processing
+```python
+from easy_images import ImageBatch
+
+batch = ImageBatch()
+img1 = batch.add(source_file=model1.image_field, options={'width': 800})
+img2 = batch.add(source_file=model2.image_field, options={'width': 600})
+
+# Get HTML for all images
+html1 = img1.as_html()
+html2 = img2.as_html()
+```
+
+#### `BoundImg` - Processed Image
+```python
+# Get image URLs
+main_url = processed_img.base_url()
+srcset = processed_img.srcset  # List of available sizes
+
+# Build images immediately (instead of queue)
+processed_img.build('all')  # Options: 'all', 'base', 'srcset'
+```
+
+### `easy_images.engine`
+Image processing engine implementation
+
+### `easy_images.models`
+Database models for storing image information
+
+## Management Commands
+
+### `build_img_queue`
+Processes pending images in the queue:
+```bash
+python manage.py build_img_queue
+```
+
+## Template Tags
+
+### `easy_images`
+Template tags for rendering processed images:
+```html
+{% load easy_images %}
+
+<!-- Basic usage -->
+{% easy_image obj.image_field width=800 %}
+
+<!-- With responsive sizes -->
+{% easy_image obj.image_field width=1200 sizes="(max-width: 768px) 600px, (max-width: 480px) 400px" %}
+```

docs/configuration.md

@@ -0,0 +1,85 @@
+# Configuration Options
+
+## Image Processing Options
+
+### `width`
+Limit the width of the image. Can be:
+
+- Integer (pixels)
+- Tailwind size string: "xs", "sm", "md", "lg", "screen-sm", "screen-md", "screen-lg", "screen-xl", "screen-2xl"
+
+```python
+Img(width=300)  # Fixed width
+Img(width="md")  # Responsive width
+```
+
+### `ratio`
+The aspect ratio of the image. Can be:
+
+- Float (e.g. `4/5`)
+- String: "square", "video" (16/9), "video_vertical", "golden", "golden_vertical"
+
+```python
+Img(ratio="square")  # 1:1 ratio
+Img(ratio=16/9)      # Custom ratio
+```
+
+### `crop`
+How to crop the image:
+
+- `True` (default): Crop from center (0.5, 0.5)
+- `False`: Don't crop (use CSS object-fit instead)
+- Tuple: (x%, y%) crop position
+- String: Position keywords like "tl", "tr", "bl", "br", "l", "r", "t", "b"
+
+```python
+Img(crop="tl")  # Crop from top-left
+Img(crop=False) # No cropping
+```
+
+### `quality`
+Image compression quality (default: 80)
+
+```python
+Img(quality=90)  # Higher quality
+```
+
+## Advanced Options
+
+### `sizes`
+Responsive sizes for different media queries:
+
+```python
+Img(
+    width=300,
+    sizes={
+        "print": {"width": 450, "quality": 90},
+        800: 100  # Max-width 800px
+    }
+)
+```
+
+### `format`
+`srcset` image format (default: "webp"):
+
+- "webp" (recommended)
+- "avif" (memory intensive)
+- "jpeg"
+
+```python
+Img(format="avif")  # Use AVIF format
+```
+
+### `focal_window`
+Zoom area specified as (x1%, y1%, x2%, y2%):
+
+```python
+Img(focal_window=(25, 25, 75, 75))  # Zoom center 50% of image
+```
+
+### `densities`
+Higher density versions to generate (default: `[2]`):
+
+```python
+Img(densities=[1.5, 2, 3])  # Generate 1.5x, 2x and 3x versions
+```

docs/getting-started.md

@@ -0,0 +1,52 @@
+# Getting Started
+
+## Installation
+
+```bash
+pip install django-easy-images
+```
+
+Add to your Django settings:
+```python
+INSTALLED_APPS = [
+    "easy_images",
+    # ...
+]
+```
+
+### Dependencies
+You'll need [libvips](https://www.libvips.org/install.html) installed:
+
+- **MacOS**: `brew install vips`
+- **Ubuntu**: `sudo apt-get install --no-install-recommends libvips`
+- **Arch**: `sudo pacman -S libvips`
+
+## Basic Usage
+
+### Using the Img class
+```python
+from easy_images import Img
+
+# Create an image configuration
+thumb = Img(width="md")
+
+# Generate HTML for an image
+html = thumb(profile.photo, alt="Profile photo").as_html()
+```
+
+If you're going to be building several images, consider using the [`ImageBatch`](api.md#imagebatch) class to process them in bulk.
+
+### Using template tags
+```html
+{% load easy_images %}
+
+<!-- Basic usage -->
+{% img report.image width="md" alt="" %}
+
+<!-- With predefined Img instance -->
+{% img report.image thumb alt="" %}
+```
+
+## Next Steps
+- [Configuration Options](configuration.md)
+- [Advanced Usage](advanced-usage.md)

docs/index.md

@@ -0,0 +1,35 @@
+# Django Easy Images Documentation
+
+Welcome to the documentation for Django Easy Images - a powerful image processing solution for Django projects.
+
+## What is Django Easy Images?
+
+Django Easy Images makes it simple to:
+
+- Generate responsive HTML `<img>` tags
+- Automatically create thumbnails and optimized versions
+- Queue image processing for better performance
+- Support modern formats like WebP and AVIF
+
+## Quick Start
+
+```python
+from easy_images import Img
+
+# Create a thumbnail configuration
+profile_thumb = Img(width=200, ratio="square")
+
+# Generate HTML for a profile photo
+html = profile_thumb(user.profile.photo, alt="User profile").as_html()
+```
+
+## Documentation Sections
+
+1. [Getting Started](getting-started.md) - Installation and basic usage
+2. [Configuration](configuration.md) - All available image processing options
+3. [Advanced Usage](advanced-usage.md) - Signals, queue management and performance tips
+4. [API Reference](api.md) - Detailed technical documentation
+
+## Need Help?
+
+Found an issue or have questions? Please [open an issue](https://github.com/your-repo/issues) on GitHub.

mkdocs.yml

@@ -0,0 +1,14 @@
+site_name: Django Easy Images
+
+nav:
+  - Getting Started: getting-started.md
+  - Configuration: configuration.md
+  - Advanced Usage: advanced-usage.md
+  - API Reference: api.md
+
+theme:
+  name: mkdocs
+
+markdown_extensions:
+  - admonition
+  - codehilite