Sphinx PyVista Plot ディレクティブ

Sphinx PyVista Plot ディレクティブ#

Sphinxを使ってドキュメントを作成する際に，以下の内容を conf.py に追加することで， .. pyvista-plot:: ディレクティブを使用して，pyvistaのプロットの静的なシーンとインタラクティブなシーンを生成することができます．

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

そうすれば，sphinxのドキュメントファイルの中で，plottingディレクティブを発行することができます:

.. pyvista-plot::
   :caption: This is a default sphere
   :include-source: True

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

以下のように表示されます．

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

これはデフォルトの球体

注釈

インタラクティブシーンをビルドするには、以下のパッケージをインストールする必要があります:

pip install 'pyvista[jupyter]' sphinx sphinx_design

注釈

ドキュメントのインタラクティブなシーンを見るには、ローカルサーバーを立ち上げる必要があります。

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

完全な例#

以下は、インタラクティブなプロットを含むドキュメントをゼロから作成するスクリプトです。このスクリプトは:

  1. 新しい仮想環境を作成し、依存関係をインストールします

  2. 簡単なドキュメントのビルドに必要なファイルを作成します:

    1. Sphinx 設定ファイル doc/src/conf.py と拡張子

    2. ソースファイル doc/src/example.py に簡単なプロットディレクティブの例を示します。

    3. サイトナビゲーションのためのインデックスファイル doc/src/index.rst

  3. ドキュメントの作成

  4. ローカルサーバーの起動

スクリプトを直接ターミナルにコピー＆ペーストして実行することができます。 ドキュメントが作成されたら、ウェブブラウザで 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リファレンス#

プロットディレクティブモジュール．

SphinxドキュメントにPyVistaプロットを含めるためのディレクティブ。

.. pyvista-plot:: ディレクティブは，インラインの .png イメージを含みます．

プロットのソースコードは，次の2つの方法のいずれかで含まれます．

  1. doctest 構文を使用しています．

    .. pyvista-plot::

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

  2. ソースファイルへのパス を directive の引数として指定します:

    .. pyvista-plot:: path/to/plot.py

    ソースファイルへのパスが与えられている場合，ディレクティブの内容には，オプションでプロットのキャプションを含めることができます:

    .. pyvista-plot:: path/to/plot.py

   The plot's caption.

    さらに，モジュールをインポートした直後に，（引数なしで）呼び出す関数の名前を指定することもできます．

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

注釈

doctest:+SKIP を含むコードブロックはスキップされます．

注釈

アニメーションは保存されず，最後のフレームのみが表示されます．

Options `pyvista-plot ディレクティブは，以下のオプションをサポートしています．

include-sourcebool

ソースコードを表示するかどうかを指定します．デフォルトは conf.py の pyvista_plot_include_source 変数で変更できます．

encodingstr

もし，このソースファイルがUTF8やASCII以外のエンコーディングである場合には， :encoding: オプションを使ってエンコーディングを指定しなければなりません． このエンコーディングは -*- coding -*- メタコメントを使って推測されることはありません．

contextNone

このオプションが指定された場合，コードは :context: オプションが指定された以前のすべてのプロットディレクティブのコンテクストで実行されます． これはインラインコードのプロットディレクティブにのみ適用され，ファイルから実行されるものには適用されません．

nofigsNone

このフラグを設定すると，コードブロックは実行されますが，数字は挿入されません． これは通常 :context: オプションと一緒に使うと便利です．

captionstr

指定された場合，オプションの引数が図のキャプションとして使用されます．これは，ファイルからプロットが生成された場合，コンテンツで与えられたキャプションを上書きします．

force_staticNone

このフラグを設定すると，インタラクティブシーンの代わりに静止画像が使われます．

skipbool, default: True

このディレクティブの実行をスキップするかどうか。 引数を指定しない場合、つまり :skip: の場合、デフォルトは :skip: true です。 デフォルトの動作は conf.py の plot_skip boolean 変数によって制御されます。 このオプションは plot_skip の設定を上書きすることに注意してください。

optionalNone

このフラグはディレクティブを 条件付き で実行することを示します。 ディレクティブが実行されるかどうかは conf.py の plot_skip_optional boolean 変数によって制御されます。

さらに，このディレクティブは， target を除いて， image ディレクティブのすべてのオプションをサポートしています (plot が独自のターゲットを追加するため)． これらのオプションには alt, height, width, scale, align があります．

Configuration options

バージョン 0.45 で変更: Prior to v0.45, these directives conflicted with matplotlib. All directives have been prepended with pyvista_.

plotディレクティブには，以下の設定項目があります．

pyvista_plot_include_sourcebool, default: True

include-source ディレクティブオプションのデフォルト値．デフォルトは True 。

pyvista_plot_basedirstr

ベースとなるディレクトリで， plot:: のファイル名の相対パスを指定します． None または未設定の場合には，ファイル名はそのディレクティブを含むファイルがあるディレクトリに相対します．

pyvista_plot_html_show_formatsbool, default: True

ファイルへのリンクをHTMLで表示するかどうか．デフォルトは True ．

pyvista_plot_templatestr

再構成されたテキストを作成するためのカスタマイズされた Jinja2 テンプレートを提供します．

pyvista_plot_setupstr

各プロットディレクティブブロックの前に実行されるPythonコード．

pyvista_plot_cleanupstr

各プロットディレクティブブロックの後に実行されるPythonコード．

pyvista_plot_skipbool, default: False

ディレクティブオプション skip のデフォルト値。

pyvista_plot_skip_optionalbool, default: False

オプションの ディレクティブの実行をスキップするかどうか。

これらのオプションは， conf.py で同名のグローバル変数を定義することで設定できます．

目次