Sphinx-Gallery

Warnings

• breaking Support for Python 3.8 has been dropped. Sphinx-Gallery now requires Python >=3.10.
  Fix: Upgrade your Python environment to version 3.10 or newer. If you need Python 3.8 support, use sphinx-gallery<0.20.0.
• breaking Support for Python 3.8 and Sphinx 4 has been dropped. Sphinx-Gallery now requires Python >=3.9 and Sphinx >=5.
  Fix: Ensure your environment uses Python 3.9+ and Sphinx 5+. If upgrading Sphinx is not an option, use sphinx-gallery<0.17.0.
• breaking Due to Sphinx 7.3.0+ caching changes, certain `sphinx_gallery_conf` options that accept callables (e.g., `reset_argv`, `FileNameSortKey`, `notebook_modification_function`) must now be provided as fully qualified name *strings* (e.g., `'path.to.my_function'`) instead of instantiated classes or direct callables. Passing objects with unstable `__repr__` can force unnecessary rebuilds.
  Fix: Update your `conf.py` to pass string references for these configuration options instead of direct callable objects.
• breaking Support for Python 3.7 was dropped. Additionally, `Pillow` was added as a required dependency.
  Fix: Upgrade your Python environment to 3.8 or newer. Ensure `Pillow` is installed (`pip install Pillow`). If you need Python 3.7, use sphinx-gallery<0.15.0.

Install

• pip install sphinx-gallery Install latest version

Imports

• sphinx_gallery.gen_gallery

  extensions = ['sphinx_gallery.gen_gallery']

  Sphinx-Gallery is typically enabled by adding its module path to the 'extensions' list in Sphinx's `conf.py` file, rather than importing specific symbols for direct use within `conf.py`.

Quickstart

To integrate Sphinx-Gallery, first enable it by adding `'sphinx_gallery.gen_gallery'` to the `extensions` list in your Sphinx `conf.py` file. Then, define the `sphinx_gallery_conf` dictionary to specify the input directory for your example scripts (`examples_dirs`) and the output directory for the generated gallery (`gallery_dirs`). The paths should be relative to `conf.py`.

import os

# conf.py example
extensions = [
    # ... other extensions
    'sphinx_gallery.gen_gallery',
]

# Path to the directory containing example scripts, relative to conf.py
examples_dir = os.path.join(os.path.dirname(__file__), '../examples')

# Path to where Sphinx-Gallery should save its generated output, relative to conf.py
gallery_dir = 'auto_examples'

sphinx_gallery_conf = {
    'examples_dirs': examples_dir,
    'gallery_dirs': gallery_dir,
    'plot_gallery': 'True', # Set to False to disable example execution
    'backreferences_dir': 'gen_modules/backreferences' # For mini-galleries
}