为什么 CPython 不使用 `sphinx.autodoc` 作为标准库？ [关闭]

Question

我正在开发一个 python 库，并且我正在使用sphinx.autodoc 来生成文档，因为我认为这是一个很好的方式，不要重复自己并且让文档和代码达成一致。

在对Emit reStructuredText from sphinx autodoc? 的评论中，我了解到“CPython 文档构建过程没有启用自动文档（有意选择）”。

我想知道为什么 CPython 不使用它，使用sphinx.autodoc 的缺点是什么？

Answer 1

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

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

因此，作为一项政策，文档字符串和散文文档仍然分开维护，而不依赖于使用 autodoc。

我们也不允许在标准库中使用 reStucturedText 文档字符串，这进一步降低了使用 autodoc 的好处。 （参见 PEP 287 Q & A 中的 Q 10：http://www.python.org/dev/peps/pep-0287/#questions-answers）

最后，Georg Brandl pointed out CPython 处于一个有点独特的位置，您需要小心确保在 Sphinx 运行时提供文档字符串的标准库版本与您生成的完全相同的文档。意外地引入错误的版本太容易了，并且在拥有一个正常工作的 Python 构建和能够重新生成文档之间产生了强烈的依赖关系。

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

autodoc 对重建的依赖也有问题，因为它不会自动在 Python 源文件上添加正确的依赖。我确实遇到了文档字符串发生更改但 Sphinx 没有重新生成相关输出文件的问题。 （我不相信这个问题已经得到解决，但如果它在最近的 Sphinx 版本中得到解决，请在 cmets 中告诉我，我会删除这个观察结果。

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

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

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

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