MEP12：改进图库和示例#

状态 #

进步

1.3 中添加的初始更改。画廊的改造正在进行中。2015 年 9 月 29 日 - 最后一个导入的pylab_examples地方pylab已转换为使用matplotlib.pyplot和numpy.

分支和拉取请求 #

#1623、#1924、#2181

PR #2474 演示了一个正在清理并移动到适当部分的示例。

摘要 #

重新组织 matplotlib 绘图库将大大简化图库的导航。此外，为了清楚起见，应该清理和简化示例。

详细说明 #

matplotlib 库最近设置为将示例分成多个部分。正如 PR [ 1 ]中所讨论的，当前的示例部分 ( api, pylab_examples) 对用户来说并不是非常有用：图库中的新部分将帮助用户找到相关示例。

这些部分还将指导示例的清理：最初，所有当前示例将保留并列在其当前目录下。随着时间的推移，这些示例可能会被清理并移至新部分之一。

此过程允许用户轻松识别需要清理的示例；即api和pylab_examples 目录中的任何内容。

实施 #

创建新的画廊部分。[完毕]
清理示例并将它们移动到新的图库部分（在许多 PR 的过程中并在许多用户/开发人员的帮助下）。[进行中]

画廊部分 #

部分的命名至关重要，将指导清理工作。当前的部分是：

线、条和标记（或多或少的一维数据）
形状和集合
统计图
图像、轮廓和字段
饼图和极坐标图：圆形的东西
颜色
文本、标签和注释
蜱和刺
子图、轴和图形
专业图（例如，sankey、雷达、龙卷风）
展示（经过调整以使其具有出版质量的情节）
工具箱的单独部分（已经存在：'mplot3d'、'axes_grid'、'units'、'widgets'）

这些名字肯定有待商榷。随着这些部分的增长，我们应该重新评估它们并在必要时将它们分开。

清理指南 #

api画廊的和部分中的当前示例pylab_examples将保留在这些目录中，直到它们被清理。清理后，他们将被转移到上述新画廊部分之一。“清理”应包括：

sphinx-gallery docstrings：示例的标题和描述，格式如下，位于示例的顶部：

"""
===============================
Colormaps alter your perception
===============================

Here I plot the function

.. math:: f(x, y) = \sin(x) + \cos(y)

with different colormaps. Look at how colormaps alter your perception!
"""

PEP8清理（强烈建议运行flake8或类似的检查器）
应删除注释掉的代码。
用（+等）替换pylab接口的使用。见c25ef1e pyplotnumpy
删除 shebang 行，例如：

#!/usr/bin/env python
使用一致的导入。尤其是：

将 numpy 导入为 np

将 matplotlib.pyplot 导入为 plt

避免从这些模块导入特定功能（例如）from numpy import sin
每个示例都应侧重于特定功能（不包括 showcase示例，这些示例将显示更多“抛光”图）。应该删除与该功能无关的调整。参见 f7b2217、 e57b5fc和1458aa8

pylab应该在专门的帮助页面而不是图库示例上演示/讨论使用。

注意：移动现有示例时，您应该搜索对该示例的引用。例如，API 文档 axes.py可能pyplot.py会使用这些示例来生成绘图。使用您最喜欢的搜索工具（例如，grep、ack、grin、pss）来搜索 matplotlib 包。见2dc9a46 和aa6b410

其他建议 #

为使用的方法/对象提供示例和 API 文档之间的链接（双向）。（问题＃2222）
plt.subplots优先使用（注意尾随“s”）而不是plt.subplot.
重命名示例以阐明其目的。例如，最基本的演示imshow可能是imshow_demo.py，演示不同插值设置的演示是 imshow_demo_interpolation.py( not imshow_demo2.py )。
拆分那些试图做太多事情的例子。见5099675 和fc2ab07
删除不显示任何新内容的示例。
一些示例为单元测试使用了深奥的功能。这些调整应该从库中移出到 unit位于包根目录中的目录中的示例。
添加情节标题以阐明示例的意图。见bd2b13c

向后兼容性 #

每个 Matplotlib 版本的网站都很容易访问，因此想要参考旧示例的用户仍然可以这样做。

替代方案 #

标签 #

标记示例还将帮助用户搜索示例库。尽管标签对于有特定目标的用户来说是一个巨大的胜利，但情节图库仍将是这些示例的入口点，而部分可以真正帮助用户浏览图库。因此，标签是对这种重组的补充。