有人使用 Sphinx 来记录 C++ 项目吗？ [关闭]

Sphinx https://www.sphinx-doc.org是一个新的 Python 文档工具。看起来非常好。我想知道的是：

• 这对于记录 C++ 项目有多合适？
• 是否有任何工具可以将现有文档（例如 doxygen）转换为 Sphinx 格式？
• 是否有使用 Sphinx 的 C++ 项目的在线/可下载示例？
• 使用过 Sphinx 的人有什么建议吗？

如上所述here https://stackoverflow.com/questions/2377985/doxygen-c-comment-string-parser-in-python and here https://stackoverflow.com/questions/2743687/sphinx-in-clinux,

• Sphinx 原生 C++ 支持与突出显示/格式化/引用相关，而不是代码内文档提取
• breathe http://michaeljones.github.com/breathe/index.html是从 chrisdew 引用的讨论中发展出来的

[下面插入编辑]：

我在 multi-10k 上测试了 doxygen+breathe+sphinx 工具链 C++ 库由 10 个不同的模块/域组成。我的底 线路是：

1. 尚未完全可用
2. 但继续观察
3. 最重要的是，考虑自己花一些时间，如果 您目前正在寻找一个有价值的 OSS 项目，值得 你的时间。

让我详细阐述一下这几点：

1. 我遇到了以下问题：

   • doxygen 标记中的 Latex 标记（当前不支持，但应该很容易实现）
   • 一些解析器错误（几个函数头定义），这似乎导致 sphinx 解析器中出现错误，但如果我测试它们，不会造成任何麻烦 直接在sphinx c++代码块中。不知道修复的难度， 但这是一个严重的功能破坏。
   • 标识符重载会出现一些问题。好像还有一些支持 用于寻址不同类中具有相同名称的函数 和/或命名空间和/或 doxygen xml 输出文件。但显示或链接到 单个类中 10 个重载构造函数中的一个似乎是 ATM机不可行。在参考/链接的情况下，甚至有一个并行的 （也许是暂时的）对呼吸的狮身人面像水平的限制可能会也可能不会 能够解决。
   • 目前无法显示全部（或所有受保护/私有） 一个班级的成员。这是通过另一个修复程序引入的 并且修复起来一定很简单。

   • 从更一般的意义上来说，请注意 ATM 是通往 Doxygen 的桥梁 xml 输出。不应该这样理解它 准确输出 doxygen 的功能，只是有上述限制。 相反，它为您提供了准确的、不多也不少的可能性：

     • 将一个 doxygen 输出域中的所有内容转储到一个大页面上
     • 显示特定的函数、成员、结构、枚举、typedef 或类， 然而，必须手动指定。 github上有一个fork 它可能想也可能不想解决这个总体概念问题，但是 那里没有未来的暗示。

2. 在我看来，功能齐全的呼吸将填补一个重大空白 开辟一条相当酷的路。所以值得一看，只是因为 潜在收益。

3. 遗憾的是，通过创建者进行的维护似乎会严重下降 将来。所以如果你在一家公司工作并且能够说服 你的老板呼吸会适合他，或者有一些空闲时间并且 寻找一个真正有价值的项目，考虑给它一个叉子！

作为最后一点，还请注意doxylink https://bitbucket.org/birkenfeld/sphinx-contrib/src狮身人面像的贡献项目， 这可能提供一个中间解决方案：建立一个类似教程的周围 引用（css 样式匹配）旧 doxygen 文档的结构 （我认为你甚至可以将相同的标头注入 sphinx 并在 doxygen 文档的外观）。这样，您的项目就可以保持 与狮身人面像有密切关系，当呼吸完全存在时，你就准备好了 跳上。但再次强调：如果符合你的议程，请考虑表达一些爱。