RST Directives

Custom RST directives for creating mini-galleries and enhanced image displays in Sphinx documentation. These directives extend standard RST functionality with Sphinx-Gallery specific features.

Capabilities

Mini-Gallery Directive

Creates mini-galleries showing related examples that use specific functions or modules.

class MiniGallery(Directive):
    """
    RST directive for creating mini-galleries of related examples.
    
    Creates a gallery of examples that reference a specific function,
    class, or module. Automatically finds and displays relevant examples
    with thumbnails and links.
    """

Usage

.. minigallery:: numpy.mean
   :add-heading: Examples using ``numpy.mean``

.. minigallery:: matplotlib.pyplot.plot
   :add-heading:
   
.. minigallery:: sklearn.datasets.load_iris

Options

• add-heading: Adds a heading above the mini-gallery (optional)
• The argument (e.g., numpy.mean) specifies the function/module to find examples for

Example Output

The directive generates a responsive grid of example thumbnails with titles and links to the full examples. It automatically searches through your gallery examples to find those that import or use the specified function.

Enhanced Image Directive

Enhanced image directive with responsive srcset support for high-DPI displays and better mobile experience.

class ImageSg(Directive):
    """
    Enhanced image directive with responsive srcset support.
    
    Extends the standard RST image directive to support modern
    responsive image features including srcset for different
    pixel densities and screen sizes.
    """

Usage

.. image-sg:: /auto_examples/images/plot_example_001.png
   :alt: Example plot showing data visualization
   :srcset: /auto_examples/images/plot_example_001.png, /auto_examples/images/plot_example_001_2x.png 2x
   :class: sphx-glr-single-img

.. image-sg:: /path/to/image.png
   :alt: Alternative text
   :width: 400px
   :height: 300px

Options

All standard RST image options plus:

• srcset: Responsive image sources for different screen densities
• class: CSS classes for styling (commonly sphx-glr-single-img)
• alt: Alternative text for accessibility
• width: Image width
• height: Image height
• scale: Scale factor
• align: Image alignment (left, center, right)

Responsive Images

The srcset option enables responsive images:

.. image-sg:: /images/plot_basic.png
   :alt: Basic plot
   :srcset: /images/plot_basic.png, /images/plot_basic_2x.png 2x, /images/plot_basic_mobile.png 480w

This provides:

• Standard resolution for normal displays
• High resolution (2x) for retina/high-DPI displays
• Mobile-optimized version for small screens (480w)

Node Registration

Function for registering custom Sphinx nodes used by the image directive.

def imagesg_addnode(app):
    """
    Registers custom Sphinx nodes for image handling.
    
    Adds the custom image-sg node type to the Sphinx application
    for proper rendering across different output formats (HTML, LaTeX, etc.).
    
    Parameters:
    - app: Sphinx application object
    """

Integration Examples

In Gallery Examples

Within example Python scripts, you can reference the generated images:

"""
Example Script
==============

This example demonstrates basic plotting functionality.

.. image-sg:: /auto_examples/images/sphx_glr_plot_basic_001.png
   :alt: Basic line plot
   :class: sphx-glr-single-img
"""

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.plot(x, y)
plt.show()

In Documentation Pages

Use mini-galleries to show related examples in API documentation:

numpy.mean
==========

Compute the arithmetic mean along the specified axis.

.. minigallery:: numpy.mean
   :add-heading: Examples using ``numpy.mean``

This function computes the arithmetic mean of array elements...

Cross-referencing Examples

Link to specific examples using enhanced images:

Advanced Techniques
===================

For more complex visualizations, see this example:

.. image-sg:: /auto_examples/images/sphx_glr_plot_advanced_001.png
   :alt: Advanced visualization example
   :class: sphx-glr-single-img
   :target: /auto_examples/plot_advanced.html

Styling and CSS Classes

Common CSS Classes

• sphx-glr-single-img: Standard styling for single gallery images
• sphx-glr-multi-img: Styling for multiple images in a row
• figure: Standard figure styling
• align-center: Center-aligned images

Responsive Behavior

The directives automatically generate responsive HTML that adapts to different screen sizes and devices. Images scale appropriately and mini-galleries reflow based on available space.

Accessibility Features

Both directives support accessibility features:

• Alt text: Always provide meaningful alt text for screen readers
• Semantic markup: Proper HTML structure for assistive technologies
• Keyboard navigation: Mini-galleries support keyboard navigation
• High contrast: Compatible with high contrast themes

Customization

Custom CSS

You can customize the appearance with CSS:

.sphx-glr-single-img {
    max-width: 100%;
    border: 1px solid #ddd;
    border-radius: 4px;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

.sphx-glr-thumbcontainer {
    margin: 10px;
    text-align: center;
}

Template Overrides

Advanced users can override the HTML templates used by the directives by providing custom templates in their Sphinx theme.