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.

When using these flags, it is good practice to make sure the source Python files are equivalent to the generated HTML and iPython notebooks (i.e. make sure .py == .html == .ipynb). This principle should be violated only when necessary, and on a case-by-case basis.

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:

Some options can be set on a per-code-block basis in a file:

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

Some options can be set on a per-line basis in a file: - # sphinx_gallery_start_ignore and # sphinx_gallery_end_ignore (Hiding lines of code)

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.'
                                '|(\n|.)*is non-interactive, and thus cannot be shown')

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). See Rerunning stale examples below for information.

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 ...

Rerunning stale examples#

By default, Sphinx-Gallery only rebuilds examples that have changed. For example, when starting from a clean doc/ directory, running your HTML build once will result in Sphinx-Gallery executing all examples that match your given filename/ignore patterns. Then, running the exact same command a second time should not run any examples, because the MD5 hash of each example will be checked against the MD5 hash (saved to disk as <filename>.md5 in the generated directory) that the example file had during the first build. These will match and thus the example will be determined to be “stale”, and it will not be rebuilt by Sphinx-Gallery. This design feature allows for more rapid documentation iteration by only rebuilding examples when they change.

However, this presents a problem during some modes of debugging and iteration. Let’s say that you have one particular example that you want to rebuild repeatedly while modifying some function in your underlying library but do not want to change the example file contents themselves. To do this, you’d either need to make some change (e.g., add/delete a newline) to your example or delete the .md5 file to force Sphinx-Gallery to rebuild the example. Instead, you can use the configuration value:

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

With this configuration, all examples matching the filename/ignore pattern will be rebuilt, even if their MD5 hash shows that the example did not change. You can combine this with filename/ignore patterns to repeatedly rerun a single example. This could be done from the command line, for example:

$ make html SPHINXOPTS="-D sphinx_gallery_conf.run_stale_examples=True -D sphinx_gallery_conf.filename_pattern='my_example_name'"

This command will cause any examples matching the filename pattern 'my_example_name' to be rebuilt, regardless of their MD5 hashes.

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/method/attribute/object/class, Sphinx-Gallery enables you to link to any examples that either:

  1. Use the function/method/attribute/object or instantiate the class in the code (generates implicit backreferences).

  2. Refer to that function/method/attribute/object/class using sphinx markup :func:/:meth:/:attr:/:obj:/:class: in a text block. You can omit this role markup if you have set the default_role in your conf.py to any of these roles (generates explicit backreferences).

The former is useful for auto-documenting functions/methods/attributes/objects that are used and classes that are explicitly instantiated. The generated links are called implicit backreferences. 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). Such links are called explicit backreferences.

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#

Plotting the exponential function

Plotting the exponential function

Choosing the thumbnail figure

Choosing the thumbnail figure

Identifying function names in a script

Identifying function names in a script

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

    # Regexes to match objects to exclude from implicit backreferences.
    # The default option is an empty set, i.e. exclude nothing.
    # To exclude everything, use: '.*'
    'exclude_implicit_doc': {r'pyplot\.show'},
}

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.

Sometimes, there are functions that are being used in practically every example for the given module, for instance the pyplot.show or pyplot.subplots functions in Matplotlib, so that a large number of often spurious examples will be linked to these functions. To prevent this, you can exclude implicit backreferences for certain objects by including them as regular expressions in exclude_implicit_doc. The following setting will exclude any implicit backreferences so that examples galleries are only created for objects explicitly mentioned by Sphinx markup in a documentation block: {'.*'}. To exclude the functions mentioned above you would use {r'pyplot\.show', r'pyplot\.subplots'} (note the escape to match a dot instead of any character, if the name is unambiguous you can also write pyplot.show or just show).

Within your sphinx documentation .rst files, you can 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., -). The mini-gallery will only be shown if the item (here numpy.exp) is actually used or referred to in an example.

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 specified within a file 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, file-level 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, no first cell is added.

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, you can add the following first cell:

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

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"
                            )
}

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"
                            ),
    '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 reST documentation blocks (not images generated from 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 reST 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 reST 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 reST to markdown#

Sphinx-Gallery can use pypandoc (if installed) to convert reST 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 reST to markdown converter has limited support for more complex reST syntax. If your examples have more complex reST, 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 building 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

You can also use negative numbers, which counts from the last figure. For example -1 means using the last figure created in the example as the thumbnail:

# sphinx_gallery_thumbnail_number = -1

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

Providing an image for the thumbnail image#

An arbitrary image can be used to serve as the thumbnail image for an example. To specify an image to serve as the thumbnail, add a comment to the example script specifying the path to the desired image. The path to the image should be relative to the conf.py file and the comment should be somewhere below the docstring (ideally in a code block, see Removing config comments).

For example, the following defines that the image 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.

Making cell magic executable in notebooks#

