编写文档

开始

通用文件结构

所有文档都是从doc/. 该目录包含渲染到文档页面doc/ 的 Sphinx 和 reStructuredText ( ReST ; ) 文件的配置文件。.rst

文档以三种方式创建。首先，API 文档 ( doc/api) 是Sphinx从 Matplotlib 库中类的文档字符串创建的。除了 doc/api/api_changes/,中的.rst文件doc/api是在构建文档时创建的。请参阅下面的编写文档字符串。

其次， 和 的内容doc/plot_types由doc/gallerySphinx doc/tutorialsGallery从和 中的 python文件plot_types/生成。这些源代码由 Python 脚本组成，它们的注释中内置了ReST文档。请参阅下面的编写示例和教程。examples/tutorials/

第三，Matplotlib在. 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 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 lowerPossible hangupsPossible Hangups

我们的目标是遵循 Python 文档 和Sphinx reStructuredText 文档 中关于部分标记字符的建议，即：

• #带上划线，用于零件。这是为 中的主标题保留的 index.rst。所有其他页面应以“章节”或更低开头。

• *带上划线，用于章节

• =, 对于部分

• -, 对于小节

• ^, 对于小节

• ", 对于段落

这可能尚未在现有文档中一致应用。

函数参数

文档字符串中的函数参数和关键字应该使用*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

为了最大限度地提高章节标签和参考文献的内部一致性，请使用连字符分隔的描述性标签作为章节参考文献。请记住，稍后可能会重新组织内容，因此除非必要，否则请避免在引用中使用顶级名称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`

将呈现为plotor 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

示例目录由 sphinx-gallery 复制到doc/gallery，因此示例目录中的图可以使用

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

请注意，生成绘图的 python 脚本被引用，而不是任何创建的绘图。Sphinx-gallery 将在构建文档时提供正确的参考。

编写文档字符串

大多数 API 文档都是用文档字符串编写的。这些是源代码中的注释块，用于解释代码的工作原理。

笔记

文档的某些部分还不符合当前的文档风格。如有疑问，请遵循此处给出的规则，而不是您在源代码中可能看到的规则。非常欢迎将文档字符串更新为当前样式的拉取请求。

所有新的或编辑的文档字符串都应符合numpydoc 文档字符串指南。上面讨论的大部分ReST语法（编写 ReST 页面）可用于链接和引用。这些文档字符串最终会填充 doc/api目录并形成库的参考文档。

示例文档字符串

一个示例文档字符串如下所示：

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网站还包含大量有关 ReST 标记和一般使用 Sphinx的文档。

格式约定

numpydoc 文档字符串指南 和Sphinx文档中介绍了基本的文档字符串约定。要记住一些特定于 Matplotlib 的格式约定：

报价仓位

单行文档字符串的引号在同一行（pydocstyle D200）：

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

多行文档字符串的引号位于不同的行上（pydocstyle D213）：

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

[...]
"""

函数参数

文档字符串中的函数参数和关键字应该使用*emphasis*角色来引用。这将使 Matplotlib 的文档与 Python 的文档保持一致：

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

不要使用or角色：`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 文档字符串指南约定。以下规则在 numpydoc 约定不具体的情况下对其进行了扩展。

用于float可以是任意数字的类型。

用于描述 2D 位置。应该包括括号以使元组更加明显。(float, float)

用于array-like同质数字序列，通常可以是 numpy.array。可以使用2D, 3D,指定维度n-dimensional。如果您需要使用变量来表示尺寸的大小，请在括号 ( ) 中使用大写字母。在文本中引用它们时，它们更易于阅读，并且不需要特殊格式。如果返回的对象确实是一个 numpy 数组，则使用而不是 返回类型。(M, N) array-likearrayarray-like

float是类似数组的隐式默认 dtype。对于其他 dtypes，请使用.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`在参数类型中使用带有缩写波浪号的完整引用。虽然全名有助于纯文本文档字符串的读者，但 HTML 在链接到它时不需要显示全名。因此，~-shortening 使其更具可读性。

`.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 将解析文档字符串并去除行继续，因此缩进会导致行内出现大量空白）：

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

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

    ...
    """

或者，您可以在文档字符串的专用部分中描述有效参数值。

rcParams

rcParams 可以通过自定义:rc:角色来引用： :rc:`foo`yield ，它是文件描述的链接。rcParams["foo"] = 'default'matplotlibrc

设置器和获取器

Artist 属性是使用 setter 和 getter 方法实现的（因为 Matplotlib 早于 Pythonproperty装饰器）。按照惯例，这些 setter 和 getter 被命名为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.
    """

