Sphinx已经适合用于C++文档吗？

Question

我想尝试使用文档生成器来为一个新的C++项目生成文档。我认为我的选择是Doxygen或Sphinx。因为我有一些Python项目想要使用Sphinx，所以我想知道Sphinx是否也适用于C++。 Sphinx 网站表明支持C++，但我找不到一个能帮助我开始编写C++文档的文档。

一个类似的问题已经在Stackoverflow上讨论过了，主要答案得出结论：

目前还不能完全使用，
但请继续关注

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

- clstaudt

---

我不了解Sphinx，但我认为Doxygen确实是一个很棒的工具！你对Doxygen有什么问题？ - lucasg

我对Doxygen目前唯一的问题是我将在我的Python项目中使用Sphinx，并希望避免使用两种不同的文档系统。这可能需要花费时间来开始并适应语法。 - clstaudt

实际上，就实践而言，存在一种辩论，即应该提取什么内容并将其记录在不同的地方。自动提取类/函数是有意义的，这样你可以建立一个可搜索的索引等等。然而，是否应该包括文档并不清楚。将其作为单独的文档可以让非技术人员使用它们，并且在源管理中，拥有不同类型的文档由不同的人进行概述也更容易。最后，在代码中过长的解释会占据太多屏幕空间。 - Matthieu M.

@cls 遵循语言的标准工具。在C++中，尽管存在所有问题，但应使用doxygen。您已经在使用两种截然不同的语言，因此应该能够处理两个略有不同的工具。 - user355252

@lunaryorn 我不同意。你应该选择最适合你的项目/问题的工具。而C++没有“标准”的文档工具。 - Synxis

Answer 1

Sphinx本身无法从C++源代码中提取文档。但是，有一些扩展可以使用Doxygen从C++中提取文档，其中最著名的是Breathe。我没有测试过这些扩展。

- user355252

---

貌似如果我要使用Breathe的话，仍然需要使用奇怪的Doxygen语法。:-/ - Niklas R

请参阅 https://breathe.readthedocs.io/en/latest/，您无需使用doxy语法。 - Erik Aronesty

还有一款名为 antidox 的新播放器，目前仍处于 alpha 开发阶段。 - Akib Azmain Turja

Answer 2

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

您希望只使用一个工具来处理这两种语言，以提高可维护性。Doxygen可以从Python代码生成文档，因此我建议您尽可能使用Doxygen处理这两个源文件。这里有一个关于Doxygen和Python的教程。

- Synxis

---

我在多年的Python编程中从未见过任何使用Doxygen的Python项目。在Python社区中，它绝对是一种非标准工具，如果你遇到问题，很难得到太多帮助。 - user355252

你的论点是“Doxygen不适用于Python，因为没有人使用它”？对不起，这并不正确。例如，请参见http://code.foosel.org/doxypy、http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks以及http://engtech.wordpress.com/2007/03/20/automatic_documentation_python_doxygen/（因此有人对在Python中使用Doxygen感兴趣）。 - Synxis

有些谷歌搜索结果并没有完全否定我的观点，即Doxygen在社区中是一个非标准工具。如果重要项目广泛使用Doxygen进行文档编写，则可以改变这一状况，但实际上并没有。没有任何重要的Python项目在过去或现在使用Doxygen进行文档编写。甚至连Zope也没有使用过…请注意，这里不包括任何解释或额外信息。 - user355252

你说得对，确实没有什么大型的Python项目使用Doxygen。但是按照你的推理，只应该使用pydoc，而不是Sphinx/Doxygen/epydoc... - Synxis

这不是“我的”理由。我没有说应该使用什么。我根据个人经验和观察评估了实际使用的工具。Sphinx和epydoc在Python开发者中广泛使用，尽管epydoc的使用率有所下降，因此可以被认为是Python中事实上的标准工具。Pydoc是一个不同的工具，用于不同的情况，并且也是Python开发者中的标准工具。 - user355252