Advanced Configuration

Here are the personal configurations that you can modify within Sphinx-Gallery.

Manage Multiple galleries

Sphinx-Gallery only supports up to sub-folder level in its gallery directories. This might be a limitation for you. Or you might want to have separate galleries for different purposes, an examples gallery and a tutorials gallery. For this you use in your Sphinx conf.py file a list of directories in the sphinx configuration dictionary:

sphinx_gallery_conf = {
    'examples_dirs'   : ['../examples', '../tutorials'],
    'gallery_dirs'    : ['auto_examples', 'tutorials'],
}

Keep in mind that both lists have to be of the same length.

Building examples matching a pattern

By default, Sphinx-Gallery execute only examples beginning with plot. However, if this naming convention does not suit your project, you can modify this pattern in your Sphinx conf.py. For example:

sphinx_gallery_conf = {
    'filename_pattern'  : '/plot_compute_'
}

will build all examples starting with plot_compute_. The key filename_pattern accepts regular expressions which will be matched with the full path of the example. This is the reason the leading '/' is required. Users are advised to use os.sep instead of '/' if they want to be agnostic to the operating system.

This option is also useful if you want to build only a subset of the examples. For example, you may want to build only one example so that you can link it in the documentation. In that case, you would do:

sphinx_gallery_conf = {
    'filename_pattern' : 'plot_awesome_example.py'
}

Here, one should escape the dot '\.' as otherwise python regular expressions matches any character. Nevertheless, as one is targeting a specific file, it is most certainly going to match the dot in the filename.

Similarly, to build only examples in a specific directory, you can do:

sphinx_gallery_conf = {
    'filename_pattern' : '/directory/plot_'
}

Alternatively, you can skip some examples. For example, to skip building examples starting with plot_long_examples_, you would do:

sphinx_gallery_conf = {
    'filename_pattern' : '/plot_(?!long_examples)'
}

As the patterns are parsed as regular expressions, users are advised to consult the regular expressions module for more details.

Linking to documentation

Sphinx-Gallery enables you to add hyperlinks in your example scripts so that you can link the used functions to their matching online documentation. As such code snippets within the gallery appear like this

y = np.sin(x)

Have a look at this in full action in our example Sphinx-Gallery introduction.

To make this work in your documentation you need to include to the configuration dictionary within your Sphinx conf.py file :

sphinx_gallery_conf = {
    'reference_url':  {
             # The module you locally document uses a None
            'sphinx_gallery': None,

            # External python modules use their documentation websites
            'matplotlib': 'http://matplotlib.org',
            'numpy': 'http://docs.scipy.org/doc/numpy-1.9.1'}
    }

References to examples (backreferences)

Sphinx-Gallery enables you, when documenting your modules, to reference to the examples that use a particular function. For example if we are documenting the numpy.exp function its possible to embed a small gallery of examples that is specific to this function and looks like this:

Examples using numpy.exp

For such behavior to be available, you have to activate it in your Sphinx-Gallery configuration conf.py file with:

sphinx_gallery_conf = {
    # directory where function granular galleries are stored
    'backreferences_dir'  : 'gen_modules/backreferences',

    # Modules for which function level galleries are created.  In
    # this case sphinx_gallery and numpy in a tuple of strings.
    'doc_module'          : ('sphinx_gallery', 'numpy')}

The path you specify in backreferences_dir, here we choose gen_modules/backreferences will get populated with ReStructuredText files, each of which contains a reduced version of the gallery specific to every function used across all the examples galleries and belonging to the modules listed in doc_module. Keep in mind that the path set in backreferences_dir is relative to the conf.py file.

Then within your sphinx documentation .rst files you write these lines to include this reduced version of the Gallery, which has examples in use of a specific function, in this case numpy.exp:

.. include:: gen_modules/backreferences/numpy.exp.examples
.. raw:: html

    <div style='clear:both'></div>

The include directive takes a path relative to the rst file it is called from. In the case of this documentation file (which is in the same directory as conf.py) we directly use the path declared in backreferences_dir followed by the function whose examples we want to show and the file has the .examples extension.

Using a custom default thumbnail image

In case you want to use your own image for the thumbnail of examples that do not generate any plot, you can specify it by editing your Sphinx conf.py file. You need to add to the configuration dictionary a key called default_thumb_file. For example:

sphinx_gallery_conf = {
    'default_thumb_file'     : 'path/to/thumb/file.png'}}

Choosing the thumbnail image from multiple figures

For examples that generate multiple figures, the default behavior will use the first figure created in each as the thumbnail image displayed in the gallery. To change the thumbnail image to a figure generated later in an example script, add a comment to the example script to specify the number of the figure you would like to use as the thumbnail. For example, to use the 2nd figure created as the thumbnail:

# sphinx_gallery_thumbnail_number = 2

The default behavior is sphinx_gallery_thumbnail_number = 1. See Choosing the thumbnail figure for an example of this functionality.