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

问题描述

我正在开发python库，并且正在使用 sphinx .autodoc 生成文档，因为我认为这是避免重复自己并使文档和代码保持一致的好方法。

在< a href = https://stackoverflow.com/q/10377576/1301710>从sphinx autodoc发出reStructuredText吗？我了解到" CPython文档构建过程未启用自动文档功能（通过我故意想知道为什么CPython没有使用它，以及使用 sphinx.autodoc ？

解决方案

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

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

因此，从政策上讲，文档字符串和散文文档仍然保留

我们也不允许允许在标准库中使用reStucturedText文档字符串，这进一步减少了使用autodoc的好处。 （请参阅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也存在依赖项问题on rebuilds，因为它不会自动在Python源文件上添加正确的依赖项。我确实遇到了文档字符串已更改的问题，但Sphinx并未重新生成相关的输出文件。 （我不认为此问题已得到解决，但是如果在最新的Sphinx版本中已解决此问题，请在评论中告知我，我将删除此观察结果。）

虽然我认为您可以通过分别维护它们来获得更好的文档和文档字符串（因为这两种书写方式并不完全相同，并且原始文档字符串通常比标记时更容易以纯文本格式阅读） （使用reStructuredText），这种方法会带来较高的额外维护成本，并增加了不一致的风险。

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

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


• 使用apidoc / 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.

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)".

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'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).

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

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)

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.

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 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).

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.

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

• 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屋！