我正在开发一个python库，我正在使用sphinx.autodoc生成文档，因为我认为这是一个不要重复自己并且文档和代码达成一致的好方法。
在对Emit reStructuredText from sphinx autodoc?的评论中，我了解到“CPython docs构建过程没有启用autodoc（通过慎重选择）”。
我想知道为什么CPython没有使用它以及使用sphinx.autodoc有什么缺点？
答案 0 :(得分：6)
这主要是历史问题，也是个人（和项目）偏好的问题。现在，你可以通过主要依赖于文档字符串来获得非常有用的文档，然后可以在它们周围添加额外的散文。
然而，CPython的文档很早就存在Sphinx（实际上，Georg Brandl编写了Sphinx的初始版本来取代CPython的旧文档系统）。因此，作为一项政策问题，文档字符串和散文文档仍然是单独维护的，而不依赖于使用autodoc。
我们不允许在标准库中使用reStucturedText文档字符串，这进一步降低了使用autodoc的好处。 （参见PEP 287 Q＆amp; A：http://www.python.org/dev/peps/pep-0287/#questions-answers中的问题10）
最后，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项目，我的建议实际上是避免遵循标准库的示例而是：
虽然这不是一个完美的解决方案，但这种方法 可以节省相当多的重复工作，使文档字符串和散文文档保持最新。