Configuration

Configuration and customization of sphinx-gallery is done primarily with a dictionary specified in your conf.py file. A list of the possible keys are listed below and explained in greater detail in subsequent sections.

List of config options

Most sphinx-gallery configuration options are set in the Sphinx conf.py file:

Some options can also be set or overridden on a file-by-file basis:

See also Removing config comments to hide these comments from the rendered examples.

Some options can be set during the build execution step, e.g. using a Makefile:

And some things can be tweaked directly in CSS:

Removing warnings

To prevent warnings from being captured and included in your built documentation, you can use the package warnings in the conf.py file. For example, to remove the specific Matplotlib agg warning, you can add:

import warnings

warnings.filterwarnings("ignore", category=UserWarning,
                        message='Matplotlib is currently using agg, which is a'
                                ' non-GUI backend, so cannot show the figure.')

to your conf.py file.

Note that the above Matplotlib warning is removed by default.

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.

Note

If your examples take a long time to run, consider looking at the execution times file that is generated for each gallery dir (as long as any examples were actually executed in that directory during the build).

Parsing and executing examples via matching patterns

By default, Sphinx-Gallery will parse and add all files with a .py extension to the gallery, but only execute files beginning with plot_. These behaviors are controlled by the ignore_pattern and filename_pattern entries, which have the default values:

sphinx_gallery_conf = {
    ...
    'filename_pattern': '/plot_',
    'ignore_pattern': r'__init__\.py',
}

To omit some files from the gallery entirely (i.e., not execute, parse, or add them), you can change the ignore_pattern option. To choose which of the parsed and added Python scripts are actually executed, you can modify filename_pattern. For example:

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

will build all examples starting with plot_compute_. The key filename_pattern (and ignore_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 re.escape(os.sep) instead of '/' if they want to be agnostic to the operating system.

The filename_pattern 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': r'plot_awesome_example\.py',
}

Here, one should escape the dot r'\.' as otherwise python regular expressions matches any character. Nevertheless, as one is targeting a specific file, it would match the dot in the filename even without this escape character.

Note

Sphinx-gallery only re-runs examples that have changed (according to their md5 hash). You can delete the associated MD5 files (e.g., ./auto_examples/plot_awesome_example.py.md5) to force a rebuild if you have not changed the example itself between subsequent sphinx calls.

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

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

Alternatively, you can skip executing 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.

Note

Remember that Sphinx allows overriding conf.py values from the command line, so you can for example build a single example directly via something like:

$ sphinx-build -D sphinx_gallery_conf.filename_pattern=plot_specific_example\.py ...

Passing command line arguments to example scripts

By default, Sphinx-Gallery will not pass any command line arguments to example scripts. By setting the reset_argv option, it is possible to change this behavior and pass command line arguments to example scripts. reset_argv needs to be a Callable that accepts the gallery_conf and script_vars dictionaries as input and returns a list of strings that are passed as additional command line arguments to the interpreter.

An example could be:

class ResetArgv:
    def __repr__(self):
        return 'ResetArgv'

    def __call__(self, sphinx_gallery_conf, script_vars):
        if script_vars['src_file'] == 'example1.py':
            return ['-a', '1']
        elif script_vars['src_file'] == 'example2.py':
            return ['-a', '2']

which is included in the configuration dictionary as:

sphinx_gallery_conf = {
    ...
    'reset_argv': ResetArgv(),
}

which is then used by Sphinx-Gallery as:

import sys
sys.argv[0] = script_vars['src_file']
sys.argv[1:] = gallery_conf['reset_argv'](gallery_conf, script_vars)

Add mini-galleries for API documentation

When documenting a given function/class, Sphinx-Gallery enables you to link to any examples that either:

  1. Use the function/instantiate the class in the code.

  2. Refer to that function/class using sphinx markup :func:/:class: in a documentation block.

The former is useful for auto-documenting functions that are used and classes that are explicitly instantiated. The latter is useful for classes that are typically implicitly returned rather than explicitly instantiated (e.g., matplotlib.axes.Axes which is most often instantiated only indirectly within function calls).

For example, we can embed a small gallery of all examples that use or refer to numpy.exp, which 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/class granular galleries are stored
    'backreferences_dir'  : 'gen_modules/backreferences',

    # Modules for which function/class 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 be populated with ReStructuredText files. Each .rst file will contain a reduced version of the gallery specific to every function/class that is used across all the examples and belonging to the modules listed in doc_module. backreferences_dir should be a string or pathlib.Path object that is relative to the conf.py file, or None. It is None by default.

