为什么CPython不使用标准库的“sphinx.autodoc”？ [英] Why is CPython not using `sphinx.autodoc` for the standard library?

问题描述

我正在开发一个python库，我正在使用狮身人面像.autodoc 生成文档，因为我认为这是一个很好的方法，不要重复你自己，并有文档和代码协议。

I am developing a python library and I am using sphinx.autodoc to generate the documentation as I think that this is a good way to don`t repeat yourself and to have documentation and code in agreement.

在对从sphinx autodoc发出reStructuredText的评论？我了解到，CPython文档构建过程没有启用autodoc（由故意选择）。

In a comment to Emit reStructuredText from sphinx autodoc? I learned that "The CPython docs build process doesn't have autodoc enabled (by deliberate choice)".

我想知道为什么CPython不使用它，使用 sphinx.autodoc ？

I am wondering why CPython is not using it and what are the disadvantages of using sphinx.autodoc?

推荐答案

这主要是历史问题，也是个人（和项目）偏好的问题。这些天，您可以通过主要依靠文本字符串获得相当有用的文档，然后再增加附加的散文。

It's mostly a matter of history, but also a question of personal (and project) preference. These days, you can get quite usable docs by relying primarily on docstrings and then maybe adding additional prose around them.

然而，CPython的文档长期以来早于Sphinx的存在事实上，Georg Brandl写了Sphinx的初始版本，以取代CPython的旧文档系统）。

CPython's documentation however, long predates the existence of Sphinx (in fact, Georg Brandl wrote the initial version of Sphinx to replace CPython's old documentation system).

所以，作为政策问题，文档和散文文档仍然保持不需要依赖于使用autodoc。

So, as a matter of policy, the docstrings and the prose documentation are still maintained separately without relying on the use of autodoc.

我们也不要允许在标准库中使用reStucturedText docstrings，这进一步减少了使用autodoc的好处。 （见PEP 287 Q& A： http：/ /www.python.org/dev/peps/pep-0287/#questions-answers ）

We also don't allow the use of reStucturedText docstrings in the standard library which further reduces the benefits of using autodoc. (See Q 10 in the PEP 287 Q & A: http://www.python.org/dev/peps/pep-0287/#questions-answers)

最后，Georg Brandl 指出，CPython处于某种独特的位置，您需要小心确保当Sphinx运行时提供文档字符串的标准库的版本与您生成文档的完全相同。这是非常容易的意外导致错误的版本，以及创建一个强大的依赖关系，有一个工作的Python构建，并能够重新生成文档。

Finally, Georg Brandl pointed out that CPython is in a somewhat unique position that you need to be careful to ensure that the version of the standard library that is providing the docstrings when Sphinx runs is the exact same one you're generating the documentation for. It would be far too easy to accidentally bring in the wrong version, as well as creating a strong dependency between having a working Python build and being able to regenerate the documentation.

在autodoc方面，您确实有问题：编辑基于自动头文的文档时，您不能轻松地查看docstring内容，因此可能很难确保文本字符串文本和附加散文一起阅读。通过自动浏览器刷新解决方案可以减轻这个问题，例如 http ：//pymolurus.blogspot.com.au/2012/01/documentation-viewer-for-sphinx.html

On the autodoc side, you do have the problem that when editing autodoc-based documentation, you can't easily see the docstring contents inline, so it can be difficult to make sure the docstring text and the additional prose read well together. That problem can be mitigated through an automatic browser refresh solution like http://pymolurus.blogspot.com.au/2012/01/documentation-viewer-for-sphinx.html

autodoc也有依赖关系的问题对于重建，因为它不会自动添加对Python源文件的正确依赖。我确实有一些问题，其中docstrings已经改变，但Sphinx没有重新生成相关的输出文件。 （我不相信这已经解决了，但是如果在最近的Sphinx版本中解决了这个问题，让我在评论中知道，我会删除这个观察）。

autodoc also has a problem with dependencies on rebuilds, since it doesn't automatically add the right dependencies on the Python source files. I've definitely had issues where the docstrings have changed but Sphinx didn't regenerate the relevant output files. (I don't believe this has been fixed, but if it's been resolved in more recent Sphinx releases let me know in the comments and I'll remove this observation).

虽然我认为通过维护它们分开来更好地获得文档文档（因为两种写作风格不完全相同，而且原始的文本字符串比普通文本更容易阅读，而不是标记时）使用reStructuredText），这是一种方法，额外的维护工作成本相当高，并且增加了不一致的风险。

While I think you get better documentation and better docstrings by maintaining them separately (because the two writing styles aren't exactly the same and raw docstrings are generally easier to read as plain text than they are when marked up with reStructuredText), it's an approach that comes with rather high costs in additional maintenance effort and an increased risk of inconsistency.

因此，对于大多数第三方Python项目，我的建议实际上是避免遵循标准库的示例，而是：

Accordingly, for most third party Python projects, my advice would actually be to avoid following the standard library's example and instead:

• 使用reRestructuredText docstrings（请参阅PEP 287： http://www.python.org/dev/peps/pep-0287/ ）


• 使用apidoc / autodoc


• 添加其他p玫瑰文档自动嵌入的文档字符串而不是替换


• 使用自动更新方法，如上面链接，查看文档读取作为一部分的一部分文件

• use reRestructuredText docstrings (see PEP 287: http://www.python.org/dev/peps/pep-0287/)
• use apidoc/autodoc
• add additional prose documentation around the automatically embedded docstrings rather than as a substitute
• use an autoupdating approach such as that linked above to see how well the docstrings read as part of the documentation

虽然这不是一个完美的解决方案，但这种方法 保存了相当多的重复努力文件和散文都是最新的。

While it's not a perfect solution, this approach does save quite a bit of duplicated effort in keeping both docstrings and prose documentation up to date.

这篇关于为什么CPython不使用标准库的“sphinx.autodoc”？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！