0
# Extension Setup
1

2
Core extension configuration and setup functions for integrating Sphinx-Gallery into Sphinx documentation projects. This module provides the primary entry points for configuring and initializing the extension.
3

4
## Capabilities
5

6
### Main Extension Setup
7

8
The primary setup function that registers Sphinx-Gallery as a Sphinx extension with full gallery generation capabilities.
9

10
```python { .api }
11
def setup(app):
12
    """
13
    Main Sphinx extension setup function.
14
    
15
    Registers the sphinx-gallery extension with Sphinx, adding configuration
16
    options, event handlers, and custom directives for gallery generation.
17
    
18
    Parameters:
19
    - app: Sphinx application object
20
    
21
    Returns:
22
    dict: Extension metadata with version and parallel read/write safety
23
    """
24
```
25

26
Usage in `conf.py`:
27

28
```python
29
extensions = ['sphinx_gallery.gen_gallery']
30

31
sphinx_gallery_conf = {
32
    'examples_dirs': '../examples',
33
    'gallery_dirs': 'auto_examples',
34
    # Additional configuration options...
35
}
36
```
37

38
### CSS-Only Setup
39

40
Alternative setup function for loading only Sphinx-Gallery CSS styles without full gallery generation functionality.
41

42
```python { .api }
43
def setup(app):
44
    """
45
    Setup function for CSS-only mode.
46
    
47
    Loads Sphinx-Gallery CSS styles without enabling gallery generation.
48
    Useful when you want the visual styling but don't need to generate
49
    galleries from example scripts.
50
    
51
    Parameters:
52
    - app: Sphinx application object
53
    
54
    Returns:
55
    dict: Extension metadata
56
    """
57
```
58

59
Usage in `conf.py`:
60

61
```python
62
extensions = ['sphinx_gallery.load_style']
63
```
64

65
### Configuration Management
66

67
Function for validating and filling default configuration values.
68

69
```python { .api }
70
def fill_gallery_conf_defaults(app, config, check_keys=True):
71
    """
72
    Validates and fills default values for sphinx_gallery_conf.
73
    
74
    Parameters:
75
    - app: Sphinx application object
76
    - config: Sphinx configuration object
77
    - check_keys: bool, whether to validate configuration keys
78
    
79
    Returns:
80
    dict: Complete configuration with defaults filled
81
    """
82
```
83

84
### Default Configuration
85

86
Complete default configuration dictionary containing all available options.
87

88
```python { .api }
89
DEFAULT_GALLERY_CONF = {
90
    'filename_pattern': re.escape(os.sep) + 'plot',
91
    'ignore_pattern': r'__init__\.py',
92
    'examples_dirs': os.path.join('..', 'examples'),
93
    'example_extensions': {'.py'},
94
    'filetype_parsers': {},
95
    'notebook_extensions': {'.py'},
96
    'reset_argv': DefaultResetArgv(),
97
    'subsection_order': None,
98
    'within_subsection_order': 'NumberOfCodeLinesSortKey',
99
    'minigallery_sort_order': None,
100
    'gallery_dirs': 'auto_examples',
101
    'backreferences_dir': None,
102
    'doc_module': (),
103
    'exclude_implicit_doc': set(),
104
    'reference_url': {},
105
    'capture_repr': ('_repr_html_', '__repr__'),
106
    'ignore_repr_types': r'',
107
    'plot_gallery': 'True',
108
    'download_all_examples': True,
109
    'abort_on_example_error': False,
110
    'only_warn_on_example_error': False,
111
    'recommender': {'enable': False},
112
    'failing_examples': {},
113
    'passing_examples': [],
114
    'stale_examples': [],
115
    'run_stale_examples': False,
116
    'expected_failing_examples': set(),
117
    'thumbnail_size': (400, 280),
118
    'min_reported_time': 0,
119
    'write_computation_times': os.getenv('SOURCE_DATE_EPOCH') is None,
120
    'binder': {},
121
    'jupyterlite': {},
122
    'promote_jupyter_magic': False,
123
    'image_scrapers': ('matplotlib',),
124
    'compress_images': (),
125
    'reset_modules': ('matplotlib', 'seaborn'),
126
    'reset_modules_order': 'before',
127
    'first_notebook_cell': None,
128
    'last_notebook_cell': None,
129
    'notebook_images': False,
130
    'pypandoc': False,
131
    'remove_config_comments': False,
132
    'show_memory': False,
133
    'show_signature': True,
134
    'junit': '',
135
    'log_level': {'backreference_missing': 'warning'},
136
    'inspect_global_variables': True,
137
    'css': _KNOWN_CSS,
138
    'matplotlib_animations': False,
139
    'image_srcset': [],
140
    'default_thumb_file': None,
141
    'line_numbers': False,
142
    'nested_sections': True,
143
    'prefer_full_module': set(),
144
    'api_usage_ignore': '.*__.*__',
145
    'show_api_usage': False,
146
    'copyfile_regex': '',
147
    'parallel': False
148
}
149
```
150

