docutils和Sphinx之间有什么关系？

Question

Python文档工具似乎有很多种，其中我遇到的另一个是epydoc。因为它用于生成官方Python文档，所以Sphinx似乎是事实上的标准。请问有人能够帮我梳理一下当前Python文档工具的现状吗？

- allyourcode

---

当前状态是什么意思？你能详细说明一下吗？Sphinx需要docutils；epydoc可以使用相同的RST标记。你想知道什么？你能更具体一些吗？ - S.Lott

哪些工具有强大的社区支持和活跃的开发？是否有现成的解决方案，还是有很多没有明显更大的追随者？ - allyourcode

也许你应该编辑一下这个问题的标题。 - Étienne

Answer 1

epydoc和Sphinx是不同类型的工具。

它们相同之处在于：

• 都使用docutils通过ReST。
• 都非常注重Python。
• 都可以生成HTML和PDF文档。

它们的关注点不同。

• Epydoc专注于API（开发人员）文档。您可以更快地获得更多结果。您将其指向源代码，然后就会得到结果。这是我从API文档工具中想要的。
• Sphinx专注于一般（用户）文档。虽然Sphinx确实从源代码中提取了很多信息，但您需要投入更多的精力。Sphinx可以生成API文档，但不像Epydoc那样直截了当，而且在我看来做得不如Epydoc好。我知道有些人会因为Sphinx是Python而持不同意见。但是，这取决于您想要投入多少工作和要记录的内容。

因此，这取决于您想要投入多少工作以及您要记录的内容。

- Paul Hildebrandt

---

感谢您解释这些工具的共同点（例如它们与docutils的关系）以及它们之间的区别。是什么使epydoc更适合API文档，而Sphinx更适合功能文档？您提到它们都使用reST。看起来有很多重叠。这只是方便的问题吗？此外，epydoc的开发似乎不太活跃。最后一次提交是在2009年2月，最后一次在devel列表上的通信是在2009年5月。 - allyourcode

简单来说，为什么一个人在某个方面比另一个人更擅长的原因是因为他们的设计方式不同。Epydoc 只是从代码中提取信息，而 Sphinx 则是从你编写的 ReST 文件中生成大部分文档。两者有很多重叠之处。Sphinx 是新生力量。我听说在 .7 版本中，它将具有更好的自动生成功能。我非常尊重 Epydoc，但 Sphinx 看起来现在拥有所有的动力。我喜欢它，因为它看起来像 python.org 的文档，而且我认为它看起来更好。 - Paul Hildebrandt

Sphinx不专注于一般用户文档。Sphinx是一种帮助您编写完整详细文档的工具，而这是通过连接Docstrings无法实现的。此外，Sphinx将支持1.0所谓的域，使您能够记录使用多种语言编写的项目，例如使用Python、JavaScript和C编写的Web应用程序。 - DasIch

我正想请教一下Sphinx如何生成API文档，然后我发现了你的这篇帖子。sphinx.ext.autodoc，真是太棒了。谢谢。 - muhuk

Answer 2

我最近从Python2切换到Python3，发现Python3没有Epydoc包。因此，Python3似乎明确关注使用Sphinx作为API文档。

- MrLeeh

Answer 3

看起来Epydoc已经死了，或者至少在渴望着“峡湾”。

使用sphinx-apidoc命令和autodoc扩展的Sphinx似乎是目前API文档中最受欢迎的选择。

好的例子有：

• requests (src)
• boto (src)

参见：应该使用Epydoc、Sphinx还是其他工具来记录Python API？（SO5579198）

Sphinx鼓励使用比javadoc模式中的工具更加叙述化的样式，但这也许是一件好事呢？

- cbare