文档风格指南#

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

也可以看看

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

说明性语言#

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

术语#

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

学期

描述

正确的

不正确

Figure

用于编程的 Matplotlib 工作空间。

  • 对于 Matplotlib 对象：图，“图是视觉的工作空间。

  • 参考类： Figure，“ Figure 提供视觉效果的方法。”

  • 通用语言：figure，“Michelle Kwan 是著名的花样滑冰运动员。”

  • “人物是视觉的工作空间。”

  • “图中的方法提供了视觉效果。”

  • “ Figure 四腿锁是摔跤动作。”

Axes

图内的子图。包含绘图元素并负责绘制和配置其他详细信息。

  • 对于 Matplotlib 对象：轴，“轴是图中的子图。”

  • 提到类： Axes，“每个 Axes都特定于一个图”。

  • 通用语言：斧头，“伐木工和伐木工都用斧头砍木头。” 或“三个轴上的坐标没有标准名称。” （轴的复数）

  • “轴方法转换数据。”

  • “每个 Axes都特定于一个人物。”

  • “舞台上的音乐家称他们的吉他为 Axes。”

  • “轴相交的点是坐标系的原点。”

Artist

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

  • 对于 Matplotlib 对象：艺术家，“艺术家显示视觉效果，并且是渲染图形时的可见元素。”

  • 提到 class : Artist，“每个 Artist 都有各自的方法和功能。”

  • 通用语言：艺术家，“博物馆里的艺术家来自法国。”

  • “用各自的方法配置传奇艺术家。”

  • “图表中有一个 Artist 用于该视觉的东西。”

  • “有些艺术家只是偶然成名。”

Axis

人类可读的一维参考标记对象，包含刻度、刻度标签、脊椎和边缘。

  • 对于 Matplotlib 对象：轴，“条形图的轴是单独的艺术家。” （复数，Axis 对象）

  • 参考类： Axis，“ Axis 包含各自的 XAxis 和 YAxis 对象。”

  • 通用语言：axis，“围绕固定轴的旋转是旋转运动的一种特殊情况。”

  • “将图形绘制到轴上。”

  • “每个轴通常以沿其测量的坐标命名。”

  • “在某些计算机图形环境中，纵坐标 Axis可能是向下的。”

显式的面向对象编程 (OOP)

Matplotlib 中的显式编程方法。

  • 显式

  • 明确的

  • 面向对象

  • 面向对象

  • OO风格

隐式， pyplot

Matplotlib 中带pyplot模块的隐式编程方法。

  • 隐式

  • 隐含的

  • pyplot

  • 像MATLAB

  • pyplot

  • pyplot 接口

语法#

主题#

使用第二人称祈使句来指定动作的定向指令。第二人称代词用于特定于个人的上下文和所有格指代。

正确的

不正确

pip 使用 Python安装程序从源目录安装 Matplotlib 。根据您的操作系统，您可能需要额外的支持。

您可以从源目录安装 Matplotlib。如果您在安装时遇到问题，您可以找到额外的支持。

紧张#

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

正确的

不正确

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

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

声音#

写主动句。被动语态最适合与警告提示相关的情况或条件。

正确的

不正确

该函数plot生成图形。

该图由 plot函数生成。

如果没有参数，函数将返回错误消息。

如果没有参数，您将看到来自函数的错误消息。

句子结构#

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

正确的

不正确

Matplotlib 中的pyplot模块是函数的集合。这些功能创建、管理和操作当前图形和绘图区域。

Matplotlib 中的pyplot模块是创建、管理和操作当前图形和绘图区域的函数的集合。

该plot函数将数据绘制到相应的轴上。轴对应于相应的图。

该plot函数在其各自的轴内为各自的图形绘制数据。

隐式方法是生成简单绘图的便捷捷径。

希望有方便的快捷方式来生成绘图的用户使用隐式方法。

格式化#

以下指南指定了如何合并代码并为 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])

重构文本#

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
===========  ===========

其他资源#

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