Update documentation for ImageBatch API

- Update API docs with correct ImageBatch usage and benefits
- Add comprehensive batch processing section to advanced usage
- Update getting started guide with modern batch examples
- Document auto-building, explicit building, and is_built property

Author: SmileyChris

docs/advanced-usage.md

@@ -35,13 +35,72 @@ class MyAppConfig(AppConfig):
         thumbnail.queue(Profile, build="src")
 ```
 
+## Batch Processing
+
+When rendering multiple images (e.g., in a list view), use `ImageBatch` to optimize database queries:
+
+```python
+from easy_images import ImageBatch, Img
+
+def product_list_view(request):
+    products = Product.objects.all()
+    
+    # Create a batch for efficient processing
+    batch = ImageBatch()
+    thumbnail = Img(batch=batch, width=300, format="webp")
+    
+    # Process all images
+    product_images = []
+    for product in products:
+        bound_img = thumbnail(product.image, alt=product.name)
+        product_images.append({
+            'product': product,
+            'image': bound_img
+        })
+    
+    # First access triggers batch loading of all images
+    # Subsequent accesses use cached data
+    return render(request, 'products.html', {
+        'product_images': product_images
+    })
+```
+
+### Benefits of Batching
+
+1. **Reduced Database Queries**: One query loads all image metadata instead of N queries
+2. **Shared Processing**: Images with the same source share processing results
+3. **Memory Efficiency**: Fresh batches prevent memory accumulation
+4. **Incremental Loading**: Can add images to already-loaded batches
+
+### Batch Building Strategies
+
+```python
+# Option 1: Automatic building on property access (default)
+batch = ImageBatch()
+img = Img(batch=batch, width=300)
+bound = img(file, build="src")
+url = bound.base_url()  # Triggers auto-build
+
+# Option 2: Explicit batch building
+batch = ImageBatch()
+img = Img(batch=batch, width=300)
+bound1 = img(file1, build="src")
+bound2 = img(file2, build="srcset")
+batch.build()  # Build all at once
+
+# Option 3: Immediate building (for signals/queue)
+img = Img(width=300)
+bound = img(file, build="src", immediate=True)
+```
+
 ## 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
+2. Use `ImageBatch` when rendering lists of images
+3. Set up Celery for distributed image processing
+4. Use `format="webp"` for best compression/performance balance
+5. Limit `densities` to `[2]` unless high-DPI support is critical (or turn it off entirely)
+6. Consider pre-generating common image sizes during deployment
 
 ## Signals
 

docs/api.md

@@ -25,26 +25,55 @@ img.queue(MyModel)  # Processes all ImageFields on MyModel
 ```
 
 #### `ImageBatch` - Batch Processing
+
+The `ImageBatch` class optimizes database queries when processing multiple images:
+
 ```python
-from easy_images import ImageBatch
+from easy_images import ImageBatch, Img
 
+# Create a shared batch for efficient processing
 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()
+# Create image configurations with the batch
+img = Img(batch=batch, width=800, format="webp")
+thumbnail = Img(batch=batch, width=200, format="jpg")
+
+# Add images to the batch
+bound1 = img(model1.image_field, alt="Main image")
+bound2 = thumbnail(model2.image_field, alt="Thumbnail")
+
+# Access images - batch loading happens automatically
+html1 = bound1.as_html()  # First access triggers batch loading
+html2 = bound2.as_html()  # Already loaded, no extra queries
+
+# Or explicitly build all images in the batch
+batch.build()
 ```
 
+**Key benefits:**
+- Batches database queries for multiple images
+- Shares loaded image data across all items in the batch
+- Supports incremental loading when adding images to an already-loaded batch
+- Automatic lazy building when properties are accessed
+
 #### `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'
+A `BoundImg` represents a single image item within a batch:
+
+```python
+# Properties (trigger auto-building if needed)
+main_url = bound_img.base_url()           # URL of the base image
+srcset_items = bound_img.srcset          # List of SrcSetItem objects
+alt_text = bound_img.alt                  # Alt text
+sizes_attr = bound_img.sizes             # Sizes attribute for responsive images
+html = bound_img.as_html()               # Complete <img> tag
+
+# Check if images are built
+if bound_img.is_built:
+    print("Images are ready")
+
+# Manually trigger building
+bound_img.build('all')  # Options: 'all', 'src', 'srcset'
 ```
 
 ### `easy_images.engine`

docs/getting-started.md

@@ -34,7 +34,29 @@ thumb = Img(width="md")
 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.
+### Batch Processing for Multiple Images
+
+When working with multiple images, use `ImageBatch` for better performance:
+
+```python
+from easy_images import Img, ImageBatch
+
+# Create a batch for efficient processing
+batch = ImageBatch()
+thumb = Img(batch=batch, width="md")
+
+# Process multiple images
+images = []
+for profile in profiles:
+    bound_img = thumb(profile.photo, alt=f"{profile.name}'s photo")
+    images.append(bound_img)
+
+# First access loads all images in one query
+for img in images:
+    print(img.as_html())
+```
+
+See the [API documentation](api.md#imagebatch-batch-processing) for more details.
 
 ### Using template tags
 ```html