有没有人用Sphinx来logging一个C ++项目？

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

• 如何合适这是为了logging一个C ++项目？
• 是否有任何工具将现有的文档（例如doxygen）转换为Sphinx格式？
• 有在线/可下载的使用Sphinx的C ++项目的例子吗？
• 任何使用狮身人面像的人的提示？

Answer 1

如这里和这里所述 ，

• Sphinx原生C ++支持与突出显示/格式化/引用有关，而不是在代码文档中提取
• 呼吸已经发展出了chrisdew参考的讨论

[编辑下面插入]：

我在一个由10个不同的模块/域组成的多10k C ++库上testing了doxygen + breathe + sphinx工具链。 我的底线是：

1. 尚未完全可用
2. 但一直在看
3. 最重要的是，如果你正在寻找一个值得你花时间的有价值的OSS项目，那就考虑花点时间吧。

让我详细说明这几点：

1. 我遇到了问题：

   • doxygen标记中的乳房标记（目前不支持，但应该很容易实现）
   • 一些parsing器错误（几个函数头定义），这似乎导致在狮身人面像parsing器中的错误，但如果我直接在sphinx c ++代码块中testing它们，不会有任何麻烦。 不知道修复的困难，但这是一个严重的function断路器。
   • 重载标识符有些麻烦。 似乎有一些支持在不同的类和/或命名空间和/或doxygen xml输出文件中寻址具有相同名称的函数。 但是在一个类中显示或者链接到10个重载构造函数的一个特定的构造函数似乎是不可行的。 在参考/链接的情况下，甚至有一个平行的（可能是暂时的）狮身人面的层面上的限制，呼吸可能或可能无法解决。
   • 目前没有办法显示一个class级的所有（或全部受保护/私人）成员。 这在某种程度上是用另一个修复程序引入的，而且修复起来也是非常微不足道的。

   • 从更一般的意义上讲，请注意，ATM是Doxygen的xml输出的桥梁。 这不应该被理解为它将精确地输出doxygen所做的，只是具有上述限制。 相反，它提供给你的是，不多，不less，可能性

     • 将一个doxygen输出域中的所有内容转储到一个巨型页面上
     • 显示具体的function，成员，结构，枚举，types定义或类，但必须手工指定。 github上有一个分支，它可能会也可能不会想要解决这个总体的概念问题，但是在那里没有提示未来。

2. 在我看来，一个function齐全的呼吸将填补一个重大的差距，开辟一条相当酷的道路。 所以值得一看，因为潜在的收益。

3. 可悲的是，通过创造者的维护将在未来严重下降。 所以，如果你在一家公司工作，并能说服你的老板，呼吸会适合他，或有一些空闲时间，并正在寻找一个非常有价值的项目，考虑给它一个叉！

作为最后一个指针，还要注意sphinx的doxylink contrib项目，它可能提供了一个中间解决scheme：构build一个引用（css风格匹配的）旧doxygen文档的周边教程式结构（我想你甚至可以注入相同的头部到狮身人面像和doxygen文件顶部look'n'feels）。 这样，你的项目就和狮身人面像保持着亲密的关系，当呼吸充分的时候，你就准备好了。 但是，再次考虑如果适合你的日程表示呼吸一些爱。

Answer 2

首先，保持两个目录树， source和build 。 把source放在版本控制之下。 不要将build置于版本控制之下，重build它作为安装的一部分。

其次，阅读http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources 。

使用sphinx-quickstart构build练习文档树。 玩这个几天，以了解它是如何工作的。 然后再次使用它在SVN目录中构build真实的东西。

在一个精心策划的树中组织你的文档。 有些部分需要一个“index.rst”的部分，有些则不需要。 这取决于该部分是如何“独立”的。

我们顶级的index.rst看起来像这样。

 .. XXX documentation master file, created by sphinx-quickstart on Wed Dec 31 07:27:45 2008. .. include:: overview.inc .. _`requirements`: Requirements ============ .. toctree:: :maxdepth: 1 requirements/requirements requirements/admin requirements/forward requirements/volume .. _`architecture`: Architecture ============ .. toctree:: :maxdepth: 1 architecture/architecture architecture/techstack architecture/webservice_tech architecture/webservice_arch architecture/common_features architecture/linux_host_architecture Detailed Designs ================ .. toctree:: :maxdepth: 3 design/index Installation and Operations =========================== .. toctree:: :maxdepth: 1 deployment/installation deployment/operations deployment/support deployment/load_test_results deployment/reference deployment/licensing Programming and API's ===================== .. toctree:: :maxdepth: 2 programming/index **API Reference**. The `API Reference`_ is generated from the source. .. _`API Reference`: ../../../apidoc/xxx/index.html .. note:: The API reference must be built with `Epydoc`_. .. _`Epydoc`: http://epydoc.sourceforge.net/ Management ========== .. toctree:: :maxdepth: 2 :glob: management/* Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` SVN Revision ============ :: $Revision: 319 $ 

请注意，我们不“包含”API，我们只是用一个普通的HTML链接来引用它。

Sphinx有一个非常酷的插件，叫做automodule，它从Python模块中select文档。

更新从Sphinx 1.0起，支持C和C ++。 http://sphinx.pocoo.org/

Answer 3

看看http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html的XML方法。;