MEP10:文档字符串一致性#

状态#

进度

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

分支和 Pull requests#

摘要#

matplotlib 的文档字符串之间存在大量不一致之处.这不仅使文档更难阅读,而且也使贡献者更难,因为他们不知道要遵循哪些规范.应该有一个明确的文档字符串约定,并始终如一地遵循.

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

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

详细描述#

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

Numpy 文档字符串格式#

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

交叉引用#

Most of the docstrings in matplotlib use explicit "roles" when linking to other items, for example: :func:`myfunction`. As of Sphinx 0.4, there is a "default_role" that can be set to "obj", which will polymorphically link to a Python object of any type. This allows one to write `myfunction` instead. This makes docstrings much easier to read and edit as raw text. Additionally, Sphinx allows for setting a current module, so links like `~matplotlib.axes.Axes.set_xlim` could be written as `~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.Axes`)应该用每页一个方法来记录,而较小的类应该将它们的所有方法放在一起.

链接到相关文档的示例#

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

使用 help() 与浏览器查看文档#

在源代码中使用 Sphinx 标记可以在浏览器中获得美观的文档,但这些标记也会使使用 help() 返回的原始文本看起来很糟糕.改进文档字符串的目标之一应该是使访问文档的两种方法都看起来不错.

实施#

  1. 应该为 matplotlib 启用 numpydoc 扩展.一个重要的问题是,这些扩展应该包含在 matplotlib 源代码树中,还是作为依赖项使用.仅仅安装 Numpy 并不足以获得 numpydoc 扩展 -- 它需要单独的安装过程.无论如何,如果它们需要针对我们的需求进行定制,我们应该努力将这些更改提交到上游,而不是分叉它们.

  2. Manually go through all of the docstrings and update them to the new format and conventions. Updating the cross references (from `:func:`myfunc` to `func`) may be able to be semi-automated. This is a lot of busy work, and perhaps this labor should be divided on a per-module basis so no single developer is over-burdened by it.

  3. 使用 autosummary 和 `` sphinx-autogen `` 重新组织 API 文档.这应该对叙述性文档的影响最小.

  4. Modify the example page generator (gen_rst.py) so that it extracts the module docstring from the example and includes it in a non-literal part of the example page.

  5. 使用 sphinx-quickstart 生成一个新的 Sphinx Makefile.当前 make.py 中的以下特性将不得不以其他方式解决:

    • 复制一些静态内容

    • 指定一个"小型"构建(仅适用于示例的低分辨率 PNG 文件)

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

向后兼容性#

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

替代方案#

尚未讨论任何内容.

On this page