Often times, tutorials will include bash code for the user to copy/paste into their terminal. This code should not be run when someone is building the documentation, as they will already have those dependencies in their environment. Hence they are normally written as code blocks inside text:

#%%
# Installing dependencies
#
#     .. code-block:: bash
#
#       pip install -q tensorflow
#       apt-get -qq install curl

This works fine for the .py and .html files, but causes problems when rendered as an Jupyter notebook. The downloaded .ipynb file will not have those dependencies installed, and will not work without running the bash code.

To fix this, we can set the promote_jupyter_magic flag in conf.py:

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

If this flag is True, then when a Jupyter notebook is being built, any code block starting with Jupyter cell magics (e.g. %%bash or %%writefile) will be turned into a runnable code block.

For our earlier example, we could change the Markdown text to:

#%%
# Installing dependencies
#
#     .. code-block:: bash
#
#       %%bash
#       pip install -q tensorflow
#       apt-get -qq install curl

meaning TensorFlow and Curl would be automatically installed upon running the Jupyter notebook. This works for any cell magic (not just those mentioned above) and only affects the creation of Jupyter notebooks.

Warning

It is good practice to ensure the .py and .html files match the .ipynb files as closely as possible. This functionality should only be used when the relevant code is intended to be executed by the end user.

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.

Note

If adding html-noplot to your Makefile, you will also need to explicitly set the default value for plot_gallery in the sphinx_gallery_conf dictionary inside your conf.py file to avoid a sphinx configuration warning.

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.

Multi-resolution images#

Web browsers allow a srcset parameter to the <img> tag that allows the browser to support responsive resolution images for hi-dpi/retina displays. Sphinx Gallery supports this via the image_srcset parameter:

sphinx_gallery_conf = {
    ...
    'image_srcset': ["2x"],
}

that saves a 1x image at the normal figure dpi (usually 100 dpi) and a 2x version at twice the density (e.g. 200 dpi). The default is no extra images ('image_srcset': []), and you can specify other resolutions if desired as a list: ["2x", "1.5x"].

The matplotlib scraper creates a custom image directive, image-sg in the rst file:

.. image-sg:: /examples/images/sphx_glr_test_001.png
    :alt: test
    :srcset: /examples/images/sphx_glr_test_001.png, /examples/images/sphx_glr_test_001_2_0x.png 2.0x
    :class: sphx-glr-single-img

This is converted to html by the custom directive as:

.. <img src="../_images/sphx_glr_test_001.png" alt="test", class="sphx-glr-single-img",
    srcset="../_images/sphx_glr_test_001.png, ../_images/sphx_glr_test_001_2_0x.png 2.0x>

This leads to a larger website, but clients that support the srcset tag will only download the appropriate-sized images.

Note that the .. image-sg directive currently ignores other .. image directive tags like width, height, and align. It also only works with the html and latex builders.

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 matplotlib images you can do:

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

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'.

  • 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.

  • qtgallery

    This library provides a scraper for Qt windows. See their repository for instructions on integrating 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)!

Using multiple code blocks to create a single figure#

By default, images are scraped following each code block in an example. Thus, the following produces two plots, with one plot per code block:

# %%
# This first code block produces a plot with two lines

import matplotlib.pyplot as plt
plt.plot([1, 0])
plt.plot([0, 1])

# %%
# This second code block produces a plot with one line

plt.plot([2, 2])
plt.show()

However, sometimes it can be useful to use multiple code blocks to create a single figure, particularly if the figure takes a large number commands that would benefit from being interleaved with text blocks. The optional flag sphinx_gallery_defer_figures can be inserted as a comment anywhere in a code block to defer the scraping of images to the next code block (where it can be further deferred, if desired). The following produces only one plot:

# %%
# This first code block does not produce any plot

import matplotlib.pyplot as plt
plt.plot([1, 0])
plt.plot([0, 1])
# sphinx_gallery_defer_figures

# %%
# This second code block produces a plot with three lines

plt.plot([2, 2])
plt.show()

Hiding lines of code#

Normally, Sphinx-Gallery will render every line of Python code when building HTML and iPython notebooks. This is usually desirable, as we want to ensure the Python source files, HTML, and iPython notebooks all do the same thing.

However, it is sometimes useful to have Python code that runs, but is not included in any user-facing documentation. For example, suppose we wanted to add some assert statements to verify the docs were built successfully, but did not want these shown to users. We could use the sphinx_gallery_start_ignore and sphinx_gallery_end_ignore flags to achieve this:

model.compile()
# sphinx_gallery_start_ignore
assert len(model.layers) == 5
assert model.count_params() == 219058
# sphinx_gallery_end_ignore
model.fit()

When the HTML or iPython notebooks are built, this code block will be shown as:

model.compile()
model.fit()

The sphinx_gallery_start_ignore and sphinx_gallery_end_ignore flags may be used in any code block, and multiple pairs of flags may be used in the same block. Every start flag must always have a corresponding end flag, or an error will be raised during doc generation. These flags and the code between them are always removed, regardless of what remove_config_comments is set to.