这导致 or 的输出中出现以下plt.setp(line)行 ：plt.setp(line, "linestyle")

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

在一些罕见的情况下（大多数情况下，setter 同时接受单个元组和未打包的元组），不能以这种方式记录接受的值；在这种情况下，它们可以记录为一个块，例如 ：.. 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:

关键字参数

笔记

开发团队正在积极讨论本节中的信息，因此仅在必要时使用文档字符串插值。本节暂时保留，因为此插值是现有文档的一部分。

由于 Matplotlib 使用了很多 pass-through kwargs，例如，在每个创建一条线的函数中（plot、semilogx、semilogy等），新用户可能很难知道哪些kwargs是支持的。Matplotlib 使用 docstring 插值方案来支持每个函数的文档，该函数需要一个**kwargs. 要求是：

1. 单点配置，因此对属性的更改不需要多个文档字符串编辑。

2. 尽可能自动化，以便随着属性的变化，文档会自动更新。

@_docstring.interpd装饰器实现了这一点。任何接受 Line2Dpass-through 的函数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，并调用artist.kwdoc该类。artist.kwdoc 内省子类并将其属性总结为子字符串，该子字符串被插入到文档字符串中。

请注意，此方案不适用于装饰 Artist's __init__，因为此时尚未定义子类及其属性。相反， @_docstring.interpd可以用来装饰类本身——此时，kwdoc可以列出属性并将它们插入到 __init__.__doc__.

继承文档字符串

如果子类重写了方法但不改变语义，我们可以将父文档字符串重用于子类的方法。如果子类方法没有文档字符串，Python 会自动执行此操作。

使用简单的注释来表示重用父文档字符串的意图。这样我们就不会在将来意外地创建一个文档字符串：# docstring inherited

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

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

添加数字

如上所述（请参阅包括图形和文件），示例库中的图形可以通过指向创建图形的 python 脚本的指令来引用。例如，文档字符串引用了文件：.. 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，可能会在将来重新组织文档时修复的重定向。

绘图也可以直接放在文档字符串中。详细信息在 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 中以及存在于 Axes 或 Figure 中的函数都应提及这两个引用，无论示例代码中使用哪一个。参考pyplot 应该总是第二个提及；见上面的例子。

图库中示例的顺序

教程和示例各部分的顺序以及每个部分中示例的顺序是在以下两步过程中确定的/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并/doc/topic/new_info.rst插入一个redirect-from指令，告诉 sphinx 仍然使用其中的 html 刷新/重定向来制作旧文件（可能靠近文件顶部以使其引人注目）

.. redirect-from:: /topic/old_info

在构建的文档中，这将产生 /build/html/topic/old_info.html一个刷新为new_info.html. 如果这两个文件位于不同的子目录中：

.. redirect-from:: /old_topic/old_info2

将产生一个 html 文件/build/html/old_topic/old_info2.html，该文件具有（相对）刷新到../topic/new_info.html.

使用此指令的完整路径，相对于 https://matplotlib.org/stable/. 用户会/old_topic/old_info2在. http://matplotlib.org/stable/old_topic/old_info2为清楚起见，请勿使用相对链接。

添加动画

动画由 Sphinx-gallery 自动抓取。如果不希望这样做，还有一个带有用户名的 Matplotlib Google/Gmail 帐户，mplgithub 用于设置 github 帐户，但可用于其他目的，例如托管 Google 文档或 Youtube 视频。您可以在文档中嵌入 Matplotlib 动画，方法是首先使用 将动画保存为电影matplotlib.animation.Animation.save()，然后上传到Matplotlib 的 Youtube 频道并插入 youtube 提供的嵌入字符串，例如：

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

请联系 Michael Droettboom 获取登录密码，以将 google docs 的 youtube 视频上传到 mplgithub 帐户。

生成继承图

可以使用 Sphinx 继承图指令生成类继承图。

例子：

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
   :parts: 2

导航栏和样式

Matplotlib 有一些共享相同导航栏和样式的子项目，因此这些子项目集中在 mpl_sphinx_theme作为狮身人面像主题。应在此处对样式或顶部栏进行更改以在所有子项目中传播。