Matplotlib 项目

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

项目摘要

开源组织：
Matplotlib
技术文档工程师：
brunobeltran
项目名称：
对“隐式”类型的文档进行标准化，提升特征的可检测性
项目时长：
长期投放（5 个月）

Project description

设计初衷

过去，matplotlib 的 API 在很大程度上依赖于字符串即枚举“隐式类型”。除了模仿 matlab 的 API，这些参数字符串还允许用户将语义丰富的值作为参数传递给 matplotlib 函数，而无需明确导入实际枚举值或为实际枚举值添加详细前缀（即，与 plt.plot(x, y, linestyle=mpl.LineStyle.solid) 等内容相比，plt.plot(x, y, linestyle='solid') 更易于输入且冗余性更低）。

此后，许多字符串即枚举的隐式类型都已经发展出了更复杂的功能。例如，linestyle 现在可以是字符串或序列的 2 元组，而 MarkerStyle 现在可以是字符串或 matplotlib.path.Path。虽然许多隐式类型也是如此，但据我所知，MarkerStyle 是唯一一个具有已升级到适当 Python 类状态的 MarkerStyle。

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

虽然这些解决方案对我们来说效果不错，但由于缺少记录每种隐式类型的明确位置，意味着文档通常很难找到，允许值的大型表在整个文档中重复，并且文档中通常完全缺少隐式类型的范围的明确声明。以 plt.plot 文档为例：在“Notes”中，类似 matlab 的格式字符串样式设置方法的说明提及了 linestyle、color 和 markers 选项。传递这三个值的方法还有很多，但对于许多用户来说，这是他们了解这些选项可能使用的值的唯一来源，直到他们偶然发现一个相关教程。我们添加了一个 Line2D 属性表，尝试向读者展示可使用哪些选项来控制其图表。不过，虽然 linestyle 条目在链接至 Line2D.set_linestyle（需要两次点击）时可以很好地链接到描述可能的输入，但 color 和 markers 条目则不然。color 只是与 Line2D.set_color 相关联，但这并不能让您直观地了解允许使用哪些类型的输入。

有人可能会认为，只需清理导致问题的各个文档字符串，即可解决此问题，但遗憾的是，这个问题远远比这更具系统性。如果没有集中位置查找文档，这只会导致我们在使用每种隐式类型的任何位置重复创建越来越详细的文档副本，使初级用户更难找到他们需要的参数。然而，当前的系统迫使用户通过全文的 Wiki 风格遍历或 StackOverflow 示例中的逐条联系，强制用户慢慢地将每种隐式类型的思维模型组合在一起，这一点也是不可持续的。

最终目标

理想情况下，提及隐式类型时应链接到单个页面，该页面描述了该类型可采用的所有可能值，按照从最简单、最常见到最高级或最深奥的顺序进行排序。我们无需在顶级 API 文档中使用宝贵的视觉空间对特定参数的所有可能输入类型进行逐个枚举，然后我们可以使用该空间简单地描述该参数所要控制的绘制抽象化。

再次使用 linestyle 的示例，LineCollection 文档中需要的内容如下：

  1. 此链接指向关于允许的输入（Line2D.set_linestyle 和 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. """"""，其中 LineStyle 类型引用将由 Sphinx 解析，指向关于 Matplotlib 如何处理 linestyle 的单一、权威且完整的文档集。

优势

此方法的一些强大功能包括：

  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

您可以在我们的“课程”中找到本文档的现行版本。