Sphinx PyVista Plot Directive

You can generate static images of pyvista plots using the .. pyvista-plot directive by adding the following to your conf.py when building your documentation using Sphinx.

extensions = [
    "sphinx.ext.napoleon",
    "pyvista.ext.plot_directive",
]

You can then issue the plotting directive within your sphinx documentation files:

>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> out = sphere.plot()
../_images/plot_directive-1_00_00.png

A sphere

Which will be rendered as:

>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> out = sphere.plot()
../_images/plot_directive-2_00_00.png

This is a default sphere

Plot directive module.

A directive for including a PyVista plot in a Sphinx document

The .. pyvista-plot:: sphinx directive will include an inline .png image.

The source code for the plot may be included in one of two ways:

  1. Using doctest syntax:

    .. pyvista-plot::
    
       >>> import pyvista
       >>> sphere = pyvista.Sphere()
       >>> out = sphere.plot()
    
  2. A path to a source file as the argument to the directive:

    .. plot:: path/to/plot.py
    

    When a path to a source file is given, the content of the directive may optionally contain a caption for the plot:

    .. plot:: path/to/plot.py
    
       The plot's caption.
    

    Additionally, one may specify the name of a function to call (with no arguments) immediately after importing the module:

    .. plot:: path/to/plot.py plot_function1
    

Note

Code blocks containing doctest:+SKIP will be skipped.

Note

Animations will not be saved, only the last frame will be shown.

Options

The pyvista-plot directive supports the following options:

include-sourcebool

Whether to display the source code. The default can be changed using the plot_include_source variable in conf.py.

encodingstr

If this source file is in a non-UTF8 or non-ASCII encoding, the encoding must be specified using the :encoding: option. The encoding will not be inferred using the -*- coding -*- metacomment.

contextNone

If provided, the code will be run in the context of all previous plot directives for which the :context: option was specified. This only applies to inline code plot directives, not those run from files.

nofigsbool

If specified, the code block will be run, but no figures will be inserted. This is usually useful with the :context: option.

captionstr

If specified, the option’s argument will be used as a caption for the figure. This overwrites the caption given in the content, when the plot is generated from a file.

Additionally, this directive supports all of the options of the image directive, except for target (since plot will add its own target). These include alt, height, width, scale, align.

Configuration options

The plot directive has the following configuration options:

plot_include_source

Default value for the include-source option.

plot_basedir

Base directory, to which plot:: file names are relative to. (If None or empty, file names are relative to the directory where the file containing the directive is.)

plot_html_show_formats

Whether to show links to the files in HTML.

plot_template

Provide a customized template for preparing restructured text.