MEP10：文档字符串一致性#

状态#

进步

这仍然是一项持续的努力

分支和拉取请求#

摘要#

matplotlib 在文档字符串之间有很多不一致的地方。这不仅使文档更难阅读，而且对贡献者来说也更难，因为他们不知道要遵循哪些规范。应该有一个清晰的文档字符串约定，并始终遵循。

API 文档的组织很难遵循。有些页面，例如 pyplot 和 axes，非常庞大且难以浏览。相反，应该有链接到详细文档的简短汇总表。此外，一些文档字符串本身很长并且包含冗余信息。

构建文档需要很长时间并且使用make.py 脚本而不是 Makefile。

详细说明#

自从 matplotlib 开始使用 Sphinx 以来，有许多新工具和约定可以让生活更轻松。以下是对文档字符串的提议更改列表，其中大部分涉及这些新功能。

Numpy 文档字符串格式#

Numpy docstring 格式：这种格式将 docstring 分成清晰的部分，每个部分都有不同的解析规则，使 docstring 易于作为原始文本和 HTML 阅读。我们可以考虑替代方案，或者发明我们自己的方案，但这是一个强有力的选择，因为它在 Numpy/Scipy 社区中得到了很好的使用和理解。

交叉引用#

matplotlib 中的大多数文档字符串在链接到其他项目时都使用明确的“角色”，例如：:func:`myfunction`. 从 Sphinx 0.4 开始，有一个“default_role”可以设置为“obj”，它将多态链接到任何类型的 Python 对象。这允许人们改写`myfunction`。这使得文档字符串更容易作为原始文本阅读和编辑。此外，Sphinx 允许设置当前模块，因此链接`~matplotlib.axes.Axes.set_xlim` 可以写为`~axes.Axes.set_xlim`.

覆盖签名#

matplotlib 中的许多方法使用*argsand**kwargs语法来动态处理函数接受的关键字参数，或者委托给另一个函数。但是，这通常不能用作文档中的签名。出于这个原因，许多 matplotlib 方法包括以下内容：

def annotate(self, *args, **kwargs):
    """
    Create an annotation: a piece of text referring to a data
    point.

    Call signature::

      annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)
    """

这不能被 Sphinx 解析，并且在原始文本中相当冗长。从 Sphinx 1.1 开始，如果autodoc_docstring_signature配置值设置为 True，Sphinx 将从文档字符串的第一行提取替换签名，允许这样做：

def annotate(self, *args, **kwargs):
    """
    annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)

    Create an annotation: a piece of text referring to a data
    point.
    """

显式签名将替换生成文档​​中的实际 Python 签名。

链接而不是复制#

许多文档字符串通过在加载时将内容插入到文档字符串中来包含一长串接受的关键字。这使得文档字符串很长。此外，由于这些表在许多文档字符串中都是相同的，因此它在文档中插入了大量冗余信息——尤其是印刷版中的一个问题。

这些表应该移动到仅用于帮助的函数的文档字符串中。引用这些表的文档字符串应该链接到它们，而不是逐字包含它们。

自动摘要扩展#

Sphinx 自动摘要扩展应该用于生成摘要表，该表链接到单独的文档页面。一些具有许多方法的类（例如Axes）应该在每页记录一个方法，而较小的类应该将它们的所有方法放在一起。

链接到相关文档的示例#

这些示例虽然有助于说明如何使用功能，但不要链接回相关的文档字符串。这可以通过将模块级文档字符串添加到示例中来解决，然后将该文档字符串包含在示例页面上的已解析内容中。这些文档字符串可以很容易地包含对文档任何其他部分的引用。

使用 help() 与浏览器的文档

在源代码中使用 Sphinx 标记可以让您的浏览器中的文档看起来很漂亮，但标记也会使使用 help() 返回的原始文本看起来很糟糕。改进文档字符串的目标之一应该是使两种访问文档的方法看起来都不错。

实施#

  1. 应该为 matplotlib 打开 numpydoc 扩展。有一个重要的问题是这些是否应该包含在 matplotlib 源代码树中，或者用作依赖项。安装 Numpy 不足以获得 numpydoc 扩展——它是一个单独的安装过程。无论如何，如果它们需要根据我们的需求进行定制，我们应该努力将这些更改提交到上游而不是分叉它们。

  2. 手动浏览所有文档字符串并将它们更新为新的格式和约定。更新交叉引用（从 `:func:`myfunc`到`func`）可能是半自动化的。这是一项繁重的工作，也许这项工作应该按模块划分，因此没有一个开发人员会因此而负担过重。

  3. 使用自动摘要和sphinx-autogen. 希望这对叙述文档的影响最小。

  4. 修改示例页面生成器 ( gen_rst.py)，使其从示例中提取模块文档字符串并将其包含在示例页面的非文字部分中。

  5. 用于sphinx-quickstart生成新样式的 Sphinx Makefile。当前的以下功能make.py必须以其他方式解决：

    • 复制一些静态内容

    • 指定“小”构建（仅用于示例的低分辨率 PNG 文件）

步骤 1、2 和 3 是相互依赖的。4 和 5 可以独立完成，尽管 5 对 3 有一定的依赖性。

向后兼容性#

由于这主要涉及文档字符串，因此对向后兼容性的影响应该很小。

替代方案#

尚未讨论。