MEP12:改进画廊和示例

状态

进度

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

分支和 Pull requests

#1623, #1924, #2181

PR #2474 演示了清理单个示例并将其移动到适当的部分.

摘要

重新组织 matplotlib 绘图画廊将大大简化画廊的导航.此外,应清理和简化示例以提高清晰度.

详细描述

matplotlib 画廊最近被设置为将示例分成几个部分.正如在该 PR [1] 中所讨论的,当前的示例部分( api , pylab_examples )对用户来说并没有太大的用处:画廊中的新部分将帮助用户找到相关的示例.

这些部分也将指导示例的清理:最初,所有当前的示例将保留并列在其当前目录下.随着时间的推移,这些示例可以被清理并移动到新的部分之一.

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

实施

1. 创建新的示例图库部分.[完成]

2. 清理示例并将它们移动到新的示例图库部分(在许多PR的过程中,并在许多用户/开发人员的帮助下).[进行中]

示例图库部分

部分的命名至关重要,并将指导清理工作.当前的部分是:

• 线条,条形和标记(或多或少是一维数据)

• 形状和集合

• 统计图

• 图像,轮廓和场

• 饼图和极坐标图:圆形事物

• 颜色

• 文本,标签和注释

• 刻度和脊柱

• 子图,轴和图形

• 特殊绘图(例如,桑基图,雷达图,龙卷风图)

• 展示(经过调整使其达到出版质量的绘图)

• 工具箱的单独部分(已存在:'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 或类似的检查器)

• 应删除注释掉的代码.

• 用 pyplot (+ numpy 等)替换 pylab 接口的使用.请参阅 c25ef1e

• 删除shebang行,例如:

  #!/usr/bin/env python
  

• 使用一致的导入.特别地:

  import numpy as np
  
  import matplotlib.pyplot as plt
  

  避免从这些模块导入特定的函数(例如 from numpy import sin )

• 每个示例都应侧重于一个特定功能(不包括将显示更多"完善"绘图的 showcase 示例).应删除与该功能无关的调整.请参阅 f7b2217 , e57b5fc 和 1458aa8

pylab 的使用应在专门的帮助页面上进行演示/讨论,而不是在图库示例中.

注意:移动现有示例时,应搜索对该示例的引用.例如, axes.py 和 pyplot.py 的API文档可能会使用这些示例来生成绘图.使用您喜欢的搜索工具(例如,grep,ack, grin , pss )来搜索matplotlib软件包.请参阅 2dc9a46 和 aa6b410

其他建议

• 在示例和API文档之间提供链接(双向),用于使用的methods/objects.(issue #2222 )

• 优先使用 plt.subplots (注意后面的"s")而不是 plt.subplot .

• 重命名示例以阐明其目的.例如, imshow 的最基本演示可能是 imshow_demo.py ,而演示不同插值设置的演示将是 imshow_demo_interpolation.py (而不是 imshow_demo2.py ).

• 拆分尝试做太多的示例.请参阅 5099675 和 fc2ab07

• 删除没有显示任何新内容的示例.

• 一些示例练习了单元测试的深奥功能.这些调整应该从图库中移到位于包根目录下的 unit 目录中的一个示例中.

• 添加绘图标题以明确示例的意图.参见 bd2b13c

向后兼容性

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

替代方案

标签

标记示例还将帮助用户搜索示例图库.虽然标签对于有特定目标的用户来说是一个很大的优势,但绘图图库仍然是这些示例的入口点,并且章节可以真正帮助用户浏览图库.因此,标签是对这种重组的补充.

[1]

matplotlib/matplotlib#714