Sphinx-Gallery

Sphinx-Gallery is a Sphinx extension that turns a directory of plain Python scripts into a polished, browsable example gallery inside a project’s documentation. It runs each script during the documentation build, captures the figures, printed output, and execution time, and generates reStructuredText pages that Sphinx renders alongside the rest of the docs — no separate hosting or manual screenshotting required.

It originated in the scientific Python ecosystem and now powers the example galleries for scikit-learn, Matplotlib, PyTorch tutorials, NetworkX, MNE-Python, PyVista, and dozens of other projects. Beyond static HTML, it can emit downloadable .py and Jupyter notebook versions of every example, wire up Binder and JupyterLite so visitors can run examples live in the browser, and scrape output from Matplotlib, Plotly, PyVista, and other plotting libraries automatically.

Because it hooks into Sphinx’s own build lifecycle rather than requiring a separate CLI or pipeline, adding it to an existing documentation project is a matter of listing it in conf.py’s extensions and pointing sphinx_gallery_conf at an examples directory.

What You Get

• Automatic execution of example scripts during the docs build, with generated reST pages, thumbnails, and a gallery index — no hand-written example pages to maintain
• Output scraping for Matplotlib, Plotly, PyVista, and other plotting libraries, so rendered figures are embedded next to the code that produced them
• Per-example downloads: the original .py script and an auto-converted Jupyter notebook (.ipynb) for every gallery entry
• Binder and JupyterLite integration so visitors can run and edit examples directly in the browser without installing anything
• Cross-referencing via backreferences: functions and classes get a ‘used in these examples’ list generated automatically from the gallery
• Execution cost tracking (time and memory) per example, with configurable ordering by cost, filename, or a custom key

Common Use Cases

• Scientific/numerical Python libraries (plotting, machine learning, imaging) documenting their API through runnable, visual examples rather than static prose
• Maintainers migrating a hand-maintained ‘examples/’ folder of scripts into a searchable, browsable documentation gallery with almost no extra authoring
• Projects that want downloadable notebook versions of their examples without maintaining .py and .ipynb copies separately
• Documentation sites that need runnable-in-browser examples (via Binder/JupyterLite) for users without a local Python environment

Under The Hood

Architecture Sphinx-Gallery attaches to Sphinx through a single setup(app) entry point in gen_gallery.py that registers config values, directives, and build-time event handlers. The core pipeline runs in two coordinated stages: gen_gallery.py orchestrates the overall build (config validation via GalleryConfig, discovering example directories, coordinating parallel execution, generating the toctree and CSS/JS assets), while gen_rst.py does the per-file work of executing each script in a fresh namespace, capturing stdout and exceptions, and writing the resulting reST. Supporting modules are cleanly separated by concern — py_source_parser.py and block_parser.py split scripts into code/text blocks, scrapers.py pulls rendered figures out of whichever plotting library produced them, backreferences.py builds the reverse-reference index, notebook.py converts scripts to .ipynb, and interactive_example.py wires up Binder/JupyterLite. Changing the core GalleryConfig contract would ripple through nearly every module since each pass reads from the same shared config object.

Tech Stack Pure Python (95% of the codebase), built on Sphinx 6+ and docutils for document generation, with Pillow for image handling. Optional extras layer in matplotlib, plotly, joblib (for parallel example execution), jupyterlite-sphinx (for in-browser notebooks), sphinxcontrib-video (for animation embeds), and memory-profiler (for per-example memory tracking) — each gated behind its own optional-dependencies group in pyproject.toml so the core install stays lean. Packaging uses setuptools with setuptools-scm for version derivation from git tags, and the CLI entry point sphinx_gallery_py2jupyter is exposed via project.scripts.

Code Quality The project has an extensive test suite under sphinx_gallery/tests/, covering the RST/block parsers, gallery generation, scrapers, notebook conversion, and a test_full.py integration suite that runs a full ‘tinybuild’ documentation build end to end — though that suite skips silently at module level unless optional dependencies like jupyterlite_sphinx, joblib, and a working matplotlib.animation writer are installed, a documented trap the maintainers call out explicitly in their own contributor notes. Linting runs through pre-commit with ruff (import sorting plus a deliberately narrow rule set), codespell, yamllint, sphinx-lint, and the ty type checker, with CI split across GitHub Actions, Azure Pipelines, and CircleCI.

What Makes It Unique Unlike general documentation generators, Sphinx-Gallery treats examples as executable source of truth rather than static text: every gallery entry is verified to actually run as part of every documentation build, which surfaces broken examples as build failures rather than stale prose. Its scraper abstraction lets it capture rendered output from multiple, unrelated plotting libraries through a common interface, and its adoption across the scientific Python stack (scikit-learn, Matplotlib, PyTorch, NetworkX, MNE-Python) has made its generated gallery layout something of a de facto visual convention for that ecosystem.