ドキュメントの作成#

はじめに#

一般的なファイル構造#

すべてのドキュメントは、doc/. このディレクトリには、ドキュメント ページに表示されるdoc/ Sphinx および reStructuredText ( ReST ; ) ファイルの構成ファイルが含まれています。.rst

ドキュメントは 3 つの方法で作成されます。まず、API ドキュメント ( ) は、Matplotlib ライブラリ内のクラスのドキュメント文字列からSphinxdoc/apiによって作成されます。を除き 、 のファイルはドキュメントのビルド時に作成されます。以下の docstring の記述を参照してください。doc/api/api_changes/.rstdoc/api

次に、と のコンテンツはdoc/plot_typesdoc/galleryと のPython ファイルからSphinx ギャラリーdoc/tutorialsによって生成されます。これらのソースは、 ReSTドキュメントがコメントに組み込まれている Python スクリプトで構成されています。以下の例とチュートリアルの作成を参照してください。plot_types/examples/tutorials/

第三に、Matplotlib にはReSTで記述されたナラティブ ドキュメントが のサブディレクトリにあり doc/users/ます。ギャラリーやチュートリアルの例ではなく、ファイルに適した新しいドキュメントを追加する場合は.rst、それを配置する適切なサブディレクトリを選択し、サブディレクトリの目次にファイルを追加しますindex.rst以下の ReST ページの作成を参照してください 。

ノート

、 、、および ( を除く) の.rstファイルを直接編集しないでください。Sphinxは、ドキュメントのビルド時にこれらのディレクトリにファイルを再生成します。doc/plot_typesdoc/gallerydoc/tutorialsdoc/apidoc/api/api_changes/

ドキュメントビルドの設定#

Matplotlib のドキュメントは、 Sphinxドキュメント生成ツールを使用して reStructuredText ( ReST )から生成されます。

ドキュメントを作成するには、開発用に Matplotlib をセットアップする必要があります 。特に、ドキュメントをビルドするために必要な追加の依存関係に注意してください。

ドキュメントの構築#

ドキュメントのソースはdoc/、トランクのディレクトリにあります。Sphinx の設定ファイルはdoc/conf.py. Sphinx が解析するディレクトリ、ドキュメントの作成方法、および拡張機能の使用方法を制御します。ドキュメントを HTML 形式でビルドするには、cd してdoc/次を実行します。

make html

その他の便利な呼び出しには次のものがあります。

# Delete built files.  May help if you get errors about missing paths or
# broken links.
make clean

# Build pdf docs.
make latexpdf

完全なドキュメントをビルドするためにSPHINXOPTS変数はデフォルトで に設定されますが、警告がある場合は終了ステータス 1 で終了します。設定を解除するには、使用します-W --keep-going

make SPHINXOPTS= html

O変数を使用して、追加のオプションを設定できます。

  • make O=-j4 html4 つのプロセスで並列ビルドを実行します。

  • make O=-Dplot_formats=png:100 htmlフィギュアを低解像度で保存します。

  • make O=-Dplot_gallery=0 htmlギャラリーのビルドをスキップします。

複数のオプションを組み合わせることができます。make O='-j4 -Dplot_gallery=0' html

Windows では、オプションを環境変数として設定します。例:

set SPHINXOPTS= & set O=-j4 -Dplot_gallery=0 & make html

ローカルにビルドされたドキュメントの表示#

ビルドされたドキュメントは、フォルダにありますbuild/html。デフォルトのブラウザで開くためのショートカットは次のとおりです。

make show

ReSTページを書く#

ほとんどのドキュメントは、個々のクラスとメソッドのドキュメント文字列、明示的な.rstファイル、または例とチュートリアルのいずれかにあります。これらはすべてReST構文を使用し、 Sphinxによって処理されます。

Sphinx reStructuredText Primerは、 ReSTを使用するための優れた入門書です。詳細については、reStructuredText リファレンス ドキュメントを参照してください。

