有没有人使用 Sphinx 来记录 C++ 项目？
Sphinx 是一个新的 Python 文档工具。 看起来非常好。 我想知道的是：
- 这对于记录 C++ 项目有多合适？
- 是否有任何工具可以将现有文档（例如 doxygen）转换为 Sphinx 格式？
- 是否有使用 Sphinx 的 C++ 项目的在线/可下载示例？
- 使用过 Sphinx 的人有什么建议吗？
Sphinx is a new documentation tool for Python. It looks very nice. What I'm wondering is:
- How suitable this is for documenting a C++ project?
- Are there any tools for converting existing documentation (e.g. doxygen) to Sphinx format?
- Are there online/downloadable examples of C++ projects that use Sphinx?
- Any tips from anyone who has used Sphinx?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
正如此处和此处，
[下面插入编辑]：
我在多台机器上测试了 doxygen+breathe+sphinx 工具链10k
C++ 库由 10 个不同的模块/域组成。 我的底
线路是：
您目前正在寻找一个有价值的 OSS 项目，值得
你的时间。
让我详细阐述以下几点：
我遇到了以下问题：
sphinx 解析器中出现错误，但如果我测试它们，不会造成任何麻烦
直接在sphinx c++代码块中。 不知道修复的难度，
但这是一个严重的功能破坏。
用于寻址不同类中具有相同名称的函数
和/或命名空间和/或 doxygen xml 输出文件。 但显示或链接到
单个类中 10 个重载构造函数中的一个似乎是
ATM机不可行。 在参考/链接的情况下，甚至有一个并行的
（也许是暂时的）对呼吸的狮身人面像水平的限制可能会也可能不会
能够解决问题。
一个班级的成员。 这是通过另一个修复程序引入的
而且修复起来一定很简单。
从更一般的意义上来说，请注意 ATM 是通往 Doxygen 的桥梁
xml 输出。 不应该这样理解它
准确输出 doxygen 的功能，只是有上述限制。
相反，它为您提供了准确的可能性，而不是更多，也不是更少，
然而，必须手动指定。 github上有一个fork
它可能想也可能不想解决这个总体概念问题，但是
那里没有任何关于未来的暗示。
在我看来，功能齐全的呼吸将填补一个重大空白，
开辟一条相当酷的路。 所以值得一看，只是因为
潜在的收获。
可悲的是，通过创建者进行的维护似乎会严重下降
将来。 所以如果你在一家公司工作并且能够说服
你的老板呼吸会适合他，或者有一些空闲时间并且
寻找一个真正有价值的项目，考虑给它一个分叉！
最后，请注意 sphinx 的 doxylink contrib 项目，
这可能提供一个中间解决方案：建立一个类似教程的周围
引用（css 样式匹配）旧 doxygen 文档的结构
（我认为你甚至可以将相同的标头注入 sphinx 并在
doxygen 文档的外观）。 这样，您的项目就可以保持
与狮身人面像有密切关系，当呼吸完全存在时，你就准备好了
跳上。 但再次强调：如果符合你的议程，请考虑表达一些爱。
As mentioned here and here,
[Edit inserted below]:
I tested the doxygen+breathe+sphinx toolchain on a multi-10k
C++ library consisting of 10 different modules/domains. My bottom
line is:
you are currently looking for a valuable OSS project that deserves
your time.
Let me elaborate these points:
I had problems with:
errors in the sphinx parser, but make no trouble if I test them
in sphinx c++ code blocks directly. No idea on the difficulty of fixing,
but this is a serious functionality breaker.
for addressing functions with the same name in different classes
and/or namespaces and/or doxygen xml output files. But showing of or linking to
one specific of 10 overloaded constructors in a single class seems
infeasible ATM. In the reference/linking case, there even is a parallel
(maybe temporary) limitation on the sphinx level which breathe may or may not
be able to work around.
members of a class. This was somehow introduced with another fix
and must be really trivial to repair.
In a more general sense, be aware that it ATM is a bridge to Doxygen's
xml output. That should not be understood in such a way that it will
exactly output what doxygen does, just with the above limitations.
Rather, it offers you exactly, not more, not less, the possibilities to
which however must be specified by hand. There is a fork on github
which may or may not want to address this overall conceptual issue, but
no hints for the future there.
In my opinion, a fully functional breathe would fill a major gap and
open up quite a cool road. So it is worth watching just because of the
potential gain.
It sadly seems that maintainance through the creator will go down severely
in the future. So if you are working in a company and can convince
your boss that breathe would suit him, or have some free time and are
looking for a really valuable project, consider to give it a fork!
As a final pointer, also note the doxylink contrib project for sphinx,
which may provide an intermediate solution: build up a surrounding tutorial-like
structure which references the (css-style matched) old doxygen documentation
(i think you could even inject the same header into sphinx and on top of the
doxygen documentation for look'n'feels). That way, your project keeps an
affinity to sphinx, and when breathe is fully there, you are prepared to
jump on. But again: consider showing breathe some love if it fits your agenda.
首先，保留两个目录树，
source和build。 将source置于版本控制之下。 不要将build置于版本控制之下，将其重建作为安装的一部分。其次，阅读http://sphinx.pocoo.org/intro。 html#setting-up-the-documentation-sources。
使用
sphinx-quickstart构建实践文档树。 尝试几天来了解它是如何工作的。 然后再次使用它在 SVN 目录中构建真实的东西。将您的文档组织在精心规划的树中。 有些部分需要该部分的“index.rst”，有些则不需要。 这取决于该部分的“独立”程度。
我们的顶级
index.rst看起来像这样。请注意，我们不“包含”API，我们只是使用普通的 HTML 链接引用它。
Sphinx 有一个非常酷的附加组件，称为 automodule，它从 Python 模块中挑选文档字符串。
更新 从 Sphinx 1.0 开始，支持 C 和 C++。 http://sphinx.pocoo.org/
First, keep two directory trees,
sourceandbuild. Putsourceunder version control. Don't putbuildunder version control, rebuild it as part of installation.Second, read http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources.
Use the
sphinx-quickstartto build a practice documentation tree. Play with this for a few days to learn how it works. Then use it again to build the real thing in SVN directories.Organize your documentation in a well-planned tree. Some sections need an "index.rst" for that section, some don't. It depends on how "stand-alone" the section is.
Our top-level
index.rstlooks like this.Note, we don't "include" the API, we just reference it with an ordinary HTML link.
Sphinx has a very cool add-on, called automodule, which picks the docstrings out of Python modules.
Update As of Sphinx 1.0, C and C++ are supported. http://sphinx.pocoo.org/
看看 http://www.nabble.com/使用-doxygen-and-sphinx-together-td20989904.html 用于 XML 方法。
Have a look at http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html for an XML approach.