为什么不CPython的使用`sphinx.autodoc`的标准库？ [关闭](Why is

我正在开发一个Python库，我使用sphinx.autodoc ，因为我认为这是不`吨重复自己，并在协议文档和代码的好方法生成的文档。

在注释从狮身人面像车博士散发出新结构化？我了解到，“CPython的文档生成过程没有启用车博士（通过深思熟虑的选择）”。

我很奇怪，为什么CPython的不使用它，什么是使用的缺点sphinx.autodoc ？

它主要是一个历史问题，也是个人（和项目）偏好的问题。这些天来，你可以通过对主要依靠文档字符串，然后可能增加额外的散文周围变得非常有用的文档。

CPython的文档但是，远远早狮身人面像的存在（实际上，乔治·布兰德写道狮身人面像最初的版本替换CPython的旧文件系统）。

所以，作为一个政策问题，文档字符串和散文文档仍然分别不依赖于使用车博士的维护。

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

最后，乔治·布兰德指出的是CPython的是，你必须要小心，以确保所提供狮身人面像时运行文档字符串的标准库的版本是你生成的文档同一个确切有点独特的地位。这将是太容易不小心把错版，以及具有一个工作Python构建和能够再生的文档之间建立一个很强的依赖性。

在车博士的一面，你必须将问题编辑基于车博士的文档时，你不能轻易看到的文档字符串内容内嵌，所以它可能难以确保文档字符串和文本阅读以及共同附加的散文。这个问题可以通过像自动刷新浏览器的解决方案来缓解http://pymolurus.blogspot.com.au/2012/01/documentation-viewer-for-sphinx.html

车博士还与重建相关性的问题，因为它不会自动添加在Python源文件的权限依赖性。我肯定有其中的文档字符串已经改变，但狮身人面像没有重新生成相关输出文件的问题。（我不相信这一点已得到修复，但如果它在最近的狮身人面像的版本已经解决了，让我知道在评论，我会删除此观察）。

虽然我觉得你单独维护他们获得更好的文档和更好的文档字符串（因为这两种写作风格不完全相同，原始文档字符串通常更容易比他们用新结构化标记的时候阅读纯文本），它是一种方法附带额外的维护工作相当高的成本和不一致的风险增加。

因此，对于大多数第三方Python项目，我的建议实际上是为了避免以下标准库的榜样，而不是：