我正在开发一个 python 库，我正在使用sphinx.autodoc来生成文档，因为我认为这是一个不要重复自己并且让文档和代码达成一致的好方法。
在sphinx autodoc 对 Emit reStructuredText 的评论中？我了解到“CPython 文档构建过程没有启用自动文档（通过深思熟虑的选择）”。
我想知道为什么 CPython 不使用它，使用它有什么缺点sphinx.autodoc？
问问题
356 次
1 回答
7
这主要是历史问题，也是个人（和项目）偏好的问题。这些天来，您可以通过主要依赖文档字符串，然后在它们周围添加额外的散文来获得非常有用的文档。
然而，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指出CPython 处于一个有点独特的位置，您需要小心确保在 Sphinx 运行时提供文档字符串的标准库版本与您为其生成文档的版本完全相同。意外地引入错误的版本太容易了，并且在拥有有效的 Python 构建和能够重新生成文档之间产生了强烈的依赖关系。
在 autodoc 方面，您确实会遇到这样的问题，即在编辑基于 autodoc 的文档时，您不能轻易地看到内联的 docstring 内容，因此很难确保 docstring 文本和附加的散文一起阅读良好。这个问题可以通过像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
- 围绕自动嵌入的文档字符串添加额外的散文文档，而不是作为替代品
- 使用自动更新方法，例如上面链接的方法，以查看文档字符串作为文档一部分的阅读效果
虽然它不是一个完美的解决方案，但这种方法确实节省了大量的重复工作，以使文档字符串和散文文档保持最新。
于 2012-05-10T04:55:16.883 回答