Sphinx PyVista Plot Directive

Sphinx PyVista Plot Directive#

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

extensions = [
    "pyvista.ext.plot_directive",
    "pyvista.ext.viewer_directive",
    "sphinx_design",
]

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

.. pyvista-plot::
   :caption: A sphere
   :include-source: True

   >>> import pyvista
   >>> sphere = pyvista.Sphere()
   >>> out = sphere.plot()

Which will be rendered as:

>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> out = sphere.plot()

Static Scene

Interactive Scene

This is a default sphere

Note

You need to install the packages to build the interactive scene.

Note

You need to spin up a local server to view the interactive scene in the documentation.

python -m http.server 11000 --directory _build/html

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:

Using doctest syntax:

.. pyvista-plot::

   >>> import pyvista as pv
   >>> sphere = pv.Sphere()
   >>> out = sphere.plot()

A path to a source file as the argument to the directive:
```
.. pyvista-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:
```
.. pyvista-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:
```
.. pyvista-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.

nofigsNone
When setting this flag, 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.

force_staticNone
When setting this flag, static images will be used instead of an interactive scene.

skipbool, default: True
Whether to skip execution of this directive. If no argument is provided i.e., :skip:, then it defaults to :skip: true. Default behaviour is controlled by the plot_skip boolean variable in conf.py. Note that, if specified, this option overrides the plot_skip configuration.

optionalNone
This flag marks the directive for conditional execution. Whether the directive is executed is controlled by the plot_skip_optional boolean variable in conf.py.

Additionally, this directive supports all 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_sourcebool, default: True
Default value for the include-source directive option. Default is True.

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

plot_html_show_formatsbool, default: True
Whether to show links to the files in HTML. Default True.

plot_templatestr
Provide a customized Jinja2 template for preparing restructured text.

plot_setupstr
Python code to be run before every plot directive block.

plot_cleanupstr
Python code to be run after every plot directive block.

plot_skipbool, default: False
Default value for the skip directive option.

plot_skip_optionalbool, default: False
Whether to skip execution of optional directives.

These options can be set by defining global variables of the same name in conf.py.