Note that any output from the ignored code will still be captured.

Warning

This flag should be used sparingly, as it makes the .py source files less equivalent to the generated .html and .ipynb files. It is bad practice to use this when other methods that preserve this relationship are possible.

Generating dummy images#

For quick visualization of your gallery, especially during the writing process, Sphinx-Gallery allows you to build your gallery without executing the code (see Building without executing examples and filename/ignore patterns). This however, can cause warnings about missing image files if you have manually written links to automatically generated images. To prevent these warnings you can tell Sphinx-Gallery to create a number of dummy images for an example.

For example, you may have an example (‘my_example.py’) that generates 2 figures, which you then reference manually elsewhere, e.g.,:

Below is a great figure:

.. figure:: ../auto_examples/images/sphx_glr_my_example_001.png

Here is another one:

.. figure:: ../auto_examples/images/sphx_glr_my_example_002.png

To prevent missing image file warnings when building without executing, you can add the following to the example file:

# sphinx_gallery_dummy_images=2

This will cause Sphinx-Gallery to generate 2 dummy images with the same naming convention and stored in the same location as images that would be generated when building with execution. No dummy images will be generated if there are existing images (e.g., from a previous run of the build), so they will not be overwritten.

Note

This configuration only works when the example is set to not execute (i.e., the plot_gallery is 'False', the example is in ignore_pattern or the example is not in filename_pattern - see filename/ignore patterns). This means that you will not need to remove any sphinx_gallery_dummy_images lines in your examples when you switch to building your gallery with execution.

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 reloading submodules that populate the units registry) 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 Resetting before each example.

Order of resetting modules#

By default, Sphinx-Gallery will reset modules before each example is run. The choices for reset_modules_order are before (default), after, and both. If the last example run in Sphinx-Gallery modifies a module, it is recommended to use after or both to avoid leaking out a modified module to other parts of the Sphinx build process. For example, set reset_modules_order to both in the configuration:

sphinx_gallery_conf = {
    ...
    'reset_modules_order': 'both',
}

Custom functions can be constructed to have custom functionality depending on whether they are called before or after the examples. See Resetting before each example for more information.

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()),
}

Show signature#

By default, Sphinx-Gallery writes a Generated by … notice in the generated output.

The show_signature parameter can be used to disable it.

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.

Output capture can be controlled globally by the capture_repr configuration setting or file-by-file by adding a comment to the example file, which overrides any global setting:

# sphinx_gallery_capture_repr = ()

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. For several examples, see Capturing output representations.

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

Manually passing files#

By default, Sphinx-Gallery creates all the files that are written in the sphinx-build directory, either by generating rst and images from a *.py in the gallery-source, or from creating index.rst from README.txt in the gallery-source. However, sometimes it is desirable to pass files from the gallery-source to the sphinx-build. For example, you may want to pass an image that a gallery refers to, but does not generate itself. You may also want to pass raw rst from the gallery-source to the sphinx-build, because that material fits in thematically with your gallery, but is easier to write as rst. To accommodate this, you may set copyfile_regex in sphinx_gallery_conf. The following copies across rst files.

sphinx_gallery_conf = {
    ...
   'copyfile_regex': r'.*\.rst',
}

Note that if you copy across files rst files, for instance, it is your responsibility to ensure that they are in a sphinx toctree somewhere in your document. You can, of course, add a toctree to your README.txt.

Manually passing index.rst#

You can bypass Sphinx-Gallery automatically creating an index.rst from a README.txt in a gallery directory or subdirectory. If your copyfile_regex includes index.rst, and you have an index.rst in the gallery-source instead of the README, Sphinx-Gallery will use that instead of the index it automatically makes. If you do this, you are responsible for adding your own Sphinx toctree in that index (or elsewhere in your Sphinx documentation) that includes any gallery items or other files in that directory.

Showing API Usage#

Graphs and documentation of both unused API entries and the examples that each API entry is used in are generated in the sphinx output directory under sg_api_usage.html. See the Sphinx-Gallery API usage documentation and graphs for example. In large projects, there are many modules and, since a graph of API usage is generated for each module, this can use a lot of resources so show_api_usage is set to 'unused' by default. The unused API entries are all shown in one graph so this scales much better for large projects. Setting show_api_usage to True will make one graph per module showing all of the API entries connected to the example that they are used in. This could be helpful for making a map of which examples to look at if you want to learn about a particular module. Setting show_api_usage to False will not make any graphs or documentation about API usage. Note, graphviz is required for making the unused and used API entry graphs.

Ignoring API entries#

By default, api_usage_ignore='.*__.*__' ignores files that match this regular expression in documenting and graphing the usage of API entries within the example gallery. This regular expression can be modified to ignore any kind of file that should not be considered. The default regular expression ignores functions like __len__() for which it may not be desirable to document if they are used in examples.