Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Sphinx extension to automatically generate an examples gallery

Project Description

A Sphinx extension that builds an HTML version of any Python script and puts it into an examples gallery.

It is extracted from the scikit-learn project and aims to be an independent general purpose extension.

Getting the package

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 dependencies are:

  • Sphinx
  • Matplotlib
  • Pillow

Sphinx-Gallery has also support for packages like:

  • Seaborn
  • Mayavi

Install as developer

You can get the latest development source from our Github repository. You need setuptools installed in your system to install Sphinx-Gallery.

You will also need to install the dependencies listed above and pytest

To install everything do:

$ git clone
$ cd sphinx-gallery
$ pip install -r requirements.txt
$ python develop

In addition, you will need the following dependencies to build the documentation:

  • Scipy
  • Seaborn

Set up your project

Let’s say your Python project looks like this:

├── doc
│   ├──
│   ├── index.rst
│   └── Makefile
├── py_module
│   ├──
│   └──
└── examples
    └── README.txt

Your Python module is on py_module, examples on how to use it are in examples and the doc folder hold the base documentation structure you get from executing sphinx-quickstart.

To get Sphinx-Gallery into your project we have to extend the Sphinx doc/ file with:

extensions = [

This is to load Sphinx-Gallery as one of your extensions, the ellipsis ... is to represent your other loaded extensions.

Now to declare your project structure, we add a configuration dictionary for Sphinx-Gallery. The examples directory ../examples is declared with a relative path from the file location:

sphinx_gallery_conf = {
    # path to your examples scripts
    'examples_dirs' : '../examples',
    # path where to save gallery generated examples
    'gallery_dirs'  : 'auto_examples'}

The gallery_dirs is the folder where Sphinx-Gallery will store the converted Python scripts into rst files that Sphinx will process into HTML.

The structure of the examples folder

There are some extra instructions on how to present your examples to Sphinx-Gallery.

  • A mandatory README.txt file with rst syntax to introduce your gallery
  • files: Python scripts that have to be executed and output a plot that will be presented in your gallery
  • files: Python scripts that will not be executed but will be presented in the gallery

All the Python scripts in the examples folder need to have a docstring. Written in rst syntax as it is used in the generated file for the example gallery.

You can have sub-folders in your examples directory, those will be processed by the gallery extension and presented in the gallery, as long as they also have a README.txt file. Sub-folders have to respect the same structure examples folder.

If these instructions are not clear enough, this package uses itself, to generated its own example gallery. So check the directory structure and the contents of the files.

Building the documentation locally

In your sphinx documentation directory, doc execute:

$ make html

This will start the build of your complete documentation including the examples gallery. Once documentation is build, our extension will have generated an auto_examples directory and populated it with rst files containing the gallery and each example. Sphinx gives this files its regular processing and you can enjoy your generated gallery under the same path. That means you will find the gallery in the path:


that you can open under your favorite browser.

Once a build is completed all your examples outputs are in cache. Thus future rebuilds of your project will not trigger the full execution of all your examples saving your a large amount of time on each iteration. Only examples which have changed (comparison evaluated by md5sum) are built again.

Extending your Makefile

Once your gallery is working you might need remove completely all generated files by sphinx-gallery to have a clean build, or you might want to build the gallery without running the examples files. For this you need to extend your Makefile with:

        rm -rf $(BUILDDIR)/*
        rm -rf auto_examples/

        $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
        @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

Remember that for Makefile white space is significant and the indentation are tabs and not spaces

Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
sphinx-gallery-0.1.13.tar.gz (72.4 kB) Copy SHA256 Checksum SHA256 Source Oct 8, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting