ドキュメントの作成#
はじめに#
一般的なファイル構造#
すべてのドキュメントは、doc/
. このディレクトリには、ドキュメント ページに表示されるdoc/
Sphinx および reStructuredText ( ReST ; ) ファイルの構成ファイルが含まれています。.rst
ドキュメントは 3 つの方法で作成されます。まず、API ドキュメント ( ) は、Matplotlib ライブラリ内のクラスのドキュメント文字列からSphinxdoc/api
によって作成されます。を除き
、 のファイルはドキュメントのビルド時に作成されます。以下の docstring の記述を参照してください。doc/api/api_changes/
.rst
doc/api
次に、と のコンテンツはdoc/plot_types
、doc/gallery
と
のPython ファイルからSphinx ギャラリーdoc/tutorials
によって生成されます。これらのソースは、 ReSTドキュメントがコメントに組み込まれている Python スクリプトで構成されています。以下の例とチュートリアルの作成を参照してください。plot_types/
examples/
tutorials/
第三に、Matplotlib にはReSTで記述されたナラティブ ドキュメントが のサブディレクトリにあり
doc/users/
ます。ギャラリーやチュートリアルの例ではなく、ファイルに適した新しいドキュメントを追加する場合は.rst
、それを配置する適切なサブディレクトリを選択し、サブディレクトリの目次にファイルを追加しますindex.rst
。以下の ReST ページの作成を参照してください
。
ノート
、
、、および
( を除く) の.rst
ファイルを直接編集しないでください。Sphinxは、ドキュメントのビルド時にこれらのディレクトリにファイルを再生成します。doc/plot_types
doc/gallery
doc/tutorials
doc/api
doc/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 html
4 つのプロセスで並列ビルドを実行します。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 lower
Possible hangups
Possible
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.
他のドキュメントやセクションの参照 #
: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`
他のパッケージも 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/gallery
examples ディレクトリは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-like
array
array-like
float
array-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_PROPERTYNAME
and と
名付けられてい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
、たとえば、行を作成するすべての関数 ( plot
、semilogx
、など) で、新しいユーザーがどれがサポートさsemilogy
れているかを知るのが難しい場合があります。kwargs
Matplotlib は、docstring 補間スキームを使用して、**kwargs
. 要件は次のとおりです。
単一の構成ポイントであるため、プロパティを変更するために複数のドキュメント文字列を編集する必要はありません。
プロパティが変更されると、ドキュメントが自動的に更新されるように、可能な限り自動化されています。
@_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.kwdoc
artist.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::
legend
examples/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)))
このようにして、テキスト、コード、図が「ノートブック」スタイルで出力されます。
スフィンクスギャラリーのリファレンス#
紹介されている Matplotlib 関数は、次のように下部の警告にリストされている必要があります。
###############################################################################
#
# .. admonition:: References
#
# The use of the following functions, methods, classes and modules is shown
# in this example:
#
# - `matplotlib.axes.Axes.fill` / `matplotlib.pyplot.fill`
# - `matplotlib.axes.Axes.axis` / `matplotlib.pyplot.axis`
これにより、sphinx-gallery は、言及された関数のミニギャラリーに例へのエントリを配置できます。ここで機能について言及するかどうかは、ミニギャラリーのリンクがその機能を説明するのに際立って役立つかどうかに応じて決定する必要があります。matplotlib.pyplot.subplots
たとえば、サブプロットのレイアウトに関する例でのみ言及し、それを使用するすべての例で言及するわけではありません。
pyplot
Axes または Figure と同様に存在する関数は、コード例でどちらが使用されているかに関係なく、両方の参照に言及する必要があります。pyplot
参照は常に 2 番目に言及する必要があります。上記の例を参照してください。
ギャラリー内の例の順序#
チュートリアルと例のセクションの順序、および各セクション内の例の順序は、 内の 2 つのステップ プロセスで決定されます/doc/sphinxext/gallery_order.py
。
明示的な順序: このファイルには、セクション順序のフォルダーのリストと、サブセクション順序の例のリストが含まれています。ドキュメント ページに表示される項目の順序は、それらの項目がそれらのリストに表示される順序です。
暗黙的な順序: フォルダーまたは例がこれらのリストにない場合、明示的に順序付けられた項目の後に追加され、それらの追加項目はすべてパス名 (セクションの場合) またはファイル名 (サブセクションの場合) で順序付けられます。
結果として、例をギャラリーの特定の位置に表示したい場合は、それらのリストを例で拡張します。明示的な順序が望まれない、または必要でない場合でも、例に一貫した名前を付けることを確認してください。つまり、メイン関数または例の主題をファイル名の最初の単語として使用します。たとえば、画像の例は理想的には のような名前にする必要がありimshow_mynewexample.py
ます。
その他#
ドキュメントの移動#
ドキュメントを移動または統合することが望ましい場合があります。何もしないと、リンクが機能しなくなる (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