docutils 和 Sphinx 之间有什么关系？

Question

Python 似乎有很多文档工具。我遇到的另一个是 epydoc。看起来 Sphinx 是事实上的标准，因为它用于生成官方 Python 文档。有人可以帮我整理一下 Python 文档工具的当前状态吗？

Answer 1

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

它们的相同之处在于：

• 都通过 ReST 使用/docutils.sourceforge.net/" rel="nofollow noreferrer">docutils。
• 两者的重点都非常 Pythonic
• 都可以生成 HTML 和 PDF 文档

他们的重点不同。

• Epydoc 专注于 API（开发人员）文档。使用 Epydoc，您可以更快地获得更多结果。你把它指向你的源代码，你就会得到一些东西。这就是我想要的 API 文档工具。
• Sphinx 专注于一般（用户）文档。虽然 Sphinx 确实从源代码中提取了大量信息，但您需要在其中添加更多信息。 Sphinx 可以生成 API 文档，但是它并不那么简单，而且 IMO 的表现不如 Epydoc。我知道有些人会不同意，因为 Sphinx 是为 Python 选择的。但是，这取决于您想投入多少工作。我确实喜欢 Sphinx 的一般文档。

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

Answer 2

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

Answer 3

看起来Epydoc即使没有死，至少也对峡湾充满了渴望。

使用 sphinx-apidoc 命令和 autodoc 扩展看起来是目前最流行的 API 文档选项。

很好的例子是：

• 请求 (src)
• boto (src)

请参阅：我们应该使用 Epydoc、Sphinx 还是其他东西来记录 Python API？ (SO5579198)

Sphinx 鼓励比 javadoc 模式中的工具更具叙事性的风格，但这也许是一件好事？