Getting Started with Sphinx-Gallery#

Creating a basic Gallery#

This section describes how to set up a basic gallery for your examples using the Sphinx extension Sphinx-Gallery, which will do the following:

Automatically generate Sphinx reST out of your .py example files. The rendering of the resulting reST will provide the users with .ipynb (Jupyter notebook) and .py files of each example, which users can download.
Create a gallery with thumbnails for each of these examples (such as the one that scikit-learn uses).

A template repository, with sample example galleries and basic configurations is also available to help you get started.

Note

Working sphinx builders for sphinx_gallery include html, dirhtml and latex.

Overview your project files and folders#

This section describes the general files and structure needed for Sphinx-Gallery to build your examples.

Let’s say your Python project has the following structure:

.
├── doc
│   ├── conf.py
│   ├── index.rst
|   ├── make.bat
│   └── Makefile
├── my_python_module
│   ├── __init__.py
│   └── mod.py
└── examples
    ├── plot_example.py
    ├── example.py
    └── GALLERY_HEADER.rst (or README.[rst/.txt])

doc is the Sphinx ‘source directory’. It contains the Sphinx base configuration files. Default versions of these base files can obtained from executing sphinx-quickstart (more details at Sphinx-quickstart). Sphinx .rst source files are generally also placed here (none included in our example directory structure above) but these are unassociated with Sphinx-Gallery functions.
my_python_module contains the .py files of your Python module. This directory is not required and Sphinx-Gallery can be used for a variety of purposes outside of documenting examples for a package, for example creating a website for a Python tutorial.
examples contains the files used by Sphinx-Gallery to build the gallery.

Sphinx-Gallery expects the examples directory to have a specific structure, which we’ll cover next.

Structure the examples folder#

In order for Sphinx-Gallery to build a gallery from your examples folder, this folder must have the following things:

The gallery header: A file named GALLERY_HEADER.[ext], where [ext] is ‘txt’ or an entry in sphinx_gallery_conf["source_suffix"] (or for backward-compatibility README.[ext]). Default recommendation is GALLERY_HEADER.rst. This file should contain reST to be used as a header for the gallery welcome page, which will also include thumbnails generated from this folder. It must have at least a title. For example:
```
This is my gallery
==================

Below is a gallery of examples
```
Example Python scripts: A collection of Python scripts that will be processed when you build your HTML documentation. For information on how to structure these Python scripts with embedded reST, see Structuring Python scripts for Sphinx-Gallery.
- By default only files prefixed with plot_ will be executed and their outputs captured to incorporate them in the HTML output of the script. Files without that prefix will be only parsed and presented in a rich literate programming fashion, without any output. To change the default file pattern for execution and capture see Parsing and executing examples via matching patterns.
- The output that is captured while executing the .py files and subsequently incorporated into the built documentation can be finely tuned. See Controlling what output is captured.
- You can have sub-directories in your examples directory. These will be included as sub-sections of your gallery. They must contain their own GALLERY_HEADER.[ext] file as well. Note that [ext] can be ‘txt’ or an entry in sphinx_gallery_conf["source_suffix"]. We also support README.[ext] for backward-compatibility.

Warning

The variable name ___ (3 underscores) should never be used in your example Python scripts as it is used as an internal Sphinx-Gallery variable.

Configure and use Sphinx-Gallery#

After Sphinx-Gallery is installed, we must enable and configure it to build with Sphinx.

First, enable Sphinx-Gallery in the Sphinx doc/conf.py file with:

extensions = [
    ...
    'sphinx_gallery.gen_gallery',
    ]

This loads Sphinx-Gallery as one of your extensions, the ellipsis ... represents your other loaded extensions.

Next, create your configuration dictionary for Sphinx-Gallery. Here we will simply set the minimal required configurations. We must set the location of the ‘examples’ directory (containing the gallery header file and our example Python scripts) and the directory to place the output files generated. The path to both of these directories should be relative to the doc/conf.py file.

The following configuration declares the location of the ‘examples’ directory ('example_dirs') to be ../examples and the ‘output’ directory ('gallery_dirs') to be auto_examples:

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

After building your documentation, gallery_dirs will contain the following files and directories:

index.rst - the master document of the gallery containing the gallery header, table of contents tree and thumbnails for each example. It will serve as the welcome page for that gallery.
sg_execution_times.rst - execution time of all example .py files, summarised in table format (original pull request on GitHub).
images - directory containing images produced during execution of the example .py files (more details in Image scrapers) and thumbnail images for the gallery.
A directory for each sub-directory in 'example_dirs'. Within each directory will be the above and below listed files for that ‘sub-gallery’ (aka subsection).

Additionally for each .py file, a file with the following suffix is generated:

.rst - the rendered reST version of the .py file, ready for Sphinx to build.
.ipynb - to enable the user to download a Jupyter notebook version of the example.
.py - to enable the user to download a .py version of the example.
.py.md5 - a md5 hash of the .py file, used to determine if changes have been made to the file and thus if new output files need to be generated.
.codeobj.json - used to identify function names and to which module they belong (more details in Identifying function names in a script)

Additionally, two compressed .zip files containing all the .ipynb and .py files are generated, as well as a root-level sg_execution_times.rst file containing all of the execution times.

For more advanced configuration, see the Configuration page.

Add your gallery to the documentation#

The index.rst file generated for your gallery can be added to the table of contents tree in the main Sphinx doc/index.rst file or embedded in a Sphinx source .rst file with an .. include:: statement.

Build the documentation#

In your Sphinx source directory, (e.g., myproject/doc) execute:

$ make html

This will start the build of your complete documentation. Both the Sphinx-Gallery output files described above and the Sphinx built HTML documentation will be generated. Once a build is completed, all the outputs from your examples will be cached. In the future, only examples that have changed will be re-built.

You should now have a gallery built from your example scripts! For more advanced usage and configuration, check out the Advanced usage page or the Configuration reference.

Note

Sphinx-Gallery may work for non-HTML Sphinx builders but support for this is mostly untested and results may vary.