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

Question

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

在从sphinx autodoc发出reStructuredText的评论中？我了解到"CPython docs构建过程没有启用autodoc(通过慎重选择)".

我想知道为什么CPython没有使用它,使用的缺点是sphinx.autodoc什么？

Answer 1

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

然而,CPython的文档很早就存在Sphinx(实际上,Georg Brandl编写了Sphinx的初始版本来取代CPython的旧文档系统).

因此,作为一项政策问题,文档字符串和散文文档仍然是单独维护的,而不依赖于使用autodoc.

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

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

在autodoc方面,你确实遇到这样的问题:在编辑基于autodoc的文档时,你不能轻易地看到内联的文档字符串内容,因此很难确保文档字符串文本和附加的散文一起阅读.可以通过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
• 在自动嵌入的文档字符串周围添加额外的散文文档,而不是替代
• 使用自动更新方法,例如上面链接的方法,看看文档字符串作为文档的一部分读取的程度

虽然这不是一个完美的解决方案,但这种方法确实可以节省相当多的重复工作,使文档字符串和散文文档保持最新.