python - 为什么 CPython 不将 `sphinx.autodoc` 用于标准库？

Question

<分区>

Answer 1

这主要是历史问题，也是个人(和项目)偏好的问题。如今，您可以通过主要依赖文档字符串然后在它们周围添加额外的散文来获得非常有用的文档。

然而，CPython 的文档早于 Sphinx 的存在(事实上，Georg Brandl 编写了 Sphinx 的初始版本以取代 CPython 的旧文档系统)。

因此，作为一项政策，docstrings 和散文文档仍然单独维护，而不依赖于 autodoc 的使用。

我们还不允许在标准库中使用 reStucturedText 文档字符串，这进一步降低了使用 autodoc 的好处。 (参见 PEP 287 问答中的问题 10:http://www.python.org/dev/peps/pep-0287/#questions-answers)

最后，Georg Brandl pointed out CPython 处于一个有点独特的位置，您需要小心确保在 Sphinx 运行时提供文档字符串的标准库版本与您为其生成文档的版本完全相同。很容易不小心引入错误的版本，并且在构建有效的 Python 和能够重新生成文档之间产生强烈的依赖性​​。

在 autodoc 方面，您确实遇到了这样的问题，即在编辑基于 autodoc 的文档时，您无法轻易地看到内联的文档字符串内容，因此很难确保文档字符串文本和附加的散文一起阅读.这个问题可以通过像 http://pymolurus.blogspot.com.au/2012/01/documentation-viewer-for-sphinx.html 这样的自动浏览器刷新解决方案来缓解。

autodoc 在重建依赖性方面也存在问题，因为它不会自动添加对 Python 源文件的正确依赖性。我确实遇到过文档字符串已更改但 Sphinx 没有重新生成相关输出文件的问题。 (我不认为这已得到解决，但如果它在最近的 Sphinx 版本中得到解决，请在评论中告诉我，我将删除此观察结果)。

虽然我认为您可以通过单独维护它们来获得更好的文档和更好的文档字符串(因为这两种书写风格并不完全相同，原始文档字符串通常比纯文本更容易阅读当标记为 reStructuredText 时)，这种方法会带来相当高的额外维护成本，并且会增加不一致的风险。

因此，对于大多数第三方 Python 项目，我的建议实际上是避免遵循标准库的示例，而是:

• 使用 reRestructuredText 文档字符串(参见 PEP 287:http://www.python.org/dev/peps/pep-0287/)
• 使用apidoc/autodoc
• 在自动嵌入的文档字符串周围添加额外的散文文档，而不是作为替代
• 使用上面链接的自动更新方法来查看文档字符串作为文档的一部分的可读性

虽然这不是一个完美的解决方案，但这种方法确实在使文档字符串和散文文档保持最新方面节省了大量重复工作。