Matplotlib 项目

本页面包含 Google 文档季接受的技术写作项目的详细信息。

项目摘要

开源组织：
Matplotlib
技术文档工程师：
brunobeltran
项目名称：
通过标准化“隐式”类型的文档来提高功能的可检测性
项目时长：
长期（5 个月）

Project description

设计初衷

过去，matplotlib 的 API 严重依赖于字符串即枚举“隐式类型”。除了模仿 matlab 的 API 之外，这些参数字符串还允许用户将富含语义的值作为参数传递给 matplotlib 函数，而无需仅为了传递基本绘图选项而明确导入或冗长地为实际枚举值添加前缀（即 plt.plot(x, y, linestyle='solid') 比 plt.plot(x, y, linestyle=mpl.LineStyle.solid) 更易于输入且更少冗余）。

这些将字符串用作枚举的隐式类型中的许多类型后来都演变出了更复杂的功能。例如，linestyle 现在可以是字符串，也可以是序列的 2 元组，MarkerStyle 现在可以是字符串，也可以是 matplotlib.path.Path。虽然许多隐式类型都存在这种情况，但 MarkerStyle（据我所知）是唯一已升级为适当 Python 类的类型。

由于这些隐式类型本身并不是类，因此 Matplotlib 过去不得不推出自己的解决方案来集中对这些隐式类型的文档和验证（例如，分别使用 docstring.interpd.update 文档字符串插值模式和 cbook._check_in_list 验证器模式），而不是使用 Python 类提供的标准工具链（例如，验证文档字符串和 __init__ 模式）。

虽然这些解决方案对我们来说非常有效，但缺少用于记录每种隐式类型的明确位置意味着文档往往难以找到，在整个文档中重复使用包含允许值的大表格，并且通常文档中完全缺少隐式类型的范围的显式声明。以 plt.plot 文档为例：在“备注”中，对类似于 Matlab 的格式字符串样式设置方法的说明中提到了 linestyle、color 和 markers 选项。传递这三个值的方式比提示的方法要多得多，但对于许多用户来说，这是他们了解这些选项可能值的唯一来源，直到他们偶然看到某个相关教程。其中包含一个 Line2D 属性表，目的是向读者显示可用于控制图表的选项。不过，虽然 linestyle 条目很好地链接到了 Line2D.set_linestyle（需要点击两次），其中描述了可能的输入，但 color 和 markers 条目却没有。color 只是链接到 Line2D.set_color，无法提供任何关于允许哪些类型的输入的直观信息。

有人可能会说，只需整理导致问题的个别 docstring 即可解决此问题，但遗憾的是，这个问题远比这更系统化。如果没有集中查找文档的位置，这只会导致我们越来越多地复制越来越详尽的文档，并在每次使用这些隐式类型的每个位置重复这些文档，这会让新手用户更难找到他们所需的参数。不过，当前的系统也不可持续，因为它迫使用户通过在我们的文档中以 Wiki 方式浏览或从 StackOverflow 示例中零散地学习，慢慢拼凑出对每个隐式类型的心理模型。

最终目标

理想情况下，提及任何隐式类型时，都应链接到单个页面，该页面会说明该类型可以采用的所有可能的值，并按照从最简单、最常见到最高级或深奥的顺序排列。这样一来，我们就可以使用顶级 API 文档中宝贵的视觉空间，以分块方式枚举特定参数的所有可能输入类型，而不是使用相同的空间来用简单的文字描述该参数要控制的绘图抽象。

再次使用 linestyle 示例，我们在 LineCollection 文档中需要的只是：

  1. 指向有关允许的输入的完整文档的链接（Line2D.set_linestyle 和线条样式教程中的文档组合）。
  2. 用简单的文字说明该参数的用途。对于 matplotlib 高级用户，这从参数名称中就可以看出来，但对于新用户来说，情况并非如此。

在实际的 LineCollection 文档中，这将如下所示：python """""" linestyles: `LineStyle` or list thereof, default: :rc:`lines.linestyle` ('-') A description of whether the stroke used to draw each line in the collection is dashed, dotted or solid, or some combination thereof. """"""其中，Sphinx 会解析 LineStyle 类型引用，以指向一组权威且完整的文档，其中介绍了 Matplotlib 如何处理线条样式。

优势

这种方法的一些强大功能包括

  1. 以纯文本形式清晰显示每个功能的全部功能（无需点击）。
  2. 将默认选项设为可见（无需点击）。看到默认选项通常足以唤起回访用户的记忆。
  3. 提供“最常用”和“最简单”选项的完整说明，以便在浏览时（只需点击一下）即可轻松找到参数。
  4. 只需“向下滚动”即可查看更多高级选项（只需点击一下），从而轻松发现更强大的功能和输入法。
  5. 提供一种集中的策略，用于将顶级“API”文档与相关“教程”相关联。
  6. 避免 API 文档爆炸，即扫描每个参数的许多可能选项会导致单个文档注释难以使用。

与当前文档相比，这种方法的其他优势包括：

  1. 由于集中化的原因，文档不太可能过时。
  2. 规范了目前必须通过阅读代码学习的 matplotlib 的许多“隐式标准”（例如“边界”与“范围”是什么）。
  3. 该流程会突出显示 API 一致性问题，使之通过 GitHub 问题跟踪器更轻松地进行跟踪，从而帮助改进我们的 API。
  4. 由于需要解析的文本量大幅减少，文档构建时间缩短。

实现

上述改进需要两项主要工作，对于这方面的工作，一名专门的技术文档工程师将非常有用。第一种方法是为每种隐式类型创建一个集中式“教程”页面。这需要与核心开发者团队合作，确定一组具体的隐式类型，其文档对用户来说非常有用（通常是因为这些类型包含我们库的强大隐藏功能，而这些功能的文档目前只能在很难找到的入门教程中找到）。然后，我会针对每种隐式类型，将各种相关教程、API 文档和示例页面整合到一个权威文档来源中，该来源可链接到引用特定类型的任何位置。

完成给定隐式类型的集中式文档后，我们将开始第二项主要工作：将现有 API 文档替换为指向新文档的链接，以便使用 Python 的内置 help() 实用程序的用户和在线浏览我们文档的用户都能尽可能轻松地实际使用这些新文档。

虽然此处提议的文档的确切格式可能会随着此项目的推进而发生变化，但我与 Matplotlib 核心团队在每周的“开发者通话”期间合作，共同达成了共识，即此处提出的策略是开始记录这些“隐式类型”时最便捷、最实用且在技术上最易于处理的方法（提供了关于这些调用的说明）。在为每个隐式类型创建集中式文档的初始阶段，我将使用现有的“教程”基础架构，这样我就可以像这样轻松引用这些页面，而无需创建任何新的公共类（再次以 LineCollection 文档为例）：

""""""
linestyles: LineStyle or list thereof, default: :rc:`lines.linestyle` ('-')
    A description of whether the stroke used to draw each line in the collection
    is dashed, dotted or solid, or some combination thereof. For a full
    description of possible LineStyle's, see :doc:`tutorials/types/linestyle`.
""""""

今后，一旦核心开发者团队就将我们的新“类型”文档纳入真正的 Python 类的最佳长期策略达成共识（例如我在 Matplotlib 增强提案 30 中提出的），我们就可以轻松更改这些引用的拼写方式。

最后，我建议在此 Google 文档季期间记录的隐式类型的初步列表如下：

  1. capstyle
  2. joinstyle
  3. bounds
  4. extents
  5. linestyle
  6. colors/lists of colors
  7. colornorm/colormap
  8. tick formatters

您可以在我们的 Discourse 论坛上找到本文档的最新版本。