MEP10: 文档字符串一致性#

状态#

进展

这仍然是一个正在进行的工作

分支和拉取请求#

摘要#

matplotlib 的文档字符串之间存在大量不一致性。这不仅使得文档更难阅读，而且对贡献者来说也更困难，因为他们不知道应该遵循哪些规范。应该有一个明确的文档字符串约定，并且要一致地遵循。

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

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

详细描述#

自从 matplotlib 开始使用 Sphinx 以来，出现了许多新的工具和约定，使得生活更加轻松。以下是建议对文档字符串进行的更改列表，其中大多数涉及这些新功能。

Numpy 文档字符串格式#

Numpy 文档字符串格式: 这种格式将文档字符串划分为清晰的章节，每个章节都有不同的解析规则，使得文档字符串在作为原始文本和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 中的许多方法使用 *args 和 **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 签名。

链接而非复制#

许多文档字符串包含在加载时通过插入内容到文档字符串中来接受的关键字的长列表。这使得文档字符串非常长。此外，由于这些表格在许多文档字符串中是相同的，它在文档中插入了大量冗余信息——特别是在打印版本中，这是一个特别的问题。

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

autosummary 扩展#

应使用 Sphinx 的 autosummary 扩展来生成摘要表，这些表链接到单独的文档页面。一些拥有许多方法的类（例如 Axes）应按每个方法一个页面进行文档化，而较小的类应将其所有方法放在一起。

链接到相关文档的示例#

这些示例虽然有助于说明如何使用某个功能，但并未链接到相关的文档字符串。可以通过在示例中添加模块级别的文档字符串来解决这个问题，然后在示例页面的解析内容中包含该文档字符串。这些文档字符串可以轻松地包含对文档其他部分的引用。

使用 help() 与浏览器进行文档对比#

在源代码中使用 Sphinx 标记可以在浏览器中生成美观的文档，但这种标记也使得通过 help() 返回的原始文本看起来很糟糕。改进文档字符串的目标之一应该是使这两种访问文档的方式都看起来美观。

实现#

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

  2. 手动检查所有的文档字符串，并将它们更新为新的格式和约定。更新交叉引用（从 `:func:`myfunc` 到 `func`）可能可以半自动化完成。这是一项繁重的工作，或许应该按模块分配，以避免单个开发者负担过重。

  3. 使用 autosummary 和 sphinx-autogen 重新组织 API 文档。希望这能对叙述性文档产生最小的影响。

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

  5. 使用 sphinx-quickstart 生成一个新的 Sphinx Makefile。当前 make.py 中的以下功能将需要以其他方式处理：

    • 复制一些静态内容

    • 指定一个“小型”构建（仅包含低分辨率的PNG文件作为示例）

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

向后兼容性#

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

替代方案#

尚未讨论。

On this page