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: This is a default 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 following packages to build the interactive scene:

pip install 'pyvista[jupyter]' sphinx sphinx_design

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

Complete Example

The following is a script to build documentation with interactive plots from scratch. The script will:

1. Create a new virtual environment and install dependencies

2. Create the files required for a simple documentation build:

   1. Sphinx configuration file doc/src/conf.py with extensions

   2. Source file doc/src/example.py with a simple plot directive example

   3. Index file doc/src/index.rst for site navigation

3. Build the documentation

4. Start a local server

You can copy and paste the script directly into a terminal and execute it. Once the documentation is built, you should be able to view it with a web browser by navigating to http://localhost:11000.

# Setup a new virtual environment and activate it
python -m venv .venv
emulate bash -c '. .venv/bin/activate'

# Install dependencies for the build
pip install 'pyvista[jupyter]' sphinx sphinx_design

# Create new `doc/src` directory
mkdir doc
cd doc
mkdir src

# Create a simple python module and include an example
# in the docstring using the plot directive.
cat > src/example.py <<EOF

def foo():
    """Some function.

    .. pyvista-plot::

        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> mesh.plot()
    """

EOF

# Create the configuration file with the required extensions.
# Here we also include `autodoc` for the example.
cat > src/conf.py <<EOF
import os, sys

sys.path.insert(0, os.path.abspath("."))

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

# Create the index for the documentation
cat > src/index.rst <<EOF
API Reference
=============

.. automodule:: example
    :members:
    :undoc-members:
EOF

# Build the documentation
sphinx-build -b html src _build/html

# Start a local server for the interactive scene
python -m http.server 11000 --directory _build/html

API Reference

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 as pv
      >>> sphere = pv.Sphere()
      >>> out = sphere.plot()
   

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

Changed in version 0.45: Prior to v0.45, these directives conflicted with matplotlib. All directives have been prepended with pyvista_.

The plot directive has the following configuration options:

pyvista_plot_include_sourcebool, default: True

Default value for the include-source directive option. Default is True.

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

pyvista_plot_html_show_formatsbool, default: True

Whether to show links to the files in HTML. Default True.

pyvista_plot_templatestr

Provide a customized Jinja2 template for preparing restructured text.

pyvista_plot_setupstr

Python code to be run before every plot directive block.

pyvista_plot_cleanupstr

Python code to be run after every plot directive block.

pyvista_plot_skipbool, default: False

Default value for the skip directive option.

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

Directive Configuration Settings

Globally, you can set if the file names should be either:

• Deterministic, based on directive source hash: <BASENAME>-<HASH>_<INDEX>_<SUBINDEX>.<EXT> (Default)

• Indexed, based on location in document: <BASENAME>-<DOC-INDEX>_<INDEX>_<SUBINDEX>.<EXT>

Enable indexed naming this by setting pyvista_plot_use_counter=True. Note that indexed is incompatible with parallel builds due to race conditions.

Changed in version 0.47: Hash-based image naming is now used by default.