Sphinx 是否已经适用于 C++ 文档？ [关闭]答案

【问题标题】：Is Sphinx already suitable for C++ documentation? [closed]Sphinx 是否已经适用于 C++ 文档？ [关闭]
【发布时间】：2012-10-07 16:28:18
【问题描述】：

我想为一个 C++ 新项目试用文档生成器。我认为我的选择是 Doxygen 或 Sphinx。由于我在 Python 中有想要使用 Sphinx 的项目，我想知道 Sphinx 是否也是 C++ 的正确选择。 Sphinx 网站声明支持 C++，但我找不到让我开始使用 C++ 文档的文档。

discussed on Stackoverflow 已经有一个类似的问题，主要答案如下：

尚未完全可用，
但请继续观看

由于讨论已经一年多了，我想知道这个结论是否仍然有效。我应该为我的 C++ 文档选择 Doxygen 而不是 Sphinx 吗？

【问题讨论】：

我不了解 Sphinx，但我认为 Doxygen 确实是一个很棒的工具！您发现 Doxygen 有哪些问题？
@georgesl 目前我对 Doxygen 的唯一问题是我将在我的 Python 项目中使用 Sphinx，并希望避免使用两个不同的文档系统。可能需要时间来开始使用每一个，并习惯语法。
@cls：实际上，对于应该提取什么以及应该分开记录什么是明智的辩论实践。自动提取类/函数是有意义的，这使您可以构建可搜索的索引等。但是，尚不清楚文档是否也应该在那里。将其作为一个单独的文档允许较少的技术人员使用它们，并且在源代码管理中也更容易让不同的人查看不同类型的文档。最后，代码中冗长的解释会占用屏幕空间。
@cls 坚持使用语言的标准工具。在 C++ 中，这就是 doxygen，尽管它存在所有问题。无论如何，您使用的是两种截然不同的语言，因此您应该能够处理两种略有不同的工具。
@lunaryorn 我不同意。您应该选择最适合您的项目/问题的工具。而且 C++ 没有“标准”文档工具。

【解决方案1】：

Sphinx 无法单独从 C++ 源代码中提取文档。但是，也有一些扩展，最著名的是 Breathe，它利用 Doxygen 从 C++ 中提取文档。这些我都没有测试过。

【讨论】：

【解决方案2】：

对于 C++，Doxygen 非常好； Sphinx 对 C++ 的支持是通过 Doxygen 完成的（使用 Breathe）。

您希望两种语言只有一个工具，以提高可维护性。 Doxygen can generate a documentation from Python code，所以我建议您尽可能将 Doxygen 用于这两种来源。 Here is a tutorial for Doxygen and Python.

【讨论】：

我在多年的 Python 编程中从未见过任何使用 Doxygen 的 Python 项目。它在 Python 社区中绝对是一个非标准工具，它不像你遇到问题时会找到很多帮助。
您的论点是“Doxygen 对 Python 不利，因为没有人使用它”？对不起，但这不是真的。例如，参见code.foosel.org/doxypy、stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks、engtech.wordpress.com/2007/03/20/…（所以有人对 Doxygen 和 Python 感兴趣）。
Google 的一些结果并没有真正否定我关于它是社区中的非标准工具的说法。在重要项目中广泛使用 Doxygen，但没有。没有相当大的 Python 项目使用 Doxygen 来编写文档，或者在过去这样做过。哎呀，连 Zope 都没有……
你说得对，没有真正的大 Python 项目使用 Doxygen。但是根据您的推理，应该只使用 pydoc，而不是 Sphinx/Doxygen/epydoc...
这不是我的推理。我没有说应该使用什么。我根据我的个人经验和观察评估了实际使用的。 Sphinx 和 epydoc 在 Python 开发人员中被广泛使用——尽管 epydoc 的使用量减少了——因此可以被视为 Python 中事实上的标准工具。 Pydoc 是针对不同用例的不同工具，也是 Python 开发人员的标准工具。