docutils和Sphinx之间有什么关系？

Question

似乎有大量的Python文档工具。我碰到的另一个是epydoc。似乎Sphinx是事实上的标准，因为它用于生成官方Python文档。有人可以帮我理清Python文档工具的当前状态吗？

Answer 1

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

他们是一样的：

• 两者都通过ReST使用docutils。
• 他们的焦点都是非常恐怖的
• 两者都可以生成HTML和PDF文档

他们的焦点不同。

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

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

Answer 2

我最近从Python2改为Python3，发现Python3没有Epydoc包。所以在Python3中似乎有一个明确的重点是使用Sphinx作为API文档。

Answer 3

似乎Epydoc，如果没有死，至少会为峡湾而烦恼。

使用sphinx-apidoc命令和autodoc扩展名的Sphynx目前是API文档最受欢迎的选项。

很好的例子是：

• requests（src）
• boto（src）

请参阅：Should we use Epydoc, Sphinx or something else for documenting Python APIs? (SO5579198)

Sphinx鼓励比javadoc模具中的工具更具叙事风格，但这可能是件好事吗？