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:
.. 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()

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:
Using doctest syntax:
.. pyvista-plot:: >>> import pyvista >>> sphere = pyvista.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.- 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_sourcebool
Default value for the include-source option. Default is
True
.- plot_basedirstr
Base directory, to which
plot::
file names are relative to. IfNone
or unset, file names are relative to the directory where the file containing the directive is.- plot_html_show_formatsbool
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.
These options can be set by defining global variables of the same name in
conf.py
.