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

但是，CPython的文档早于Sphinx的存在（事实上，Georg Brandl编写了Sphinx的初始版本以替代CPython的旧文档系统）。

因此，从政策上讲，文档字符串和散文文档仍然单独维护，而不依赖于使用autodoc。

我们也 不会 允许这进一步降低了使用车博士的好处标准库使用reStucturedText文档字符串的。（请参阅PEP
287问题与解答中的问题10：http : //www.python.org/dev/peps/pep-0287/#questions-
answers）

最后，Georg Brandl指出CPython处于某种独特的位置，您需要小心确保在Sphinx运行时提供文档字符串的标准库版本与您为其生成文档的版本完全相同。意外地引入错误的版本，以及在具有有效的Python构建和能够重新生成文档之间建立强烈的依赖关系，这太容易了。

在自动文档方面，您确实存在一个问题，即在编辑基于自动文档的文档时，无法轻松地内联查看文档字符串内容，因此很难确保文档字符串文本和其他散文可以很好地阅读。可以通过自动浏览器刷新解决方案（例如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
• 在自动嵌入的文档字符串 周围 添加其他散文文档 ， 而不是替代
• 使用自动更新的方法（如上面链接的方法）来查看文档字符串作为文档一部分的阅读情况

尽管这不是一个完美的解决方案，但是在保持文档字符串和散文文档均为最新时，这种方法 确实 节省了很多重复的工作。