Within your sphinx documentation .rst files, you can use easily add this reduced version of the Gallery. For example, the rst below adds the reduced version of the Gallery for numpy.exp, which includes all examples that use the specific function numpy.exp:

.. minigallery:: numpy.exp
    :add-heading:

The add-heading option adds a heading for the mini-gallery, which will be a default generated message if no string is provided as an argument. The example mini-gallery shown above uses the default heading. The level of the heading defaults to ^, but can be changed using the heading-level option, which accepts a single character (e.g., -).

You can also list multiple items, separated by spaces, which will merge all examples into a single mini-gallery, e.g.:

.. minigallery:: numpy.exp numpy.sin
    :add-heading: Mini-gallery using ``numpy.exp`` or ``numpy.sin``
    :heading-level: -

For such a mini-gallery, specifying a custom heading message is recommended because the default message is vague: “Examples of one of multiple objects”.

Toggling global variable inspection

By default, Sphinx-gallery will inspect global variables (and code objects) at the end of each code block to try to find classes of variables and method calls. It also tries to find methods called on classes. For example, this code:

lst = [1, 2]
fig, ax = plt.subplots()
ax.plot(lst)

should end up with the following links (assuming intersphinx is set up properly):

However, this feature might not work properly in all instances. Moreover, if variable names get reused in the same script to refer to different classes, it will break.

To disable this global variable introspection, you can use the configuration key:

sphinx_gallery_conf = {
    ...
    'inspect_global_variables'  : False,
}

Using a custom default thumbnail

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',
}

Adding line numbers to examples

Line numbers can be displayed in listings by adding the global line_numbers setting:

sphinx_gallery_conf = {
    ...
    'line_numbers': True,
}

or by adding a comment to the example script, which overrides any global setting:

# sphinx_gallery_line_numbers = True

Removing config comments

Some configurations can be done on a file-by-file basis by adding a special comment with the pattern # sphinx_gallery_config = value to the example source files. By default, the source files are parsed as is and thus the comment will appear in the example.

To remove the comment from the rendered example set the option:

sphinx_gallery_conf = {
    ...
    'remove_config_comments': True,
}

This only removes configuration comments from code blocks, not from text blocks. However, note that technically, configuration comments will work when put in either code blocks or text blocks.

Add your own first and last notebook cell

Sphinx-Gallery allows you to add your own first and/or last cell to every generated notebook. Adding a first cell can be useful for including code that is required to run properly in the notebook, but not in a .py file. By default, the following first cell is added to each notebook:

.. code-block:: ipython

%matplotlib inline

Adding a last cell can be useful for performing a desired action such as reporting on the user’s environment. By default no last cell is added.

You can choose whatever text you like by modifying the first_notebook_cell and last_notebook_cell configuration parameters. For example, the gallery of this documentation adds the following first cell:

.. code-block:: ipython

# This cell is added by sphinx-gallery # It can be customized to whatever you like %matplotlib inline

Which is achieved by the following configuration:

sphinx_gallery_conf = {
    ...
    'first_notebook_cell': ("# This cell is added by sphinx-gallery\n"
                            "# It can be customized to whatever you like\n"
                            "%matplotlib inline")
}

A last cell may be added similarly by setting the last_notebook_cell parameter:

sphinx_gallery_conf = {
    ...
    'first_notebook_cell': ("# This cell is added by sphinx-gallery\n"
                            "# It can be customized to whatever you like\n"
                            "%matplotlib inline"),
    'last_notebook_cell': "# This is the last cell",
}

If the value of first_notebook_cell or last_notebook_cell is set to None, then no extra first or last cell will be added to the notebook.

Adding images to notebooks

When notebooks are produced, by default (notebook_images = False) image paths from the image directive in rST documentation blocks (not images generated fom code) are included in markdown using their original paths. This includes paths to images expected to be present on the local filesystem which is unlikely to be the case for those downloading the notebook.

By setting notebook_images = True, images will be embedded in the generated notebooks via Base64-encoded data URIs. As inclusion of images via data URIs can significantly increase size of the notebook, it’s suggested this only be used when small images are used throughout galleries.

An alternative is to instead provide a prefix string that’ll be used for images e.g. the root URL of where your documentation is hosted. So for example the following configuration:

sphinx_gallery_conf = {
    ...
    'examples_dirs': ['../examples'],
    'gallery_dirs': ['auto_examples'],
    ...
    'notebook_images': 'https://project.example.com/en/latest/',
    ...
}

