docutils 和 Sphinx 是什么关系？答案

【问题标题】：What is the relationship between docutils and Sphinx?docutils 和 Sphinx 是什么关系？
【发布时间】：2010-03-14 03:24:05
【问题描述】：

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

【问题讨论】：

当前状态？这意味着什么？你能扩展一下吗？ Sphinx 需要 docutils； epydoc 可以使用相同的 RST 表示法。你想知道什么？你能说得更具体点吗？
例如哪些工具有强大的社区支持，积极的开发？有现成的解决方案，还是有很多没有明显更多的追随者？
也许你应该编辑这个问题的标题。

【解决方案1】：

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

它们的相同之处在于：

他们的关注点不同。

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

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

【讨论】：

感谢您解释这些工具的共同点（例如它们与 docutils 的关系）以及它们之间的区别。是什么让 epydoc 更适合 API 文档，而 Sphinx 更适合功能文档？你提到他们都使用reST。好像有很多重叠。只是为了方便吗？此外，epydoc 的开发似乎也不是很活跃。最后一次提交是在 2009 年 2 月，而在开发列表上的最后一次通信是在 2009 年 5 月。
嗯，为什么一个人在某件事上比另一件事更好的简单答案就是它们的设计方式。 Epydoc 仅用于从代码中提取，而 Sphinx 则用于从您编写的 ReST 文件中生成大量文档。有很多重叠。斯芬克斯是街区里的新人。我听说在 0.7 中它将内置更好的自动生成功能。我非常尊重 Epydoc，但 Sphinx 似乎现在拥有所有动力。我喜欢它，因为它看起来像 python.org 文档，而且我认为它看起来更好。
Sphinx 不专注于一般用户文档。 Sphinx 是一个工具，它可以帮助您编写完整而详细的文档，而您根本无法通过连接文档字符串来提供这些文档。此外，Sphinx 将支持所谓的 1.0 域，这将允许您记录用多种语言编写的项目，例如用 Python、Javascript 和 C 编写的 web 应用程序。
我正要询问 Sphinx 如何生成 API 文档的指针，然后我找到了你的 this 帖子。 sphinx.ext.autodocdoh。谢谢。

【解决方案2】：

我最近从Python2换成了Python3，发现没有Python3的Epydoc包。因此，对于 Python3，似乎有一个明确的重点是使用 Sphinx 作为 API 文档。

【讨论】：

【解决方案3】：

似乎Epydoc 是，如果没有死，至少渴望峡湾。

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

很好的例子是：

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

【讨论】：