MEP10:DocString一致性¶
摘要¶
matplotlib在docstrings之间有很大的不一致性。这不仅使文档更难阅读，而且对贡献者来说也更难阅读，因为他们不知道要遵循哪种规范。应该有一个始终遵循的清晰的docstring约定。
API文档的组织结构很难遵循。有些页面，如Pyplot和Axes，非常庞大，很难浏览。相反，应该有链接到详细文档的简短摘要表。此外，一些文档字符串本身相当长，包含冗余信息。
构建文档需要很长时间，并使用 make.py 脚本而不是生成文件。
详细描述¶
自从matplotlib开始使用Sphinx以来，有许多新的工具和约定可供使用，使生活更容易。下面列出了对docstring的建议更改，其中大多数都涉及到这些新特性。
numpy docstring格式¶
Numpy docstring format: 这种格式将docstring分为清晰的部分，每个部分都有不同的解析规则，使docstring既可以作为原始文本也可以作为HTML阅读。我们可以考虑替代方案，或者自己发明，但这是一个强有力的选择，因为它在 Numpy/Scipy 的社区中得到了很好的使用和理解。
交叉引用¶
Matplotlib中的大多数docstring在链接到其他项时使用显式的“角色”，例如： :func:`myfunction '.从sphinx 0.4开始，有一个“默认角色”可以设置为“obj”，它将以多态方式链接到任何类型的python对象。这允许一个人写 `myfunction 相反。这使得docstring作为原始文本更容易读取和编辑。另外，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)
"""
斯芬克斯无法解析这一点，而且在原始文本中相当冗长。从狮身人面像1.1开始，如果 autodoc_docstring_signature 配置值设置为true，sphinx将从docstring的第一行提取替换签名，允许这样做：
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签名。
链接而不是复制¶
许多docstring都包含了通过在加载时将内容插入docstring而获得的长的关键字列表。这使得docstrings非常长。此外，由于这些表在许多docstring中是相同的，所以它在docs中插入了大量冗余信息，特别是在打印版本中。
对于仅用于帮助的函数，应将这些表移动到docstrings。引用这些表的docstring应该链接到它们，而不是逐字包含它们。
自动摘要扩展¶
sphinx autosummary扩展应该用于生成摘要表，该表链接到单独的文档页。一些类有许多方法（例如 Axes ）应该用每页一个方法来记录，而较小的类应该把它们的所有方法放在一起。
链接到相关文档的示例¶
这些示例虽然有助于说明如何使用功能，但不会链接回相关的docstring。这可以通过向示例中添加模块级的docstring来解决，然后将该docstring包含在示例页面的已解析内容中。这些文档字符串可以很容易地包含对文档任何其他部分的引用。
使用help（）与浏览器的文档¶
在源代码中使用sphinx标记允许在浏览器中使用美观的文档，但该标记还使使用help（）返回的原始文本看起来很糟糕。改进docstring的目的之一应该是使访问docs的两种方法看起来都很好。
实施¶
- 应为Matplotlib打开NumpyDoc扩展。有一个重要的问题，是应该将它们包括在matplotlib源树中，还是作为依赖项使用。安装numpy不足以获得numpydoc扩展——这是一个单独的安装过程。在任何情况下，只要它们需要为我们的需求进行定制，我们就应该努力向上游提交这些更改，而不是将其转发。
- 手动浏览所有文档字符串，并将其更新为新的格式和约定。更新交叉引用（从
`:func:`myfunc到`func`）可能是半自动化的。这是一项非常繁忙的工作，也许应该根据每个模块来划分这项工作，这样就不会有单个开发人员被它负担过重。 - 使用AutoSummary和
sphinx-autogen. 希望这对叙述性文档的影响最小。 - 修改示例页生成器 (
gen_rst.py）以便它从示例中提取模块docstring，并将其包含在示例页面的非文本部分中。 - 使用
sphinx-quickstart生成一个新样式的sphinx makefile。当前的以下功能make.py必须以其他方式解决：- 复制某些静态内容
- 指定“小”版本（示例中仅使用低分辨率PNG文件）
步骤1、2和3相互依赖。4和5可以独立完成，尽管5依赖于3。