with an example image directive in an rST documentation block being:

.. image:: ../_static/example.jpg
    :alt: An example image

The image will be added to the generated notebook pointing to the source URL https://project.example.com/en/latest/_static/example.jpg. Note the image path in the rST examples above is a relative path, therefore the URL doesn’t contain auto_examples as ../ moved up a directory to the documentation source directory. Both relative and absolute (from source directory) paths are supported; so in the example above /_static/example.jpg would have resulted in the same URL being produced.

Note that the prefix is applied directly, so a trailing / should be included in the prefix if it’s required.

Tip

If building multiple versions of your documentation on a hosted service and using prefix, consider using sphinx build -D command line option to ensure links point to the correct version. For example:

sphinx-build \
    -b html \
    -D sphinx_gallery_conf.notebook_images="https://project.example.com/docs/${VERSION}/" \
    source_dir build_dir

Using pypandoc to convert rST to markdown

Sphinx-Gallery can use pypandoc (if installed) to convert rST text blocks to markdown for the iPython notebooks (.ipynb files) generated for each example. These are made available for download, along with the raw .py version, at the bottom of each example.

The Sphinx-Gallery rST to markdown converter has limited support for more complex rST syntax. If your examples have more complex rST, pypandoc may produce better results. By default, the ‘pypandoc’ configuration is set to False and pypandoc is not used.

To use pypandoc you can set:

sphinx_gallery_conf = {
    ...
    'pypandoc': True,
}

You can also use pandoc options by setting the pypandoc.convert_text() parameters extra_args and filters. To use these parameters, set the ‘pypandoc’ configuration to be a dictionary of keyword argument(s):

