编写文档#
入门#
通用文件结构#
所有文档都是从 doc/ 构建的。doc/ 目录包含 Sphinx 和 reStructuredText (ReST; .rst) 文件的配置文件，这些文件会被渲染成文档页面。
文档通过三种方式创建。首先，API 文档（doc/api）是通过 Sphinx 从 Matplotlib 库中的类文档字符串创建的。除了 doc/api/api_changes/ 之外，doc/api 中的 .rst 文件是在构建文档时创建的。请参见下面的 编写文档字符串。
其次，我们的示例页面、教程以及部分叙述性文档是由 Sphinx Gallery 创建的。Sphinx Gallery 将示例 Python 文件转换为包含 Matplotlib 绘图调用结果的嵌入图像的 *.rst 文件。请参见下面的 编写示例和教程。
第三，Matplotlib 的叙述性文档是用 ReST 编写的，位于 doc/users/ 的子目录中。如果你想添加新的文档，适合用 .rst 文件而不是图库或教程示例，请选择一个合适的子目录放置它，并将文件添加到该子目录的 index.rst 的目录中。请参见下面的 编写 ReST 页面。
备注
不要直接编辑 doc/plot_types、doc/gallery、doc/tutorials 和 doc/api 中的 .rst 文件（除了 doc/api/api_changes/ 目录下的文件）。Sphinx 在构建文档时会重新生成这些目录中的文件。
设置构建#
Matplotlib 的文档是通过使用 Sphinx 文档生成工具从 reStructuredText (ReST) 生成的。
要构建文档，您需要 为开发设置 Matplotlib。特别注意构建文档所需的 额外依赖项。
构建文档#
文档源文件位于 doc/ 目录中。Sphinx 的配置文件是 doc/conf.py。它控制 Sphinx 解析哪些目录、文档的构建方式以及如何使用扩展。要在 html 格式下构建文档，请进入 doc/ 并运行：
make html
备注
由于文档非常庞大，首次构建可能需要10-20分钟，具体取决于您的机器。后续构建将会更快。
其他有用的调用包括
# Build the html documentation, but skip generation of the gallery images to
# save time.
make html-noplot
# Build the html documentation, but skip specific subdirectories. If a gallery
# directory is skipped, the gallery images are not generated. The first
# time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited
# to add or remove subdirectories
make html-skip-subdirs
# Delete built files. May help if you get errors about missing paths or
# broken links.
make clean
# Build pdf docs.
make latexpdf
SPHINXOPTS 变量默认设置为 -W --keep-going，以构建完整的文档，但如果存在警告，则退出并返回退出状态 1。要取消设置它，请使用
make SPHINXOPTS= html
您可以使用 O 变量来设置附加选项：
make O=-j4 html使用4个进程运行并行构建。make O=-Dplot_formats=png:100 html以低分辨率保存图像。
多个选项可以组合使用，例如 make O='-j4 -Dplot_formats=png:100' html。
在Windows上，将选项设置为环境变量，例如：
set SPHINXOPTS= & set O=-j4 -Dplot_formats=png:100 & make html
显示本地构建的文档#
构建的文档位于文件夹 build/html 中。在默认浏览器中打开它们的快捷方式是：
make show
编写 ReST 页面#
大多数文档要么在单个类和方法的文档字符串中，要么在显式的 .rst 文件中，或者在示例和教程中。所有这些都使用 ReST 语法，并由 Sphinx 处理。
Sphinx reStructuredText 入门 是使用 ReST 的一个很好的介绍。更多完整的信息可以在 reStructuredText 参考文档 中找到。
本节包含有关如何在 Matplotlib 文档中使用 ReST 的附加信息和约定。
格式和样式约定#
在 Matplotlib 文档中追求一致性是有益的。以下是一些使用的格式和风格约定。
章节格式化#
使用 sentence case Upper lower 作为章节标题，例如，Possible hangups 而不是 Possible Hangups。
我们旨在遵循 Python 文档 和 Sphinx reStructuredText 文档 中关于章节标记字符的建议，即：
#带有上划线，用于部分。这在index.rst中保留用于主标题。所有其他页面应从“章节”或更低级别开始。*带有上划线，用于章节=，用于章节-，用于子部分^，用于子子节", 用于段落
这可能尚未在现有文档中一致应用。
表格格式化#
鉴于表格的大小和每个条目的长度，请使用：
小表格 |
大表格 |
|
简短条目 |
||
长条目 |
更多信息，请参见 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.
参考其他文档和章节#
示例：
See the :doc:`/install/index`
See the tutorial :ref:`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`
将给出以下链接：全新安装
为了最大化章节标签和引用的内部一致性，请使用连字符分隔的描述性标签进行章节引用。请记住，内容可能会在以后重新组织，因此除非必要，否则避免在引用中使用像 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。请注意，通常应包含前导点。它告诉Sphinx在整个项目中查找给定的名称。另请参阅 Sphinx: 跨引用Python对象 的解释。
如果有多个代码元素具有相同名称（例如，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
示例目录被 sphinx-gallery 复制到 doc/gallery 中，因此可以使用示例目录中的图表。
.. plot:: gallery/lines_bars_and_markers/simple_plot.py
请注意，这里引用的是生成图表的Python脚本，而不是创建的任何图表。当文档构建时，Sphinx-gallery将提供正确的引用。
用于编写数学表达式的工具#
在大多数情况下，您可能希望使用 Sphinx 的内置数学扩展 之一。在极少数情况下，我们希望文档 html 中的数学文本渲染与 Matplotlib 图形中的数学表达式渲染完全匹配。在这些情况下，您可以使用 matplotlib.sphinxext.mathmpl Sphinx 扩展（另请参阅 书写数学表达式 教程。）
编写文档字符串#
大部分API文档是用docstrings编写的。这些是源代码中的注释块，用于解释代码的工作原理。
备注
文档的某些部分尚未符合当前的文档风格。如有疑问，请遵循此处给出的规则，而不是源代码中可能看到的规则。欢迎提交更新文档字符串以符合当前风格的拉取请求。
所有新的或编辑过的文档字符串应符合 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 文档以了解其呈现方式。
格式约定#
基本的文档字符串约定在 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'.
不要使用 `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 表示可以为任意数字的类型。
使用 (float, float) 来描述一个二维位置。括号应包含在内，以使元组的性质更加明显。
使用 array-like 表示同质数值序列，这通常可以是一个 numpy.array。可以使用 2D、3D、n-dimensional 来指定维度。如果需要用变量表示维度的大小，可以使用括号中的大写字母（(M, N) array-like）。在文本中提到它们时，更容易阅读，不需要特殊格式。如果返回的对象确实是 numpy 数组，则使用 array 而不是 array-like 作为返回类型。
float 是数组类对象的隐式默认数据类型。对于其他数据类型，请使用 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不需要显示完整名称，因为它会链接到该名称。因此，~ 缩短了名称，使其更具可读性。
在文本中使用缩写链接 `.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.
参见 部分#
Sphinx 会自动在 参见 部分的定义块中链接代码元素。无需在那里使用反引号:
See Also
--------
vlines : vertical lines
axhline : horizontal line across the Axes
包装参数列表#
长参数列表应使用 \ 进行换行，并在新行开始时不缩进（不缩进是因为 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` 生成 rcParams["foo"] = 'default'，这是一个指向 matplotlibrc 文件描述的链接。
设置器和获取器#
艺术家属性通过设置和获取方法实现（因为 Matplotlib 早于 Python 的 property 装饰器）。按照惯例，这些设置和获取方法被命名为 set_PROPERTYNAME 和 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, left=None, right=None):
"""
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.
"""
注意，前导的 .. 使得 .. ACCEPTS: 块成为一个 reST 注释，从而在渲染的文档中隐藏它。
关键字参数#
备注
本节中的信息正在开发团队中积极讨论，因此仅在必要时使用文档字符串插值。本节目前保留在原位，因为此插值是现有文档的一部分。
由于 Matplotlib 使用了大量的传递 kwargs，例如在每个创建线条的函数中（plot、semilogx、semilogy 等），新用户可能很难知道哪些 kwargs 是被支持的。Matplotlib 使用了一种文档字符串插值方案来支持对每个接受 **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 查找名为 Line2D 的 Artist 子类，并调用该类上的 artist.kwdoc。 artist.kwdoc 内省子类并将其属性总结为子字符串，该子字符串被插入到文档字符串中。
请注意，此方案不适用于装饰艺术家的 __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:: 指令来引用。例如，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，这一重定向可能在未来的文档重新组织中得到修复。
图表也可以直接放置在文档字符串中。详细信息请参见 matplotlib.sphinxext.plot_directive 。一个简短的例子是：
"""
...
Examples
--------
.. plot::
import matplotlib.image as mpimg
img = mpimg.imread('_static/stinkbug.png')
imgplot = plt.imshow(img)
"""
与引用示例脚本相比，这种风格的一个优点是代码也将出现在交互式文档字符串中。
编写示例和教程#
示例和教程是 Sphinx Gallery 运行的 Python 脚本。Sphinx Gallery 在源目录中找到 *.py 文件并运行这些文件，以在 doc/ 目录的构建位置创建嵌入在 *.rst 文件中的图像和叙述。构建位置中的文件不应直接编辑，因为它们将被 Sphinx Gallery 覆盖。目前 Matplotlib 有四个图库，如下所示：
源位置 |
构建位置 |
|---|---|
|
|
|
|
|
|
|
|
前三个是传统画廊。最后一个，galleries/users_explain，是一个混合画廊，其中一些文件是原始的 *.rst 文件，一些是 *.py 文件；Sphinx Gallery 只是将这些 *.rst 文件从源位置复制到构建位置（参见下面的 画廊中的原始 restructured text 文件）。
在Python文件中，若要排除某个示例生成图表，请在文件名中的某处插入“sgskip”。
这些文件的格式相对简单。正确格式的注释块被视为 ReST 文本，代码会被显示，而图表会被插入到生成的页面中。Matplotlib 使用 # %% 部分分隔符，以便 IDE 能够识别“代码单元”，从而便于重新运行示例的子部分。
例如，线图 示例是从 /galleries/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 文本。其他注释块在 线图 中呈现为注释。
教程是通过完全相同的机制制作的，只不过它们更长，通常有多个注释块（例如 快速入门指南）。第一个注释块可以与上面的示例相同。后续的 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)))
通过这种方式，文本、代码和图形以“笔记本”风格输出。
示例数据#
当样本数据来自公共数据集时，请引用数据来源。样本数据应在代码中写出。当这不可行时，可以使用 cbook.get_sample_data 加载数据。
import matplotlib.cbook as cbook
fh = cbook.get_sample_data('mydata.dat')
如果数据太大而无法包含在代码中，则应将其添加到 lib/matplotlib/mpl-data/sample_data/
创建迷你图库#
展示的 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 引用应始终是第二个提及的；请参见上面的示例。
订单示例#
章节 教程 和 图库 的顺序，以及每个章节内示例的顺序，是通过 /doc/sphinxext/gallery_order.py 中的两步过程确定的：
显式顺序：此文件包含一个章节顺序的文件夹列表和一个子章节顺序的示例列表。文档页面上显示的项目的顺序是这些项目在这些列表中出现的顺序。
隐式顺序：如果一个文件夹或示例不在这两个列表中，它将被附加在显式排序的项目之后，所有这些额外的项目将按路径名（对于部分）或按文件名（对于子部分）排序。
因此，如果你想让你的示例出现在图库中的某个特定位置，请将你的示例添加到这些列表中。如果没有明确顺序的需求，仍然要确保你的示例名称一致，即使用示例的主要功能或主题作为文件名的第一个词；例如，一个图像示例最好命名为类似于 imshow_mynewexample.py。
画廊中的原始 restructured text 文件#
Sphinx Gallery 文件夹通常由一个 README.txt 和一系列 Python 源文件组成，这些文件随后被转换为 index.rst 文件和一系列 example_name.rst 文件在 doc/ 子目录中。然而，Sphinx Gallery 也允许原始的 *.rst 文件通过一个图库传递（参见 Sphinx Gallery 文档中的 手动传递文件）。我们在 galleries/users_explain 中使用了这个功能，例如，galleries/users_explain/colors 是一个常规的 Sphinx Gallery 子目录，但 galleries/users_explain/artists 混合了 *.rst 和 *py 文件。对于这种混合子目录，我们必须将任何 *.rst 文件添加到 :toctree: 中，无论是在 README.txt 中还是在手动 index.rst 中。
示例指南#
示例图库包含了 matplotlib 功能的视觉演示。图库示例的存在是为了让用户可以通过浏览视觉示例来学习。与教程或用户指南不同，图库示例通过演示来教学，而不是通过解释或指导。
图库示例应包含对 演示内容 的简要描述，并在相关时，说明 如何 实现。解释应简明扼要，仅提供理解示例所需的最少上下文。交叉链接相关文档（例如教程、用户指南和API条目），并用相关概念标记示例。
格式#
所有 示例索引 都应遵循这些指南：
- 标题:
用一句话描述内容（约1-6个词）。不要使用*demo*，因为这是示例中隐含的。避免使用如*创建*、制作*等隐含的动词，例如*带注释的热图*优于*创建带注释的热图。当需要动词时，使用一般现在时，例如*填充两条曲线之间的区域*。
- 描述:
在一个简短的段落（大约1-3句话）中描述所展示的可视化技术以及如何使用库的功能来执行该技术，例如 使用 ~Axes.bar 的颜色和标签参数设置条形颜色和条形标签
- Plot:
清晰地展示主题，并在可能的情况下展示边缘案例和不同的应用。虽然图表应该在视觉上吸引人，但优先保持图表的简洁。
- 代码:
编写展示示例重点功能所需的最少内容。当不会提高示例的清晰度时，避免使用自定义样式和注释（标题、图例、颜色等）。
使用简短的注释来描述代码中难以理解的部分。当需要更多上下文或解释时，在代码示例前添加一段文字。
识别艺术家是否相交 展示了视觉示例的要点。这个示例是“杂乱的”，因为它很难分类，但图库是它的正确位置，因为通过视觉搜索找到它是有意义的。
交互式调整色图范围 是一个很好的描述性标题示例，简要总结了如何使用展示的库功能来实现所演示的可视化技术。
带有勾选路径效果的线条 是一个展示功能所需最少代码量的例子。多余的代码缺失使得读者更容易将代码的哪些部分与图形的哪些部分对应起来。
杂项#
移动文档#
有时需要移动或整合文档。如果不采取行动，这将导致链接要么失效（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
在构建的文档中，这将生成一个html文件 /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 inheritance-diagram 指令生成。
示例：
.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
:parts: 2