MEP12:改进图库和示例¶
状态¶
Progress
1.3中增加了初始变更。画廊的改建正在进行中。2015年9月29日-最后一次 pylab_examples
在哪里? pylab
导入的已转换为使用 matplotlib.pyplot
和 numpy
.
详细描述¶
Matplotlib绘图示例最近成立,将示例拆分为多个部分。如该公关中所述 [1], 当前示例部分 (api
, pylab_examples
)对用户不是非常有用:图库中的新部分将帮助用户找到相关示例。
这些部分还将指导对示例的清理:最初,所有当前示例将保留并列在其当前目录下。随着时间的推移,这些示例可以被清理并移到新的部分中。
此过程允许用户轻松识别需要清理的示例,即 api
和 pylab_examples
目录。
实施¶
- 创建新的库分区。 [Done]
- 清理示例并将其移动到新的图库部分(在许多PRS过程中,在许多用户/开发人员的帮助下)。 [在进行中]
绘图示例部分¶
分区的命名非常关键,将指导清理工作。当前部分包括:
- 线条、条形图和标记(或多或少是一维数据)
- 形状和集合
- 统计图
- 图像、轮廓和场
- 饼图和极坐标图:圆形
- 颜色
- 文本、标签和注释
- 小技巧
- 子图、轴和图形
- 专业图(如桑基、雷达、龙卷风)
- Showcase(带有调整的绘图,使其成为出版物质量)
- 工具箱的单独部分(已经存在:“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! """
应删除注释掉的代码。
替换使用
pylab
interface withpyplot
(+numpy
, etc.). See c25ef1e移除 shebang 线,例如:
#!/usr/bin/env python
使用一致的导入。特别地:
import numpy as np
import matplotlib.pyplot as 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
( notimshow_demo2.py
) - 把做得太多的例子分开。见 5099675 和 fc2ab07
- 删除不显示任何新内容的示例。
- 一些例子练习单元测试的深奥特性。这些调整应该从库中移到
unit
目录位于包的根目录中。 - 添加绘图标题以澄清示例的意图。见 bd2b13c