sphinx_gallery_conf = {
    ...
    'pypandoc': {'extra_args': ['--mathjax',],
                 'filters': ['pandoc-citeproc',],
}

Warning

Certain pandoc options may result in undesirable effects. Use with caution.

Using JUnit XML files

Sphinx-Gallery can create a JUnit XML file of your example run times, successes, and failures. To create a file named e.g. junit-result.xml in the /build output directory, set the configuration key (path is relative to the HTML output directory):

sphinx_gallery_conf = {
    ...
    'junit': '../test-results/sphinx-gallery/junit.xml',
}

By default, JUnit XML file generation is disabled (by setting 'junit': ''). JUnit XML files are useful for example on CircleCI builds, where you can add a line like this to get a summary of your example run times in the CircleCI GUI (which will parse the file path doc/_build/test-results/sphinx-gallery/junit.xml and infer the tests came from sphinx-gallery based on the nested subdirectory name):

- store_test_results:
    path: doc/_build/test-results
- store_artifacts:
    path: doc/_build/test-results

For more information on CircleCI integration, peruse the related CircleCI doc and blog post.

Setting log level

Sphinx-Gallery logs output at several stages. Warnings can be generated for code that requires case sensitivity (e.g., plt.subplot and plt.Subplot) when building docs on a filesystem that does not support case sensitive naming (e.g., Windows). In this case, by default a logger.warning is emitted, which will lead to a build failure when buidling with -W. The log level can be set with:

sphinx_gallery_conf = {
    ...
    'log_level': {'backreference_missing': 'warning'},
}

The only valid key currently is backreference_missing. The valid values are 'debug', 'info', 'warning', and 'error'.

Disabling download button of all scripts

By default Sphinx-Gallery collects all python scripts and all Jupyter notebooks from each gallery into zip files which are made available for download at the bottom of each gallery. To disable this behavior add to the configuration dictionary in your conf.py file:

sphinx_gallery_conf = {
    ...
    'download_all_examples': False,
}

Choosing the thumbnail image

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.

Providing a figure for the thumbnail image

An arbitrary image can be provided to serve as a thumbnail image. To provide a figure for the thumbnail image, add a comment to the example script to specify the path to the figure you would like to use as the thumbnail. For example, the following defines that the figure demo.png in the folder _static/ should be used to create the thumbnail:

# sphinx_gallery_thumbnail_path = '_static/demo.png'

Note that sphinx_gallery_thumbnail_number overrules sphinx_gallery_thumbnail_path. See Providing a figure for the thumbnail image for an example of this functionality.

Building without executing examples

Sphinx-Gallery can parse all your examples and build the gallery without executing any of the scripts. This is just for speed visualization processes of the gallery and the size it takes your website to display, or any use you can imagine for it. To achieve this you need to pass the no plot option in the build process by modifying your Makefile with:

html-noplot:
    $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
    @echo
    @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.

Alternatively, you can add the plot_gallery option to the sphinx_gallery_conf dictionary inside your conf.py to have it as a default:

sphinx_gallery_conf = {
    ...
    'plot_gallery': 'False',
}

The highest precedence is always given to the -D flag of the sphinx-build command.

Compressing images

When writing PNG files (the default scraper format), sphinx-gallery can be configured to use optipng to optimize the PNG file sizes. Typically this yields roughly a 50% reduction in file sizes, thus reducing the loading time of galleries. However, it can increase build time. The allowed values are 'images' and 'thumbnails', or a tuple/list (to optimize both), such as:

sphinx_gallery_conf = {
    ...
    'compress_images': ('images', 'thumbnails'),
}

The default is () (no optimization) and a warning will be emitted if optimization is requested but optipng is not available. You can also pass additional command-line options (starting with '-'), for example to optimize less but speed up the build time you could do:

sphinx_gallery_conf = {
    ...
    'compress_images': ('images', 'thumbnails', '-o1'),
}

See $ optipng --help for a complete list of options.

Image scrapers

Image scrapers are plugins that allow Sphinx-gallery to detect images produced during execution of your examples, and then embed them into documentation. Scrapers can be activated by appending scraper names to the 'image_scrapers' tuple in your Sphinx-gallery configuration. For example, to scrape both matplotlib and Mayavi images you can do:

sphinx_gallery_conf = {
    ...
    'image_scrapers': ('matplotlib', 'mayavi'),
}

The default value is 'image_scrapers': ('matplotlib',) which only scrapes Matplotlib images. Note that this includes any images produced by packages that are based on Matplotlib, for example Seaborn or Yellowbrick. If you want to embed matplotlib.animation.Animations as animations rather than a single static image of the animation figure, you should add:

sphinx_gallery_conf = {
    ...
    'matplotlib_animations': True,
}

HTML embedding options can be changed by setting rcParams['animation.html'] and related options in your matplotlib rcParams. It’s also recommended to ensure that “imagemagick” is available as a writer, which you can check with matplotlib.animation.ImageMagickWriter.isAvailable(). The FFmpeg writer in some light testing did not work as well for creating GIF thumbnails for the gallery pages.

The following scrapers are supported:

  • matplotlib

    Sphinx-gallery maintains a scraper for matplotlib figures via the string 'matplotlib'.

  • Mayavi

    Sphinx-gallery maintains a scraper for Mayavi figures via the string 'mayavi'.

  • PyVista

    PyVista maintains a scraper (for PyVista >= 0.20.3) enabled by the string 'pyvista'.

  • PyGMT

    See their website for more information on how to integrate with Sphinx-Gallery.

It is possible to write custom scrapers for images generated by packages outside of those listed above. This is accomplished by writing your own Python function to define how to detect and retrieve images produced by an arbitrary package. For instructions, see Write a custom image scraper. If you come up with an implementation that would be useful for general use (e.g., a custom scraper for a plotting library) feel free to add it to the list above (see discussion here)!

Resetting modules

Often you wish to “reset” the behavior of your visualization packages in order to ensure that any changes made to plotting behavior in one example do not propagate to the other examples.

By default, before each example file executes, Sphinx-gallery will reset matplotlib (by using matplotlib.pyplot.rcdefaults()) and seaborn (by trying to unload the module from sys.modules). This is equivalent to the following configuration:

sphinx_gallery_conf = {
    ...
    'reset_modules': ('matplotlib', 'seaborn'),
}

Currently, Sphinx-gallery natively supports resetting matplotlib and seaborn. However, you can also add your own custom function to this tuple in order to define resetting behavior for other visualization libraries.

To do so, follow the instructions in Define resetting behavior (e.g., for custom libraries).

Minimal reported time

By default, Sphinx-gallery logs and embeds in the html output the time it took to run each script. If the majority of your examples runs quickly, you may not need this information.

The min_reported_time parameter can be set to a number of seconds. The duration of scripts that ran faster than that amount will not be logged nor embedded in the html output.

Showing memory consumption

Sphinx-Gallery can use memory_profiler, if installed, to report the peak memory during the run of an example. After installing memory_profiler, you can do:

sphinx_gallery_conf = {
    ...
    'show_memory': True,
}

It’s also possible to use your own custom memory reporter, for example if you would rather see the GPU memory. In that case, show_memory must be a callable that takes a single function to call (i.e., one generated internally to run an individual script code block), and returns a two-element tuple containing:

  1. The memory used in MiB while running the function, and

  2. The function output

A version of this that would always report 0 memory used would be:

sphinx_gallery_conf = {
    ...
    'show_memory': lambda func: (0., func()),
}

Controlling what output is captured

Note

Configure capture_repr to be an empty tuple (i.e., capture_repr: ()) to return to the output capturing behaviour prior to release v0.5.0.

The capture_repr configuration allows the user to control what output is captured, while executing the example .py files, and subsequently incorporated into the built documentation. Data directed to standard output is always captured. The value of the last statement of each code block, if it is an expression, can also be captured. This can be done by providing the name of the ‘representation’ method to be captured in the capture_repr tuple, in order of preference. The representation methods currently supported are:

  • __repr__ - returns the official string representation of an object. This is what is returned when your Python shell evaluates an expression.

  • __str__ - returns a string containing a nicely printable representation of an object. This is what is used when you print() an object or pass it to format().

  • _repr_html_ - returns a HTML version of the object. This method is only present in some objects, for example, pandas dataframes.

The default setting is:

sphinx_gallery_conf = {
    ...
    'capture_repr': ('_repr_html_', '__repr__'),
}

With the default setting Sphinx-Gallery would first attempt to capture the _repr_html_ of the last statement of a code block, if it is an expression. If this method does not exist for the expression, the second ‘representation’ method in the tuple, __repr__, would be captured. If the __repr__ also does not exist (unlikely for non-user defined objects), nothing would be captured. Data directed to standard output is always captured.

To capture only data directed to standard output, configure 'capture_repr' to be an empty tuple: 'capture_repr': (). This will imitate the behaviour of Sphinx-Gallery prior to v0.5.0.

From another perspective, take for example the following code block:

print('Hello world')
a=2
a   # this is an expression

'Hello world' would be captured for every capture_repr setting as this is directed to standard output. Further,

  • if capture_repr is an empty tuple, nothing else would be captured.

  • if capture_repr is ('__repr__'), 2 would also be captured.

  • if capture_repr is ('_repr_html_', '__repr__') (the default) Sphinx-Gallery would first attempt to capture _repr_html_. Since this does not exist for a, it will then attempt to capture __repr__. The __repr__ method does exist for a, thus 2 would be also captured in this case.

Matplotlib note: if the 'capture_repr' tuple includes '__repr__' and/or '__str__', code blocks which have a Matplotlib function call as the last expression will generally produce a yellow output box in the built documentation, as well as the figure. This is because matplotlib function calls usually return something as well as creating/amending the plot in standard output. For example, matplotlib.plot() returns a list of Line2D objects representing the plotted data. This list has a __repr__ and a __str__ method which would thus be captured. You can prevent this by:

  • assigning the (last) plotting function to a temporary variable. For example:

    import matplotlib.pyplot as plt
    
    _ = plt.plot([1, 2, 3, 4], [1, 4, 9, 16])
    
  • add plt.show() (which does not return anything) to the end of your code block. For example:

    import matplotlib.pyplot as plt
    
    plt.plot([1, 2, 3, 4], [1, 4, 9, 16])
    plt.show()
    

The unwanted string output will not occur if 'capture_repr' is an empty tuple or does not contain __repr__ or __str__.

Prevent capture of certain classes

If you wish to capture a representation of the last expression of each code blocks unless the last expression is of a certain type, you can use 'ignore_repr_types'. 'ignore_repr_types' is by default an empty raw string (r''), meaning no types are ignored. To exclude specific type(s) from being captured, 'ignore_repr_types' can be set to a regular expression matching the name(s) of the type(s) to be excluded.

For example, the configuration below would capture the __repr__ of the last expression of each code block unless the name of the type() of the last expression includes the string ‘matplotlib.text’ or ‘matplotlib.axes’. This would prevent capturing of all subclasses of ‘matplotlib.text’, e.g. expressions of type ‘matplotlib.text.Annotation’, ‘matplotlib.text.OffsetFrom’ etc. Similarly subclasses of ‘matplotlib.axes’ (e.g. ‘matplotlib.axes.Axes’, ‘matplotlib.axes.Axes.plot’ etc.) will also not be captured.

sphinx_gallery_conf = {
    ...
    'capture_repr': ('__repr__'),
    'ignore_repr_types': r'matplotlib[text, axes]',
}