1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
.. _plot_directive_docs:
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.
.. code-block:: python
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:
.. pyvista-plot::
:caption: This is a default sphere
:include-source: True
>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> out = sphere.plot()
.. note::
You need to install the following packages to build the interactive scene:
.. code-block:: bash
pip install 'pyvista[jupyter]' sphinx sphinx_design
.. note::
You need to spin up a local server to view the interactive scene in the documentation.
.. code-block:: bash
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:
#. Create a new virtual environment and install dependencies
#. Create the files required for a simple documentation build:
#. Sphinx configuration file ``doc/src/conf.py`` with extensions
#. Source file ``doc/src/example.py`` with a simple plot directive example
#. Index file ``doc/src/index.rst`` for site navigation
#. Build the documentation
#. 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``.
.. code-block:: bash
# 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
=============
.. automodule::
pyvista.ext.plot_directive
|