このセクションには、Matplotlib ドキュメントでの ReST の使用方法に関する追加情報と規則が含まれています。

フォーマットとスタイルの規則#

Matplotlib のドキュメントで一貫性を保つよう努めることは役に立ちます。ここでは、使用されるフォーマットとスタイルの規則をいくつか示します。

セクションのフォーマット#

最上位の章以外のすべてについて、セクション タイトルとして使用します。Upper lowerPossible hangupsPossible Hangups

セクション マークアップ文字については、 Python ドキュメントSphinx reStructuredText ドキュメントの推奨事項に従うことを目指しています 。

  • #パーツ用、上線あり。これは のメイン タイトル用に予約されてい index.rstます。他のすべてのページは「章」以下で開始する必要があります。

  • *上線付き、章用

  • =、セクション用

  • -、サブセクション用

  • ^、サブサブセクション用

  • "、段落の場合

これは、既存のドキュメントではまだ一貫して適用されていない可能性があります。

関数の引数#

docstring 内の関数の引数とキーワードは、*emphasis*ロールを使用して参照する必要があります。これにより、Matplotlib のドキュメントと Python のドキュメントの一貫性が保たれます。

Here is a description of *argument*

使用しないでください:`default role`

Do not describe `argument` like this.  As per the next section,
this syntax will (unsuccessfully) attempt to resolve the argument as a
link to a class or method in the library.

``literal``役割もありません:

Do not describe ``argument`` like this.

他のドキュメントやセクションの参照 #

Sphinxでは、ドキュメント間の内部参照が可能です。

:doc:ドキュメントはディレクティブでリンクできます:

See the :doc:`/users/installing/index`

See the tutorial :doc:`/tutorials/introductory/quick_start`

