文档风格指南

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

参见

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

说明性语言

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

术语

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

术语	描述	正确	不正确
|图|	Matplotlib 编程工作空间。	对于 Matplotlib 对象：Figure，“Figure 是视觉的工作空间。” 引用类: Figure, "Figure 中的方法提供了视觉效果。" 通用语言: 人物, "关颖珊是一位著名花样滑冰运动员。"	figure 是用于视觉元素的工作空间。 图中的方法提供了视觉效果。 Figure 四腿锁是一种摔跤动作。
|轴|	图中的子图。包含绘图元素，并负责绘图和配置附加细节。	对于 Matplotlib 对象: Axes, "Axes 是 Figure 中的一个子图。" 引用类: Axes, "每个 Axes 都特定于一个 Figure。" 通用语言: 轴, "伐木工和伐木工人都使用斧头来砍木头。" 或 "三个轴的坐标没有标准名称。" (axis 的复数)	轴方法转换数据。 每个 Axes 都是特定于一个 Figure 的。 舞台上的音乐家们称他们的吉他为 Axes。 坐标轴相交的点是坐标系的原点。
|艺术家|	显示视觉效果的 Matplotlib 对象种类繁多。	对于 Matplotlib 对象：Artist，“Artists 显示视觉效果，并且在渲染 Figure 时是可见的元素。” 引用类: Artist , "每个 Artist 都有相应的方法和功能。" General language: 艺术家, "博物馆里的艺术家来自法国。"	使用其相应的方法配置图例艺术家。 图表中有一个 Artist 用于那个视觉元素。 一些艺术家仅凭偶然机会成名。
|轴|	包含刻度、刻度标签、脊线和边缘的易读的单维对象。	对于 Matplotlib 对象: 轴, "条形图的轴是一个独立的艺术家。" (复数, 轴对象) 引用类: Axis, "Axis 包含相应的 XAxis 和 YAxis 对象。" 通用语言: 轴, "绕固定轴旋转是旋转运动的一个特例。"	将图形绘制到轴上。 每个轴通常以其所测量的坐标命名。 在某些计算机图形学的上下文中，纵坐标 Axis 可能向下方向。
Axes 接口	在 Axes 和 Figure（有时还有其他 Artist）对象上调用方法以配置图表的使用模式。	Axes 接口 在 Axes / Figure 对象上调用方法	显式接口 面向对象 OO-风格 面向对象编程
pyplot 接口	仅调用 pyplot 函数来配置图形的用法模式。	pyplot 接口 调用 pyplot 函数	隐式接口 MATLAB 类似 Pyplot

语法

主题

使用第二人称祈使句来指定需要执行的动作。第二人称代词用于个人特定的上下文和所有格引用。

正确	不正确
使用 Python 的 pip 安装程序从源目录安装 Matplotlib。根据您的操作系统，您可能需要额外的支持。	你可以从源代码目录安装 Matplotlib。如果你在安装过程中遇到问题，可以寻求额外的支持。

紧张

使用一般现在时进行解释。尽可能避免使用将来时和其他情态或助动词。

正确	不正确
Matplotlib 用于可视化的基本思想涉及获取数据并通过函数和方法对其进行转换。	Matplotlib 将通过函数和方法处理数据并进行转换。它们可以生成多种视觉图形。这些将是使用 Matplotlib 的基础。

语音

使用主动句式。被动语态最适合用于与警告提示相关的情境或条件。

正确	不正确
函数 plot 生成图表。	图表由 plot 函数生成。
如果没有参数，函数将返回一条错误消息。	如果没有参数，你将会从函数中看到一个错误信息。

句子结构

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

正确	不正确
Matplotlib 中的 pyplot 模块是一组函数。这些函数用于创建、管理及操作当前的图形和绘图区域。	Matplotlib 中的 pyplot 模块是一组函数，用于创建、管理并操作当前的图形和绘图区域。
plot 函数将数据绘制到相应的 Axes 上。Axes 对应于相应的 Figure。	plot 函数在其各自的 Figure 中为其各自的 Axes 绘制数据。
隐式方法是生成简单图形的便捷快捷方式。	希望为生成图表提供便捷快捷方式的用户使用隐式方法。

格式化

以下指南规定了如何在Matplotlib文档中整合代码并使用适当的格式。

代码

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

注释

Python 代码示例中，注释可以在代码之前或同一行。

正确	不正确
# Data years = [2006, 2007, 2008]	years = [2006, 2007, 2008] # Data
years = [2006, 2007, 2008] # Data

输出

在使用 Matplotlib 生成视觉内容时，通过在示例中使用 .py 文件，使用 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 帮助将这些文档转换为适合访问和可见的格式。

• reStructuredText 规范

• 快速参考文档

列表

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

正确	不正确
该示例使用了三个图表。	该示例使用了三个图表。
酒吧 行 派	酒吧 行 派
这四个步骤有助于开始使用 Matplotlib。	以下步骤对于开始使用 Matplotlib 非常重要。
导入 Matplotlib 库。 导入必要的模块。 设置并分配要处理的数据。 通过方法和函数转换数据。	导入 Matplotlib 库。 导入必要的模块。 设置并分配要处理的数据。 通过方法和函数转换数据。

表格

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

正确	不正确
正确 不正确 好的 不 OK	| 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 =========== ===========

附加资源

本风格指南不是一个全面的规范。关于如何更全面地为文档做出贡献，请参见以下链接。这些资源包含了编写文档的常见最佳实践。

• Python 开发者指南

• Google 开发者风格指南

• IBM 风格指南

• Red Hat 风格指南