Add post-build script to fix animated GIF thumbnails

- Created docs/post_build.py to copy GIF thumbnails and update HTML references
- Added comprehensive documentation in docs/ANIMATED_THUMBNAILS.md
- Script works around sphinx-gallery limitation with GIF thumbnail paths
- Enables animated thumbnails to display properly on Read the Docs
- Includes instructions for local development and Read the Docs integration

Root cause: sphinx-gallery ignores sphinx_gallery_thumbnail_path for GIFs
Solution: Post-build processing to copy GIFs and update HTML references

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: jeremymanning

docs/ANIMATED_THUMBNAILS.md

@@ -0,0 +1,100 @@
+# Animated Thumbnails Fix
+
+## Problem
+The gallery thumbnails for animated examples (chemtrails, animate_MDS, animate_spin, animate, precog, save_movie) were not displaying as animated GIFs. Instead, they showed static PNG thumbnails or placeholder images.
+
+## Root Cause
+Sphinx-gallery ignores the `sphinx_gallery_thumbnail_path` directive when it points to GIF files and generates PNG thumbnails instead. The GIF files are properly stored in version control but need to be manually copied and HTML references updated after the build.
+
+## Solution
+A post-build script (`docs/post_build.py`) has been created that:
+
+1. **Copies GIF thumbnails**: Moves animated GIF files from `docs/_static/thumbnails/` to `docs/_build/html/_images/`
+2. **Updates HTML references**: Replaces PNG thumbnail references with GIF references in the gallery HTML
+
+## Usage
+
+### Local Development
+After building documentation locally:
+```bash
+cd docs/
+make html
+python post_build.py
+```
+
+### Read the Docs Integration
+For Read the Docs, add this to your `.readthedocs.yaml`:
+```yaml
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_create_environment:
+      # Install dependencies
+      - pip install -r requirements.txt
+    post_build:
+      # Fix animated thumbnails after build
+      - python docs/post_build.py
+```
+
+### Manual Build Commands
+```bash
+# Clean build
+make clean
+make html
+python post_build.py
+
+# Or direct sphinx
+python -m sphinx.cmd.build -b html . _build/html
+python post_build.py
+```
+
+## Files Involved
+
+### Animated Examples with Custom Thumbnails
+- `examples/chemtrails.py` → `sphx_glr_chemtrails_thumb.gif`
+- `examples/animate_MDS.py` → `sphx_glr_animate_MDS_thumb.gif`  
+- `examples/animate_spin.py` → `sphx_glr_animate_spin_thumb.gif`
+- `examples/animate.py` → `sphx_glr_animate_thumb.gif`
+- `examples/precog.py` → `sphx_glr_precog_thumb.gif`
+- `examples/save_movie.py` → `sphx_glr_save_movie_thumb.gif`
+
+### Static Examples with Custom Thumbnails
+- `examples/explore.py` → `sphx_glr_explore_thumb.png`
+- `examples/save_image.py` → `sphx_glr_save_image_thumb.png`
+- `examples/analyze.py` → `sphx_glr_analyze_thumb.png`
+
+### Key Directories
+- `docs/_static/thumbnails/` - Version controlled custom thumbnails (source)
+- `docs/_build/html/_images/` - Built documentation images (target)
+- `docs/post_build.py` - Automation script
+
+## Technical Details
+
+Each example file includes a `sphinx_gallery_thumbnail_path` comment:
+```python
+# sphinx_gallery_thumbnail_path = '_static/thumbnails/sphx_glr_example_thumb.gif'
+```
+
+However, sphinx-gallery generates PNG thumbnails regardless of this directive when pointing to GIF files. The post-build script works around this limitation by:
+
+1. Copying the actual GIF files to the correct location
+2. Updating the HTML to reference the GIF files instead of PNG files
+
+## Verification
+
+After running the post-build script:
+1. Check that GIF files exist in `docs/_build/html/_images/`
+2. Open `docs/_build/html/auto_examples/index.html` in a browser
+3. Verify that animated examples show moving thumbnails
+4. Verify that static examples (explore, save_image, analyze) show custom static thumbnails
+
+## Maintenance
+
+When adding new animated examples:
+1. Create the animated GIF thumbnail (50fps, infinite loop)
+2. Add the GIF to `docs/_static/thumbnails/`
+3. Add `sphinx_gallery_thumbnail_path` comment to the example
+4. Update `GIF_REPLACEMENTS` dictionary in `docs/post_build.py`
+5. Commit all changes to version control

