0
# RST Directives
1

2
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.
3

4
## Capabilities
5

6
### Mini-Gallery Directive
7

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

10
```python { .api }
11
class MiniGallery(Directive):
12
    """
13
    RST directive for creating mini-galleries of related examples.
14
    
15
    Creates a gallery of examples that reference a specific function,
16
    class, or module. Automatically finds and displays relevant examples
17
    with thumbnails and links.
18
    """
19
```
20

21
#### Usage
22

23
```rst
24
.. minigallery:: numpy.mean
25
   :add-heading: Examples using ``numpy.mean``
26

27
.. minigallery:: matplotlib.pyplot.plot
28
   :add-heading:
29
   
30
.. minigallery:: sklearn.datasets.load_iris
31
```
32

33
#### Options
34

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

38
#### Example Output
39

40
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.
41

42
### Enhanced Image Directive
43

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

46
```python { .api }
47
class ImageSg(Directive):
48
    """
49
    Enhanced image directive with responsive srcset support.
50
    
51
    Extends the standard RST image directive to support modern
52
    responsive image features including srcset for different
53
    pixel densities and screen sizes.
54
    """
55
```
56

57
#### Usage
58

59
```rst
60
.. image-sg:: /auto_examples/images/plot_example_001.png
61
   :alt: Example plot showing data visualization
62
   :srcset: /auto_examples/images/plot_example_001.png, /auto_examples/images/plot_example_001_2x.png 2x
63
   :class: sphx-glr-single-img
64

65
.. image-sg:: /path/to/image.png
66
   :alt: Alternative text
67
   :width: 400px
68
   :height: 300px
69
```
70

71
#### Options
72

73
All standard RST image options plus:
74

75
- **srcset**: Responsive image sources for different screen densities
76
- **class**: CSS classes for styling (commonly `sphx-glr-single-img`)
77
- **alt**: Alternative text for accessibility
78
- **width**: Image width
79
- **height**: Image height
80
- **scale**: Scale factor
81
- **align**: Image alignment (left, center, right)
82

83
#### Responsive Images
84

85
The `srcset` option enables responsive images:
86

87
```rst
88
.. image-sg:: /images/plot_basic.png
89
   :alt: Basic plot
90
   :srcset: /images/plot_basic.png, /images/plot_basic_2x.png 2x, /images/plot_basic_mobile.png 480w
91
```
92

93
This provides:
94
- Standard resolution for normal displays
95
- High resolution (`2x`) for retina/high-DPI displays  
96
- Mobile-optimized version for small screens (`480w`)
97

98
### Node Registration
99

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

102
```python { .api }
103
def imagesg_addnode(app):
104
    """
105
    Registers custom Sphinx nodes for image handling.
106
    
107
    Adds the custom image-sg node type to the Sphinx application
108
    for proper rendering across different output formats (HTML, LaTeX, etc.).
109
    
110
    Parameters:
111
    - app: Sphinx application object
112
    """
113
```
114

115
## Integration Examples
116

117
### In Gallery Examples
118

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

121
```python
122
"""
123
Example Script
124
==============
125

126
This example demonstrates basic plotting functionality.
127

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

133
import matplotlib.pyplot as plt
134
import numpy as np
135

136
x = np.linspace(0, 10, 100)
137
y = np.sin(x)
138
plt.plot(x, y)
139
plt.show()
140
```
141

142
### In Documentation Pages
143

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

146
```rst
147
numpy.mean
148
==========
149

150
Compute the arithmetic mean along the specified axis.
151

152
.. minigallery:: numpy.mean
153
   :add-heading: Examples using ``numpy.mean``
154

155
This function computes the arithmetic mean of array elements...
156
```
157

158
### Cross-referencing Examples
159

160
Link to specific examples using enhanced images:
161

162
```rst
163
Advanced Techniques
164
===================
165

166
For more complex visualizations, see this example:
167

168
.. image-sg:: /auto_examples/images/sphx_glr_plot_advanced_001.png
169
   :alt: Advanced visualization example
170
   :class: sphx-glr-single-img
171
   :target: /auto_examples/plot_advanced.html
172
```
173

174
## Styling and CSS Classes
175

176
### Common CSS Classes
177

178
- **sphx-glr-single-img**: Standard styling for single gallery images
179
- **sphx-glr-multi-img**: Styling for multiple images in a row
180
- **figure**: Standard figure styling
181
- **align-center**: Center-aligned images
182

183
### Responsive Behavior
184

185
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.
186

187
## Accessibility Features
188

189
Both directives support accessibility features:
190

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

196
## Customization
197

198
### Custom CSS
199

200
You can customize the appearance with CSS:
201

202
```css
203
.sphx-glr-single-img {
204
    max-width: 100%;
205
    border: 1px solid #ddd;
206
    border-radius: 4px;
207
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
208
}
209

210
.sphx-glr-thumbcontainer {
211
    margin: 10px;
212
    text-align: center;
213
}
214
```
215

216
### Template Overrides
217

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