Welcome to Sphinx-Gallery’s documentation!¶
Sphinx-Gallery
is a Sphinx extension that builds an HTML
gallery of examples from any set of Python scripts.

The code of the project is on Github: Sphinx-Gallery
Features of Sphinx-Gallery¶
Creating a basic Gallery by automatically running Python files, capturing outputs + figures, and rendering them into rST files ready for Sphinx when you build the documentation. Learn how to Overview your project files and folders
Embed rST in your example Python files, allowing you to interweave narrative-like content with code that generates plots in your documentation. Sphinx-Gallery also automatically generates a Jupyter Notebook for each your example page.
Add mini-galleries for API documentation. Sphinx-Gallery can generate mini-galleries listing all examples that use a particular function/method/etc.
Add intersphinx links to your examples. Sphinx-Gallery can automatically add links to API documentation for functions/methods/classes that are used in your examples (for any Python module that uses intersphinx).
Manage multiple galleries to create and embed galleries for several folders of examples.
Installation¶
Install via pip
¶
You can do a direct install via pip by using:
$ pip install sphinx-gallery
Sphinx-Gallery will not manage its dependencies when installing, thus you are required to install them manually. Our minimal dependency is:
Sphinx >= 1.8.3
Sphinx-Gallery has also support for packages like:
Matplotlib
Seaborn
Mayavi
For much of this functionality, you will need pillow
. We also recommend
installing system optipng
binaries to reduce the file sizes of the
generated PNG files.
Install as a Sphinx-Gallery developer¶
You can get the latest development source from our Github repository. You need
setuptools
installed in your system to install Sphinx-Gallery. For example,
you can do:
$ git clone https://github.com/sphinx-gallery/sphinx-gallery
$ cd sphinx-gallery
$ pip install -r dev-requirements.txt
$ pip install -e .
Citation¶
If you would like to cite Sphinx-Gallery you can do so using our Zenodo deposit.
Sphinx-Gallery Show: Gallery of Examples¶
Using Sphinx Gallery
- Getting Started with Sphinx-Gallery
- How to structure your Python scripts for Sphinx-Gallery
- Configuration
- List of config options
- Removing warnings
- Manage multiple galleries
- Parsing and executing examples via matching patterns
- Rerunning stale examples
- Passing command line arguments to example scripts
- Sorting gallery subsections
- Sorting gallery examples
- Add intersphinx links to your examples
- Add mini-galleries for API documentation
- Using a custom default thumbnail
- Adding line numbers to examples
- Removing config comments
- Add your own first and last notebook cell
- Adding images to notebooks
- Using pypandoc to convert rST to markdown
- Using JUnit XML files
- Setting log level
- Disabling download button of all scripts
- Choosing the thumbnail image
- Providing an image for the thumbnail image
- Generate Binder links for gallery notebooks (experimental)
- Building without executing examples
- Compressing images
- Image scrapers
- Resetting modules
- Dealing with failing Gallery example scripts
- Setting gallery thumbnail size
- Minimal reported time
- Showing memory consumption
- Show signature
- Controlling what output is captured
- Who uses Sphinx-Gallery
Advanced usage and information
Example galleries
API and developer reference
- Sphinx-Gallery API Reference
- Sphinx Gallery
- sphinx_gallery.gen_gallery
- sphinx_gallery.backreferences
- sphinx_gallery.gen_rst
- sphinx_gallery.scrapers
- sphinx_gallery.py_source_parser
- sphinx_gallery.docs_resolv
- sphinx_gallery.notebook
- sphinx_gallery.downloads
- sphinx_gallery.sorting
- sphinx_gallery.binder
- sphinx_gallery.directives
- Utilities
- sphinx_gallery.utils.optipng
- Change Log
- Fork Sphinx-Gallery on Github