docs/post_build.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""
+Post-build script to copy custom GIF thumbnails and update HTML references.
+
+This script should be run after sphinx-gallery builds the documentation
+to replace PNG thumbnails with animated GIF thumbnails for specific examples.
+"""
+
+import os
+import shutil
+import re
+
+# Base paths
+DOCS_DIR = os.path.dirname(os.path.abspath(__file__))
+STATIC_THUMBS_DIR = os.path.join(DOCS_DIR, "_static", "thumbnails")
+BUILD_IMAGES_DIR = os.path.join(DOCS_DIR, "_build", "html", "_images")
+GALLERY_HTML = os.path.join(DOCS_DIR, "_build", "html", "auto_examples", "index.html")
+
+# Mapping of PNG to GIF thumbnails that should be replaced
+GIF_REPLACEMENTS = {
+    "sphx_glr_chemtrails_thumb.png": "sphx_glr_chemtrails_thumb.gif",
+    "sphx_glr_animate_MDS_thumb.png": "sphx_glr_animate_MDS_thumb.gif", 
+    "sphx_glr_animate_spin_thumb.png": "sphx_glr_animate_spin_thumb.gif",
+    "sphx_glr_animate_thumb.png": "sphx_glr_animate_thumb.gif",
+    "sphx_glr_precog_thumb.png": "sphx_glr_precog_thumb.gif",
+    "sphx_glr_save_movie_thumb.png": "sphx_glr_save_movie_thumb.gif"
+}
+
+def copy_gif_thumbnails():
+    """Copy GIF thumbnails from _static/thumbnails to _build/html/_images"""
+    print("Copying GIF thumbnails...")
+    
+    if not os.path.exists(BUILD_IMAGES_DIR):
+        print(f"Error: Build images directory not found: {BUILD_IMAGES_DIR}")
+        return False
+        
+    if not os.path.exists(STATIC_THUMBS_DIR):
+        print(f"Error: Static thumbnails directory not found: {STATIC_THUMBS_DIR}")
+        return False
+    
+    # Copy all GIF files from static to build directory
+    gif_files = [f for f in os.listdir(STATIC_THUMBS_DIR) if f.endswith('.gif')]
+    
+    for gif_file in gif_files:
+        src = os.path.join(STATIC_THUMBS_DIR, gif_file)
+        dst = os.path.join(BUILD_IMAGES_DIR, gif_file)
+        
+        shutil.copy2(src, dst)
+        print(f"  Copied: {gif_file}")
+    
+    print(f"Copied {len(gif_files)} GIF thumbnails")
+    return True
+
+def update_html_references():
+    """Update HTML gallery to reference GIF files instead of PNG"""
+    print("Updating HTML references...")
+    
+    if not os.path.exists(GALLERY_HTML):
+        print(f"Error: Gallery HTML not found: {GALLERY_HTML}")
+        return False
+    
+    # Read the HTML file
+    with open(GALLERY_HTML, 'r', encoding='utf-8') as f:
+        html_content = f.read()
+    
+    # Replace PNG references with GIF references
+    replacements_made = 0
+    for png_name, gif_name in GIF_REPLACEMENTS.items():
+        if png_name in html_content:
+            html_content = html_content.replace(png_name, gif_name)
+            replacements_made += 1
+            print(f"  Replaced: {png_name} -> {gif_name}")
+    
+    # Write the updated HTML back
+    with open(GALLERY_HTML, 'w', encoding='utf-8') as f:
+        f.write(html_content)
+    
+    print(f"Made {replacements_made} HTML replacements")
+    return True
+
+def main():
+    """Main function to run post-build processing"""
+    print("Running post-build script to fix animated thumbnails...")
+    
+    success = copy_gif_thumbnails()
+    if success:
+        success = update_html_references()
+    
+    if success:
+        print("✅ Post-build processing completed successfully!")
+        print("Animated GIF thumbnails should now be working in the gallery.")
+    else:
+        print("❌ Post-build processing failed!")
+        return 1
+    
+    return 0
+
+if __name__ == "__main__":
+    exit(main())