Image Scrapers

def matplotlib_scraper(block, block_vars, gallery_conf, **kwargs):
    """
    Scrapes matplotlib figures from code execution.
    
    Automatically detects and saves matplotlib figures created during
    code block execution, handling both explicit plt.show() calls and
    figures created but not explicitly shown.
    
    Parameters:
    - block: dict, code block information with 'code_obj' and execution context
    - block_vars: dict, variables from code execution including local/global scope
    - gallery_conf: dict, gallery configuration options
    - **kwargs: Additional scraper arguments
    
    Returns:
    list: Filenames of images that were saved
    """

# conf.py
sphinx_gallery_conf = {
    'image_scrapers': ['matplotlib'],  # Default scraper
    # or with custom settings:
    'image_scrapers': [matplotlib_scraper],
}

def save_figures(block, block_vars, gallery_conf):
    """
    Main function to save figures using configured scrapers.
    
    Iterates through all configured scrapers and saves any figures
    they detect from the executed code block.
    
    Parameters:
    - block: dict, code block information
    - block_vars: dict, execution variables
    - gallery_conf: dict, gallery configuration
    
    Returns:
    list: All saved image filenames from all scrapers
    """

class ImagePathIterator:
    """
    Iterator for generating sequential image paths.
    
    Generates sequential filenames for images within an example,
    ensuring unique names and proper organization.
    """
    
    def __init__(self, image_path):
        """
        Parameters:
        - image_path: str, base image path template
        """
    
    def __iter__(self):
        """Returns iterator instance."""
    
    def __next__(self):
        """
        Returns:
        str: Next sequential image filename
        """

from sphinx_gallery.scrapers import ImagePathIterator

iterator = ImagePathIterator('/path/to/images/sphx_glr_example_{:03d}.png')
first_image = next(iterator)   # sphx_glr_example_001.png
second_image = next(iterator)  # sphx_glr_example_002.png

def figure_rst(figure_list, sources_dir, fig_titles="", srcsetpaths=None):
    """
    Generates RST code for embedding images in documentation.
    
    Creates properly formatted RST image directives with responsive
    srcset support and appropriate styling classes.
    
    Parameters:
    - figure_list: list, image filenames to embed
    - sources_dir: str, source directory path for resolving relative paths
    - fig_titles: str or list, titles for images (optional)
    - srcsetpaths: list, responsive image paths for srcset (optional)
    
    Returns:
    str: RST code for embedding the images
    """

.. image-sg:: /auto_examples/images/sphx_glr_plot_001.png
    :alt: Plot output
    :srcset: /auto_examples/images/sphx_glr_plot_001.png, /auto_examples/images/sphx_glr_plot_001_2x.png 2x
    :class: sphx-glr-single-img

def clean_modules(gallery_conf, fname, when):
    """
    Resets/cleans modules between example executions.
    
    Removes specified modules from sys.modules to ensure clean
    execution environment for each example.
    
    Parameters:
    - gallery_conf: dict, gallery configuration with 'reset_modules'
    - fname: str, current filename being processed
    - when: str, when cleanup is happening ('before' or 'after')
    """

def plotly_scraper(block, block_vars, gallery_conf):
    """Custom scraper for Plotly figures."""
    import plotly.io as pio
    
    # Get all current plotly figures
    figures = []
    
    # Check for plotly figures in the execution namespace
    for var_name, var_value in block_vars.items():
        if hasattr(var_value, '_plot_html'):
            # This is a plotly figure
            image_path_iterator = block_vars['image_path_iterator']
            img_fname = next(image_path_iterator)
            
            # Save as static image
            pio.write_image(var_value, img_fname)
            figures.append(img_fname)
    
    return figures

# Configuration
sphinx_gallery_conf = {
    'image_scrapers': [matplotlib_scraper, plotly_scraper],
}

from sphinx_gallery.scrapers import matplotlib_scraper

def mayavi_scraper(block, block_vars, gallery_conf):
    """Scraper for Mayavi 3D visualizations."""
    # Implementation for Mayavi figure detection and saving
    pass

def seaborn_scraper(block, block_vars, gallery_conf):
    """Scraper for Seaborn statistical plots."""
    # Seaborn uses matplotlib backend, so matplotlib_scraper handles it
    # This is just an example of how you might extend it
    pass

sphinx_gallery_conf = {
    'image_scrapers': [
        matplotlib_scraper,
        mayavi_scraper,
        'plotly',  # Built-in plotly scraper (if available)
    ],
}

sphinx_gallery_conf = {
    'image_scrapers': ['matplotlib'],
    'compress_images': ['images'],  # Directories to compress
    'compress_images_args': ['-quality', '85'],  # ImageMagick args
    'thumbnail_size': (200, 200),  # Thumbnail dimensions
}

sphinx_gallery_conf = {
    'reset_modules': ('matplotlib.pyplot', 'seaborn'),  # Reset between examples
    'capture_repr': ('matplotlib.figure.Figure',),      # Capture object representations
}

def robust_scraper(block, block_vars, gallery_conf):
    """Example of robust error handling in scrapers."""
    figures = []
    
    try:
        # Scraper logic here
        pass
    except Exception as e:
        # Log error but don't break build
        print(f"Scraper error: {e}")
    
    return figures

def conditional_scraper(block, block_vars, gallery_conf):
    """Scraper that only runs under certain conditions."""
    
    # Only run if specific library is imported
    if 'my_viz_lib' not in block_vars:
        return []
    
    # Scraping logic here
    return saved_images

sphinx_gallery_conf = {
    'log_level': {'examples_log_level': 'DEBUG'},  # Enable debug logging
    'only_warn_on_example_error': True,           # Continue on errors
}