See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`

次のようにレンダリングされます。

インストールを見る

チュートリアルのクイック スタート ガイドを参照してください

単純なプロットの例を参照してください

セクションにも参照名を付けることができます。たとえば、 インストールリンクから:

.. _clean-install:

How to completely remove Matplotlib
===================================

Occasionally, problems with Matplotlib can be solved with a clean...

標準の参照構文を使用して参照します。

See :ref:`clean-install`

次のリンクが表示されます: Matplotlib を完全に削除する方法

セクションのラベル付けと参照の内部一貫性を最大限に高めるには、ハイフンで区切られた説明的なラベルをセクション参照に使用します。内容は後で再編成される可能性があることに注意してください。たとえば、「バックエンドとは何ですか?」という FAQ など、必要な場合を除いて、userまたはdevel またはなどの参照では最上位の名前を使用しないでください。faq後でユーザーガイドの一部になる可能性があるため、ラベルは次のとおりです。

.. _what-is-a-backend:

よりも良い:

.. _faq-backend:

また、アンダースコアは Sphinx 自体で広く使用されているため、ハイフンを使用して単語を区切ります。

他のコードの参照 #

Matplotlib の他のメソッド、クラス、またはモジュールにリンクするには、次のようにバックティックを使用できます。

`matplotlib.collections.LineCollection`

次のようなリンクが生成されますmatplotlib.collections.LineCollection

注: 、、などの修飾子を使用する必要がないように、sphinx設定を使用します。default_role = 'obj':class::func::meth:

多くの場合、完全なパッケージ名とモジュール名を表示したくない場合があります。ターゲットが明確である限り、単純に除外できます。

`.LineCollection`

リンクは引き続き機能します: LineCollection.

同じ名前のコード要素が複数ある場合 (plot()複数のクラスのメソッドなど)、定義を拡張する必要があります。

`.pyplot.plot` or `.Axes.plot`

これらはpyplot.plotまたはとして表示されAxes.plotます。最後のセグメントのみを引き続き表示するには、プレフィックスとしてチルダを追加できます。

`~.pyplot.plot` or `~.Axes.plot`

plotまたはとしてレンダリングされますplot

他のパッケージも intersphinx経由でリンクできます:

`numpy.mean`

は次のリンクを返します: numpy.mean。これは、Python、Numpy、Scipy、および Pandas で機能します (完全なリストは にありdoc/conf.pyます)。外部リンクが失敗した場合は、次のコマンドを使用して、参照可能なオブジェクトの完全なリストを確認できます。

python -m sphinx.ext.intersphinx 'https://docs.python.org/3/objects.inv'
python -m sphinx.ext.intersphinx 'https://numpy.org/doc/stable/objects.inv'
python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/scipy/objects.inv'
python -m sphinx.ext.intersphinx 'https://pandas.pydata.org/pandas-docs/stable/objects.inv'

図とファイルを含める#

画像ファイルは、image::ディレクティブを使用してページに直接含めることができます。たとえば、tutorials/intermediate/constrainedlayout_guide.pyいくつかの静止画像を表示します。

# .. image:: /_static/constrained_layout_1b.png
#    :align: center

ファイルは逐語的に含めることができます。たとえば、LICENSEファイルは使用許諾契約に含まれています

.. literalinclude:: ../../LICENSE/LICENSE

doc/galleryexamples ディレクトリはsphinx-gallery によってコピーされるため、examples ディレクトリからのプロットは以下を使用して含めることができます。

.. plot:: gallery/lines_bars_and_markers/simple_plot.py

作成されたプロットではなく、プロットを生成する python スクリプトが参照されることに注意してください。Sphinx-gallery は、ドキュメントがビルドされるときに正しい参照を提供します。

ドキュメント文字列を書く#

API ドキュメントのほとんどは、docstring で記述されています。これらは、コードの動作を説明するソース コード内のコメント ブロックです。

ノート

ドキュメントの一部は、現在のドキュメント スタイルにまだ準拠していません。疑わしい場合は、ソース コードに表示されるルールではなく、ここに記載されているルールに従ってください。docstring を現在のスタイルに更新するプル リクエストは大歓迎です。

すべての新規または編集された docstring は、numpydoc docstring guideに準拠する必要があります。上で説明したReST構文 ( ReST ページの作成 )の多くは、リンクと参照に使用できます。これらの docstring は最終的に doc/apiディレクトリに入力され、ライブラリの参照ドキュメントを形成します。

docstring の例#

docstring の例は次のようになります。

def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
           label='', **kwargs):
    """
    Plot horizontal lines at each *y* from *xmin* to *xmax*.

    Parameters
    ----------
    y : float or array-like
        y-indexes where to plot the lines.

    xmin, xmax : float or array-like
        Respective beginning and end of each line. If scalars are
        provided, all lines will have the same length.

    colors : list of colors, default: :rc:`lines.color`

    linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional

    label : str, default: ''

    Returns
    -------
    `~matplotlib.collections.LineCollection`

    Other Parameters
    ----------------
    data : indexable object, optional
        DATA_PARAMETER_PLACEHOLDER
    **kwargs :  `~matplotlib.collections.LineCollection` properties.

    See Also
    --------
    vlines : vertical lines
    axhline : horizontal line across the Axes
    """

hlinesこれがどのようにレンダリングされるかについては、ドキュメントを参照してください。

SphinxのWeb サイトには、ReST マークアップと Sphinx の一般的な操作に関するドキュメントも多数含まれています。

フォーマット規則#

基本的な docstring 規則は、numpydoc docstring ガイドSphinxのドキュメントで説明されています。留意すべきいくつかの Matplotlib 固有のフォーマット規則:

ポジションの引用#

単一行の docstring の引用符は同じ行にあります (pydocstyle D200):

def get_linewidth(self):
    """Return the line width in points."""

複数行の docstring の引用符は別の行にあります (pydocstyle D213):

def set_linestyle(self, ls):
"""
Set the linestyle of the line.

[...]
"""

関数の引数#

docstring 内の関数の引数とキーワードは、*emphasis*ロールを使用して参照する必要があります。これにより、Matplotlib のドキュメントと Python のドキュメントの一貫性が保たれます。

If *linestyles* is *None*, the default is 'solid'.

またはロールを使用しないでください。`default role```literal``

Neither `argument` nor ``argument`` should be used.

文字列の引用#

Matplotlib には、一重引用符と二重引用符のどちらを使用するかという規則がありません。現在のコードには両方が混在しています。

文字列値を指定するときは、単純な一重引用符または二重引用符を使用してください。

If 'tight', try to figure out the tight bbox of the figure.

No ``'extra'`` literal quotes.

テキストの前後に余分なリテラル引用符を使用することはお勧めできません。レンダリングされたドキュメントはわずかに改善されますが、入力するのが面倒で、プレーンテキストのドキュメントを読むのは困難です。

パラメータタイプの説明#

パラメータ型の説明の主な目標は、人間が読みやすく、理解できるようにすることです。可能性のある型が複雑すぎる場合は、型の説明を簡略化し、テキストで型をより正確に説明します。

一般に、numpydoc docstring ガイドの規則が適用されます。次のルールは、numpydoc の規則が特定されていない場合に適用されます。

float任意の数値の型に使用します。

2D 位置を表すために使用します。タプルであることをより明確にするために、括弧を含める必要があります。(float, float)

array-like通常は numpy.array である同種の数値シーケンスに使用します。次元は、、、を使用して指定2Dでき 3Dますn-dimensional。寸法のサイズを示す変数が必要な場合は、括弧内に大文字を使用します ( )。テキストでそれらを参照すると、読みやすくなり、特別な書式設定は必要ありません。返されたオブジェクトが実際に numpy 配列である場合は、戻り値の型の代わりに 使用します。(M, N) array-likearrayarray-like

floatarray-likes の暗黙のデフォルト dtype です。他の dtype の場合は.array-like of int

考えられる用途:

2D array-like
(N,) array-like
(M, N) array-like
(M, N, 3) array-like
array-like of int

非数値同種シーケンスはリストとして記述されます。例:

list of str
list of `.Artist`

型の参照 #

一般に、他のコードへの参照のルールが適用されます。すなわち:

`~matplotlib.colors.Normalize`パラメーターの型では、省略形のチルダを使用して完全な参照を使用します。完全な名前はプレーン テキストの docstring の読者に役立ちますが、HTML はそれにリンクしているため、完全な名前を表示する必要はありません。したがって、~短縮すると読みやすくなります。

`.Normalize`本文中では短縮リンクを使用してください。

norm : `~matplotlib.colors.Normalize`, optional
     A `.Normalize` instance is used to scale luminance data to 0, 1.

デフォルト値#

numpydoc ガイドとは対照的に 、単純なデフォルトがある場合、パラメーターをオプションとしてマークする必要はありません。

  • 可能な場合に使用します。{name} : {type}, default: {val}

  • 推奨される方法で十分に説明できない場合は、テキストでデフォルトを使用して説明してください。{name} : {type}, optional

デフォルト値は、人間の読者を対象としたセマンティック情報を提供する必要があります。単純なケースでは、関数シグネチャの値を言い換えます。該当する場合は、ユニットを追加する必要があります。

Prefer:
    interval : int, default: 1000ms
over:
    interval : int, default: 1000

Noneが「パラメーターが指定されていません」のセンチネル値としてのみ使用されている場合は、それをデフォルトとして文書化しないでください。コンテキストに応じて、実際のデフォルトを指定するか、指定しなくても特に効果がない場合はパラメーターをオプションとしてマークします。

Prefer:
    dpi : float, default: :rc:`figure.dpi`
over:
    dpi : float, default: None

Prefer:
    textprops : dict, optional
        Dictionary of keyword parameters to be passed to the
        `~matplotlib.text.Text` instance contained inside TextArea.
over:
    textprops : dict, default: None
        Dictionary of keyword parameters to be passed to the
        `~matplotlib.text.Text` instance contained inside TextArea.

See alsoセクション#

Sphinx は、セクションの定義ブロック内のコード要素を自動的にリンクします。そこでバッククォートを使用する必要はありません:See also

See Also
--------
vlines : vertical lines
axhline : horizontal line across the Axes

パラメータリストのラッピング#

長いパラメータ リストは、\for continuation を使用してラップし、インデントなしで新しい行から開始する必要があります (pydoc は docstring を解析し、行の継続を削除して、インデントによって行内に多くの空白が生じるため、インデントはありません)。

def add_axes(self, *args, **kwargs):
    """
    ...

    Parameters
    ----------
    projection : {'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \
'rectilinear'}, optional
        The projection type of the axes.

    ...
    """

または、docstring の専用セクションに有効なパラメーター値を記述することもできます。

rcParams #

rcParams は、カスタム:rc:ロール の:rc:`foo`yieldsで参照できます。これは、ファイルの説明へのリンクです。rcParams["foo"] = 'default'matplotlibrc

セッターとゲッター#

アーティストのプロパティは、setter メソッドと getter メソッドを使用して実装されます (Matplotlib は Pythonpropertyデコレータよりも古いため)。慣例により、これらのセッターとゲッターはset_PROPERTYNAMEand と 名付けられていget_PROPERTYNAMEます。このようにしてアーティストに定義されたプロパティのリストとその値は、setpおよびgetp関数によってリストできます。

プロパティ セッター メソッドのパラメーター ブロックは、受け入れられた値を文書化するために解析されますLine2D.set_linestyle

def set_linestyle(self, ls):
    """
    Set the linestyle of the line.

    Parameters
    ----------
    ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
        etc.
    """

plt.setp(line)または の出力に次の行が表示されます。plt.setp(line, "linestyle")

linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}

いくつかのまれなケース (ほとんどの場合、単一のタプルとアンパックされたタプルの両方を受け入れるセッター) では、受け入れられた値をそのような方法で文書化することはできません。その場合、それらはブロックとして文書化できます。たとえば、 次の場合です。.. ACCEPTS:axes.Axes.set_xlim

def set_xlim(self, ...):
    """
    Set the x-axis view limits.

    Parameters
    ----------
    left : float, optional
        The left xlim in data coordinates. Passing *None* leaves the
        limit unchanged.

        The left and right xlims may also be passed as the tuple
        (*left*, *right*) as the first positional argument (or as
        the *left* keyword argument).

        .. ACCEPTS: (bottom: float, top: float)

    right : float, optional
        etc.
    """

先頭..はブロックを reST コメントにし、レンダリングされたドキュメントから隠していることに注意してください。.. ACCEPTS:

キーワード引数#

ノート

このセクションの情報は開発チームによって積極的に議論されているため、必要な場合にのみ docstring 補間を使用してください。この補間は既存のドキュメントの一部であるため、このセクションは現在のところ残されています。

Matplotlib は多くのパススルーを使用するためkwargs、たとえば、行を作成するすべての関数 ( plotsemilogx、など) で、新しいユーザーがどれがサポートさsemilogyれているかを知るのが難しい場合があります。kwargsMatplotlib は、docstring 補間スキームを使用して、**kwargs. 要件は次のとおりです。

  1. 単一の構成ポイントであるため、プロパティを変更するために複数のドキュメント文字列を編集する必要はありません。

  2. プロパティが変更されると、ドキュメントが自動的に更新されるように、可能な限り自動化されています。

@_docstring.interpdデコレータはこれを実装します。Line2Dパススルーを受け入れる関数 kwargs( など)は、次のようにプロパティmatplotlib.axes.Axes.plotの概要を一覧表示できます。Line2D

# in axes.py
@_docstring.interpd
def plot(self, *args, **kwargs):
    """
    Some stuff omitted

    Other Parameters
    ----------------
    scalex, scaley : bool, default: True
        These parameters determine if the view limits are adapted to the
        data limits. The values are passed on to `autoscale_view`.

    **kwargs : `.Line2D` properties, optional
        *kwargs* are used to specify properties like a line label (for
        auto legends), linewidth, antialiasing, marker face color.
        Example::

        >>> plot([1, 2, 3], [1, 2, 3], 'go-', label='line 1', linewidth=2)
        >>> plot([1, 2, 3], [1, 4, 9], 'rs', label='line 2')

        If you specify multiple lines with one plot call, the kwargs apply
        to all those lines. In case the label object is iterable, each
        element is used as labels for each set of data.

        Here is a list of available `.Line2D` properties:

        %(Line2D:kwdoc)s
    """

この%(Line2D:kwdoc)構文は、interpdルックアップをArtistという名前のサブクラスにし、そのクラスLine2Dを呼び出します。 サブクラスを内省し、そのプロパティを部分文字列として要約し、docstring に挿入します。artist.kwdocartist.kwdoc

__init__サブクラスとそのプロパティはその時点ではまだ定義されていないため、このスキームはアーティストの装飾には機能しないことに注意してください。代わりに @_docstring.interpd、クラス自体を装飾するために使用できます。その時点でkwdoc、プロパティをリストし、それらを に補間できます __init__.__doc__

docstring の継承#

サブクラスがメソッドをオーバーライドしてもセマンティクスを変更しない場合、子クラスのメソッドに親のドキュメント文字列を再利用できます。サブクラス メソッドに docstring がない場合、Python はこれを自動的に行います。

親ドキュメント文字列を再利用する意図を示すには、プレーンなコメントを使用してください。そうすれば、将来誤って docstring を作成することはありません。# docstring inherited

class A:
    def foo():
        """The parent docstring."""
        pass

class B(A):
    def foo():
        # docstring inherited
        pass

図の追加#

上記のように (図とファイルを含める を参照)、サンプル ギャラリーの図は、図を作成した python スクリプトを指すディレクティブで参照できます。たとえば、docstring はファイルを参照します。.. plot::legendexamples/text_labels_and_annotations/legend.py

"""
...

Examples
--------

.. plot:: gallery/text_labels_and_annotations/legend.py
"""

examples/text_labels_and_annotations/legend.pyは にマッピングされている ことに注意してください。このgallery/text_labels_and_annotations/legend.pyリダイレクトは、将来のドキュメントの再編成で修正される可能性があります。

プロットは、docstring 内に直接配置することもできます。詳細は matplotlib.sphinxext.plot_directiveにあります。簡単な例は次のとおりです。

"""
...

Examples
--------

.. plot::
   import matplotlib.image as mpimg
   img = mpimg.imread('_static/stinkbug.png')
   imgplot = plt.imshow(img)
"""

サンプル スクリプトの参照に対するこのスタイルの利点は、コードがインタラクティブなドキュメント文字列にも表示されることです。

例とチュートリアルを書く#

サンプルとチュートリアルは、Sphinx Gallery/doc/galleryによって実行される Python スクリプトで、それぞれと /doc/tutorialsディレクトリ に画像のギャラリーを作成します。例をプロット生成から除外するには、ファイル名のどこかに「sgskip」を挿入します。

これらのファイルの形式は比較的単純です。適切にフォーマットされたコメント ブロックはReSTテキストとして扱われ、コードが表示され、図がビルドされたページに挿入されます。

たとえば、Simple Plot/examples/lines_bars_and_markers/simple_plot.pyの例は、次のように から生成され ます。

"""
===========
Simple Plot
===========

Create a simple plot.
"""
import matplotlib.pyplot as plt
import numpy as np

# Data for plotting
t = np.arange(0.0, 2.0, 0.01)
s = 1 + np.sin(2 * np.pi * t)

# Note that using plt.subplots below is equivalent to using
# fig = plt.figure and then ax = fig.add_subplot(111)
fig, ax = plt.subplots()
ax.plot(t, s)

ax.set(xlabel='time (s)', ylabel='voltage (mV)',
       title='About as simple as it gets, folks')
ax.grid()
plt.show()

最初のコメント ブロックはReSTテキストとして扱われます。その他のコメント ブロックは、Simple Plotでコメントとしてレンダリングされます。

チュートリアルは、より長く、通常は複数のコメント ブロック (つまり、 クイック スタート ガイド) があることを除いて、まったく同じメカニズムで作成されます。最初のコメント ブロックは、上記の例と同じにすることができます。###ReST テキストの後続のブロックは、文字行で区切られます。

"""
===========
Simple Plot
===========

Create a simple plot.
"""
...
ax.grid()
plt.show()

##########################################################################
# Second plot
# ===========
#
# This is a second plot that is very nice

fig, ax = plt.subplots()
ax.plot(np.sin(range(50)))

このようにして、テキスト、コード、図が「ノートブック」スタイルで出力されます。

その他#

ドキュメントの移動#

ドキュメントを移動または統合することが望ましい場合があります。何もしないと、リンクが機能しなくなる (404) か、ドキュメントの古いバージョンを指すようになります。望ましいのは、古いページを html 更新に置き換えて、ビューアをすぐに新しいページにリダイレクトすることです。したがって、たとえば に移動/doc/topic/old_info.rst/doc/topic/new_info.rstます。削除/doc/topic/old_info.rstして、sphinx に html の更新/リダイレクトを含む古いファイルを引き続き作成するように指示/doc/topic/new_info.rstするディレクティブを挿入します (おそらくファイルの上部近くにあるので、目立つようにするためです)。redirect-from

.. redirect-from:: /topic/old_info

/build/html/topic/old_info.htmlビルドされたドキュメントでは、これにより、更新された html ファイルが生成さ れnew_info.htmlます。2 つのファイルが異なるサブディレクトリにある場合:

.. redirect-from:: /old_topic/old_info2

/build/html/old_topic/old_info2.htmlに(相対的に) 更新された html ファイルが生成され../topic/new_info.htmlます。

このディレクティブには、ドキュメント ルート に相対するフル パスを使用し https://matplotlib.org/stable/ます。その/old_topic/old_info2ため、 のユーザーによって検出されますhttp://matplotlib.org/stable/old_topic/old_info2。わかりやすくするために、相対リンクは使用しないでください。

アニメーションの追加#

アニメーションは Sphinx-gallery によって自動的にスクレイピングされます。これが望ましくない場合はmplgithub 、github アカウントのセットアップに使用されたユーザー名を持つ Matplotlib Google/Gmail アカウントもありますが、Google ドキュメントや Youtube ビデオのホスティングなど、他の目的に使用できます。最初に を使用してアニメーションをムービーとして保存し、次にMatplotlib の Youtube チャンネルmatplotlib.animation.Animation.save()にアップロードして、YouTube が提供する埋め込み文字列を挿入することにより、ドキュメントに Matplotlib アニメーションを埋め込むことができます。

.. raw:: html

   <iframe width="420" height="315"
     src="https://www.youtube.com/embed/32cjc6V0OZY"
     frameborder="0" allowfullscreen>
   </iframe>

ムービーを生成するための保存コマンドの例は次のようになります

ani = animation.FuncAnimation(fig, animate, np.arange(1, len(y)),
    interval=25, blit=True, init_func=init)

ani.save('double_pendulum.mp4', fps=15)

Google ドキュメントの YouTube ビデオを mplgithub アカウントにアップロードするためのログイン パスワードについては、Michael Droettboom にお問い合わせください。

継承図の生成#

クラス継承図は、Sphinx のinheritance-diagramディレクティブで生成できます 。

例:

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
   :parts: 2
matplotlib.patches、matplotlib.lines、matplotlib.text の継承図