文档风格指南#

本指南包含 Matplotlib 文档的语言和格式的最佳实践.

参见

有关贡献的更多信息,请参阅 编写文档 部分.

说明性语言#

对于解释性写作,以下指南适用于清晰简洁的语言使用.

术语#

Matplotlib 中有几个关键术语,它们是文档可靠性和一致性的标准.它们不可互换.

术语

描述

正确

不正确

Figure

Matplotlib 用于编程的工作空间.

  • 对于 Matplotlib 对象:Figure,"Figure 是视觉对象的工作空间."

  • 引用类:Figure,"Figure 中的方法提供了视觉效果."

  • 通用语言:figure,"Michelle Kwan 是一位著名的花样滑冰运动员."

  • "figure 是视觉对象的工作空间."

  • "figure 中的方法提供了视觉效果."

  • "Figure 四字锁是一种摔跤动作."

Axes

Figure 中的子图.包含绘图元素,负责绘制和配置其他细节.

  • 对于 Matplotlib 对象:Axes,"Axes 是 Figure 中的一个子图."

  • 引用类:Axes,"每个 Axes 都是特定于一个 Figure 的."

  • 通用语言:axes,"伐木工和樵夫都用 axes 砍树."或者"三个坐标轴中没有坐标的标准名称."(axis 的复数)

  • "axes 方法转换数据."

  • "每个 Axes 都是特定于一个 Figure 的."

  • "舞台上的音乐家称他们的吉他为 Axes."

  • "Axes 相交的点是坐标系的原点."

Artist

显示视觉效果的各种 Matplotlib 对象.

  • 对于 Matplotlib 对象:Artist,"Artist 显示视觉效果,并且是渲染 Figure 时的可见元素."

  • 参考类:Artist,"每个 Artist 都有各自的方法和函数."

  • 通用语言:艺术家,"博物馆里的艺术家来自法国."

  • "使用其各自的方法配置图例 artist."

  • "在图中,该视觉效果有一个 Artist."

  • "有些 Artist 是偶然成名的."

Axis

人类可读的单维度参考标记对象,包含刻度,刻度标签,轴脊和边缘.

  • 对于 Matplotlib 对象:Axis,"条形图的 Axis 是一个单独的 Artist." (复数,Axis 对象)

  • 参考类:Axis,"Axis 包含各自的 XAxis 和 YAxis 对象."

  • 通用语言:轴,"绕固定轴旋转是旋转运动的一个特例."

  • "将图形绘制到轴上."

  • "每个 Axis 通常以沿其测量的坐标命名."

  • "在某些计算机图形环境中,纵坐标 Axis 可以向下定向."

Axes 接口

调用 Axes 和 Figure (有时还有其他 Artist) 对象上的方法来配置绘图的使用模式.

  • Axes 接口

  • 调用 Axes / Figure 对象上的方法

  • 显式接口

  • 面向对象

  • OO 风格

  • OOP

pyplot 接口

仅调用 pyplot 函数来配置绘图的使用模式.

  • pyplot 接口

  • 调用 pyplot 函数

  • 隐式接口

  • 类似 MATLAB

  • Pyplot

语法#

主语#

对于指定操作的指令,使用第二人称祈使句.第二人称代词用于特定于个人的上下文和所有格引用.

正确

不正确

使用 Python pip 安装程序从源目录安装 Matplotlib.根据您的操作系统,您可能需要其他支持.

您可以从源目录安装 Matplotlib.如果您在安装时遇到问题,可以找到其他支持.

时态#

对于解释,使用现在一般时.尽可能避免将来时和其他情态或助动词.

正确

不正确

Matplotlib 用于可视化的基本思想涉及获取数据并通过函数和方法对其进行转换.

Matplotlib 将获取数据并通过函数和方法对其进行转换.它们可以生成多种视觉效果.这些将是使用 Matplotlib 的基础.

语态#

用主动句书写.被动语态最适合用于与警告提示相关的场景或条件.

正确

不正确

函数 plot 生成图形.

该图形由 plot 函数生成.

如果没有参数,该函数将返回一条错误消息.

如果没有参数,您将看到该函数发出一条错误消息.

句子结构#

使用主语-谓语-宾语的顺序编写简短的句子.限制句子中的并列连词.避免代词引用和从属连词短语.

正确

不正确

Matplotlib 中的 pyplot 模块是函数的集合.这些函数创建,管理和操作当前的 Figure 和绘图区域.

Matplotlib 中的 pyplot 模块是函数的集合,这些函数创建,管理和操作当前的 Figure 和绘图区域.

plot 函数将数据绘制到各自的 Axes.Axes 对应于各自的 Figure.

plot 函数在其各自的 Axes 中为其各自的 Figure 绘制数据.

隐式方法是生成简单绘图的便捷快捷方式.

希望拥有用于生成绘图的便捷快捷方式的用户使用隐式方法.

格式化#

以下指南指定了如何合并代码以及如何为 Matplotlib 文档使用适当的格式.

代码#

Matplotlib 是一个 Python 库,并遵循相同的文档标准.

注释#

Python 代码示例在代码之前或在同一行有注释.

正确

不正确

 
# Data
years = [2006, 2007, 2008]

years = [2006, 2007, 2008]
# Data

years = [2006, 2007, 2008]  # Data

输出#

当使用 .py 文件在示例中使用 Matplotlib 生成视觉效果时,使用 matplotlib.pyplot.show 显示视觉效果.保持文档清晰,避免 Python 输出行.

正确

不正确

 
plt.plot([1, 2, 3], [1, 2, 3])
plt.show()

plt.plot([1, 2, 3], [1, 2, 3])

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 2, 3])
fig.show()

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 2, 3])

reStructuredText#

Matplotlib 使用 reStructuredText 标记进行文档编写.Sphinx 帮助将这些文档转换为适当的格式,以实现可访问性和可见性.

列表#

无序列表适用于不需要排序的项目.编号列表专门用于按确定的顺序执行操作.

正确

不正确

该示例使用了三个图表.

该示例使用了三个图表.

  • 条形图

  • 折线图

  • 饼图

  1. 条形图

  2. 折线图

  3. 饼图

以下四个步骤可以帮助您开始使用 Matplotlib.

以下步骤对于开始使用 Matplotlib 非常重要.

  1. 导入 Matplotlib 库.

  2. 导入必要的模块.

  3. 设置并分配要处理的数据.

  4. 使用方法和函数转换数据.

  • 导入 Matplotlib 库.

  • 导入必要的模块.

  • 设置并分配要处理的数据.

  • 使用方法和函数转换数据.

表格#

使用带有 reStructuredText 标准的 ASCII 表格来组织内容.Markdown 表格和 csv-table 指令不被接受.

正确

不正确

正确

不正确

正确

不正确

 
| Correct | Incorrect |
| ------- | --------- |
| OK      | Not OK    |

+----------+----------+
| Correct  | Incorrect|
+==========+==========+
| OK       | Not OK   |
+----------+----------+

.. csv-table::
   :header: "correct", "incorrect"
   :widths: 10, 10

   "OK   ", "Not OK"

===========  ===========
  Correct     Incorrect
===========  ===========
OK           Not OK
===========  ===========

其他资源#

本风格指南不是一个全面的标准.有关如何为文档做出贡献的更完整的参考,请参见下面的链接.这些资源包含编写文档的常见最佳实践.

On this page