CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-sphinx-gallery

A Sphinx extension that builds an HTML gallery of examples from any set of Python scripts.

Overview
Eval results
Files

extension-setup.mddocs/

Extension Setup

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.

Capabilities

Main Extension Setup

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

def setup(app):
    """
    Main Sphinx extension setup function.
    
    Registers the sphinx-gallery extension with Sphinx, adding configuration
    options, event handlers, and custom directives for gallery generation.
    
    Parameters:
    - app: Sphinx application object
    
    Returns:
    dict: Extension metadata with version and parallel read/write safety
    """

Usage in conf.py:

extensions = ['sphinx_gallery.gen_gallery']

sphinx_gallery_conf = {
    'examples_dirs': '../examples',
    'gallery_dirs': 'auto_examples',
    # Additional configuration options...
}

CSS-Only Setup

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

def setup(app):
    """
    Setup function for CSS-only mode.
    
    Loads Sphinx-Gallery CSS styles without enabling gallery generation.
    Useful when you want the visual styling but don't need to generate
    galleries from example scripts.
    
    Parameters:
    - app: Sphinx application object
    
    Returns:
    dict: Extension metadata
    """

Usage in conf.py:

extensions = ['sphinx_gallery.load_style']

Configuration Management

Function for validating and filling default configuration values.

def fill_gallery_conf_defaults(app, config, check_keys=True):
    """
    Validates and fills default values for sphinx_gallery_conf.
    
    Parameters:
    - app: Sphinx application object
    - config: Sphinx configuration object
    - check_keys: bool, whether to validate configuration keys
    
    Returns:
    dict: Complete configuration with defaults filled
    """

Default Configuration

Complete default configuration dictionary containing all available options.

DEFAULT_GALLERY_CONF = {
    'filename_pattern': re.escape(os.sep) + 'plot',
    'ignore_pattern': r'__init__\.py',
    'examples_dirs': os.path.join('..', 'examples'),
    'example_extensions': {'.py'},
    'filetype_parsers': {},
    'notebook_extensions': {'.py'},
    'reset_argv': DefaultResetArgv(),
    'subsection_order': None,
    'within_subsection_order': 'NumberOfCodeLinesSortKey',
    'minigallery_sort_order': None,
    'gallery_dirs': 'auto_examples',
    'backreferences_dir': None,
    'doc_module': (),
    'exclude_implicit_doc': set(),
    'reference_url': {},
    'capture_repr': ('_repr_html_', '__repr__'),
    'ignore_repr_types': r'',
    'plot_gallery': 'True',
    'download_all_examples': True,
    'abort_on_example_error': False,
    'only_warn_on_example_error': False,
    'recommender': {'enable': False},
    'failing_examples': {},
    'passing_examples': [],
    'stale_examples': [],
    'run_stale_examples': False,
    'expected_failing_examples': set(),
    'thumbnail_size': (400, 280),
    'min_reported_time': 0,
    'write_computation_times': os.getenv('SOURCE_DATE_EPOCH') is None,
    'binder': {},
    'jupyterlite': {},
    'promote_jupyter_magic': False,
    'image_scrapers': ('matplotlib',),
    'compress_images': (),
    'reset_modules': ('matplotlib', 'seaborn'),
    'reset_modules_order': 'before',
    'first_notebook_cell': None,
    'last_notebook_cell': None,
    'notebook_images': False,
    'pypandoc': False,
    'remove_config_comments': False,
    'show_memory': False,
    'show_signature': True,
    'junit': '',
    'log_level': {'backreference_missing': 'warning'},
    'inspect_global_variables': True,
    'css': _KNOWN_CSS,
    'matplotlib_animations': False,
    'image_srcset': [],
    'default_thumb_file': None,
    'line_numbers': False,
    'nested_sections': True,
    'prefer_full_module': set(),
    'api_usage_ignore': '.*__.*__',
    'show_api_usage': False,
    'copyfile_regex': '',
    'parallel': False
}

Configuration Categories

Core Gallery Settings

Essential configuration for gallery generation:

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

Execution Control

Options controlling example execution:

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

Output Options

Settings for generated output:

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

Advanced Configuration

Advanced customization options:

  • image_scrapers (tuple): Functions for extracting images from code (default: ('matplotlib',))
  • reset_modules (tuple): Modules to reset between example executions (default: ('matplotlib', 'seaborn'))
  • subsection_order (str/callable): Function for ordering gallery subsections
  • within_subsection_order (str/callable): Function for ordering within subsections
  • first_notebook_cell (str): Content for first notebook cell
  • last_notebook_cell (str): Content for last notebook cell

Usage Examples

Basic Gallery Setup

# conf.py
extensions = ['sphinx_gallery.gen_gallery']

sphinx_gallery_conf = {
    'examples_dirs': '../examples',
    'gallery_dirs': 'auto_examples',
    'filename_pattern': '/plot_.*\.py$',
    'ignore_pattern': r'__init__\.py',
}

Advanced Configuration

# conf.py
from sphinx_gallery.sorting import ExplicitOrder

extensions = ['sphinx_gallery.gen_gallery']

sphinx_gallery_conf = {
    'examples_dirs': '../examples',
    'gallery_dirs': 'auto_examples',
    'subsection_order': ExplicitOrder(['basic', 'advanced', 'expert']),
    'show_memory': True,
    'download_all_examples': True,
    'expected_failing_examples': {'plot_broken_example.py'},
    'thumbnail_size': (250, 250),
}

CSS-Only Integration

# conf.py
extensions = ['sphinx_gallery.load_style']

# No sphinx_gallery_conf needed for CSS-only mode

Install with Tessl CLI

npx tessl i tessl/pypi-sphinx-gallery

docs

directives.md

extension-setup.md

index.md

notebooks.md

scrapers.md

sorting.md

utilities.md

tile.json