有没有人使用Sphinx来记录C ++项目？ [英] Has anyone used Sphinx to document a C++ project?
问题描述
狮身人面像是Python的新文档工具。看起来很不错我想知道的是：
Sphinx is a new documentation tool for Python. It looks very nice. What I'm wondering is:
- 如何适用于记录C ++项目？
- 是否有任何将现有文档（例如doxygen）转换为Sphinx格式的工具？
- 是否有使用Sphinx的C ++项目的在线/可下载示例？
- 任何使用Sphinx的人的任何提示？
- 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?
推荐答案
- Sphinx本地C ++支持与突出显示/格式化/引用相关，不在代码文档提取
- 呼吸已经开发在讨论之前，chrisdew引用
- Sphinx native C++ support is related to highlighting/formatting/referencing, not in-code documentation extraction
- breathe has developed out of the discussion that chrisdew referenced
：
我在一个由10个不同模块/域组成的多10k
C ++库中测试了doxygen +呼吸+ sphinx工具链。我的底部
行是：
I tested the doxygen+breathe+sphinx toolchain on a multi-10k C++ library consisting of 10 different modules/domains. My bottom line is:
- 尚未完全使用
- / li>
- ，最重要的是，如果
您现在正在寻找一个值得您b0 b $ b的宝贵的OSS项目，您的时间将会花费一些时间。
请详细说明这些要点：
-
我有问题with：
I had problems with:
- doxygen标记中的胶乳标记（目前不支持但应易于实施）
- 某些解析器错误（几个函数头定义），似乎在sphinx解析器中导致
错误，但是如果我直接在sphinx c ++代码块中测试
，则不会麻烦。不了解修复的难度，
但这是一个严重的功能破坏者。 - 重载标识符有些麻烦。似乎有一些支持
用于在不同的类
和/或命名空间和/或doxygen xml输出文件中寻址具有相同名称的函数。但显示或链接到
一个特定的10个重载构造函数在一个单一的类似乎
不可行的ATM。在参考/链接的情况下，甚至还有一个平行的
（可能是临时的）限制，可以呼吸或可能没有
可以解决。 - 目前没有办法显示一个类的所有（或所有保护/私有）
成员。这是以某种方式引入另一个修复
，必须非常简单的修复。 -
在更一般的意义上，请注意，ATM是Doxygen的
xml输出。这不应该以这样一种方式理解，只要符合上述限制，它将
完全输出什么doxygen。
相反，它为您提供了完全不是更少的，而不是更少的可能性。
- Latex markup within the doxygen markup (not supported currently, but should be easy to implement)
- Some parser errors (several function header definitions), which seemingly cause 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.
- Some trouble with overloaded identifiers. There seems to be some support 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.
- Currently there is no way to show all (or all protected/private) 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
- 转出一个doxygen输出域中的所有内容显示特定的函数，成员，结构体，枚举，typedefs或类
，但是必须用手指定一个巨大的页面 - 。在github
上有一个fork，可能或可能不想解决这个整体概念问题，但
没有提示未来。
在我看来，全功能呼吸将填补一个重大差距，
开辟了一条很酷的道路。所以值得观看，因为
的潜在收益。
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.
可悲的是，通过创作者的维护将严重下降
在将来。所以如果你在一家公司工作，并且可以说服你的老板，那么呼吸的老板会适合他，还是有一些空闲时间，并且
寻找一个非常有价值的项目，考虑给它一个叉子！ p>
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!
作为最后一个指针，还要注意 doxylink 对于sphinx，
的contrib项目，可以提供中间解决方案：构建一个周围的教程 -
结构，引用（css-风格匹配）old doxygen文档
（我想你甚至可以将相同的标题注入到狮身人面像中，并且在
doxygen文档的顶部，查看'恩'）。这样，您的项目对于狮身人面像保持
的亲和力，当呼吸完全在那里时，您准备
跳跃。但再次考虑：如果符合您的议程，请考虑显示一些爱。
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.
这篇关于有没有人使用Sphinx来记录C ++项目？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
