python - 有没有人使用 Sphinx 来记录 C++ 项目？

Question

Sphinx是一个新的 Python 文档工具。它看起来非常漂亮。我想知道的是:

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

Answer 1

如前所述 here和 here ,

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

[编辑插入下方]:

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

1. 尚未完全可用
2. 但请继续观看
3. 而且，最重要的是，如果出现以下情况，请考虑自己花一些时间 您目前正在寻找一个有值(value)的 OSS 项目，值得 你的时间。

让我详细说明以下几点:

1. 我遇到了以下问题:

   • doxygen 标记中的 latex 标记(目前不支持，但应该很容易实现)
   • 一些解析器错误(几个函数头定义)，这似乎会导致 狮身人面像解析器中的错误，但如果我测试它们就没有问题 直接在 sphinx c++ 代码块中。不知道修复的难度， 但这是一个严重的功能破坏。
   • 重载标识符的一些问题。好像有点支持 用于寻址不同类中具有相同名称的函数 和/或命名空间和/或 doxygen xml 输出文件。但显示或链接到 单个类中的 10 个重载构造函数中的一个似乎 不可行的自动取款机。在引用/链接的情况下，甚至有一个并行 (可能是暂时的)限制呼吸的狮身人面像水平可能会或可能不会 能够解决问题。
   • 目前无法显示全部(或全部 protected /私有(private)) 一个类(class)的成员。这以某种方式引入了另一个修复程序 并且必须非常容易修复。

   • 在更一般的意义上，请注意 ATM 是通往 Doxygen 的桥梁 xml 输出。不应该这样理解 完全输出 doxygen 的作用，只是具有上述限制。 相反，它为您提供了准确的，而不是更多，而不是更少的可能性

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

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

3. 可悲的是，通过创作者的维护似乎会严重下降 在将来。所以如果你在一家公司工作并且可以说服 你会呼吸的老板会适合他，或者有一些空闲时间 寻找一个真正有值(value)的项目，考虑给它一个 fork!

作为最终指针，还要注意 doxylink狮身人面像的贡献项目， 这可能会提供一个中间解决方案:建立一个类似教程的周边 引用(css 样式匹配的)旧 doxygen 文档的结构 (我认为您甚至可以将相同的 header 注入(inject) sphinx 并在 look'n'feels 的 doxygen 文档)。这样，您的项目将保持 与狮身人面像的亲和力，当呼吸完全在那里时，你准备好了 跳上。但再说一遍:如果符合您的议程，请考虑表现出一些爱。