151
## Configuration Categories
152

153
### Core Gallery Settings
154

155
Essential configuration for gallery generation:
156

157
- **examples_dirs** (str): Source directory containing example scripts (default: `'../examples'`)
158
- **gallery_dirs** (str): Output directory for generated galleries (default: `'auto_examples'`)
159
- **filename_pattern** (str): Regex pattern for example files (default: `re.escape(os.sep) + 'plot'`)
160
- **ignore_pattern** (str): Files to ignore (default: `r'__init__\.py'`)
161
- **plot_gallery** (str): Whether to execute examples ('True', 'False', or 'auto')
162

163
### Execution Control
164

165
Options controlling example execution:
166

167
- **abort_on_example_error** (bool): Stop build on first error
168
- **only_warn_on_example_error** (bool): Continue with warnings on errors
169
- **expected_failing_examples** (set): Scripts expected to fail
170
- **run_stale_examples** (bool): Re-run examples when source changes
171

172
### Output Options
173

174
Settings for generated output:
175

176
- **download_all_examples** (bool): Generate download links for examples
177
- **thumbnail_size** (tuple): Dimensions for generated thumbnails (default: `(400, 280)`)
178
- **show_memory** (bool): Display memory usage information
179
- **show_signature** (bool): Include Sphinx-Gallery signature in output
180

181
### Advanced Configuration
182

183
Advanced customization options:
184

185
- **image_scrapers** (tuple): Functions for extracting images from code (default: `('matplotlib',)`)
186
- **reset_modules** (tuple): Modules to reset between example executions (default: `('matplotlib', 'seaborn')`)
187
- **subsection_order** (str/callable): Function for ordering gallery subsections
188
- **within_subsection_order** (str/callable): Function for ordering within subsections
189
- **first_notebook_cell** (str): Content for first notebook cell
190
- **last_notebook_cell** (str): Content for last notebook cell
191

192
## Usage Examples
193

194
### Basic Gallery Setup
195

196
```python
197
# conf.py
198
extensions = ['sphinx_gallery.gen_gallery']
199

200
sphinx_gallery_conf = {
201
    'examples_dirs': '../examples',
202
    'gallery_dirs': 'auto_examples',
203
    'filename_pattern': '/plot_.*\.py$',
204
    'ignore_pattern': r'__init__\.py',
205
}
206
```
207

208
### Advanced Configuration
209

210
```python
211
# conf.py
212
from sphinx_gallery.sorting import ExplicitOrder
213

214
extensions = ['sphinx_gallery.gen_gallery']
215

216
sphinx_gallery_conf = {
217
    'examples_dirs': '../examples',
218
    'gallery_dirs': 'auto_examples',
219
    'subsection_order': ExplicitOrder(['basic', 'advanced', 'expert']),
220
    'show_memory': True,
221
    'download_all_examples': True,
222
    'expected_failing_examples': {'plot_broken_example.py'},
223
    'thumbnail_size': (250, 250),
224
}
225
```
226

227
### CSS-Only Integration
228

229
```python
230
# conf.py
231
extensions = ['sphinx_gallery.load_style']
232

233
# No sphinx_gallery_conf needed for CSS-only mode
234
```