docutils和Sphinx有什么关系？

Question

看起来有很多用于Python的文档工具。我遇到的另一个工具是epydoc。Sphinx似乎是行业标准，因为它被用来生成官方的Python文档。有人能帮我理清一下现在Python的文档工具都有哪些吗？

Answer 1

看起来Epydoc这个工具要么已经不再更新，要么就是在慢慢消亡。

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

一些不错的例子包括：

• requests（源代码）
• boto（源代码）

可以参考这个链接：我们应该使用Epydoc、Sphinx还是其他工具来记录Python API？ (SO5579198)

Sphinx鼓励使用更叙述性的风格，而不是像javadoc那样的工具，这也许是件好事？

Answer 2

我最近把编程语言从Python2换成了Python3，发现Python3没有Epydoc这个工具包。所以看起来在Python3中，大家更倾向于使用Sphinx来生成API文档。

Answer 3

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

它们有一些相同之处：

• 它们都使用 ReST 格式，通过 docutils 来实现。
• 它们都非常注重 Python 语言的特性。
• 它们都可以生成 HTML 和 PDF 格式的文档。

但它们的侧重点不同。

• Epydoc 主要关注 API（开发者）文档。使用 Epydoc，你可以更快地得到结果。只需将它指向你的源代码，就能生成文档。这正是我希望从 API 文档工具中得到的。
• Sphinx 则更关注一般用户文档。虽然 Sphinx 也能从你的源代码中提取很多信息，但你需要投入更多的精力。Sphinx 可以生成 API 文档，但过程没有那么简单，个人认为效果不如 Epydoc。虽然有些人可能不同意，因为 Sphinx 被用于 Python 的文档，但这取决于你愿意投入多少工作。我非常喜欢 Sphinx 用于一般文档的功能。

所以，选择哪个工具取决于你愿意投入多少精力以及你要记录的内容。