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

Question

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

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

Answer 1

首先，保留两个目录树，source和build。在版本控制下放入source。不要将build置于版本控制之下，重建它作为安装的一部分。第二，阅读http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources。使用sphinx-quickstart构建练习文档树。玩这几天，以了解它是如何工作的。然后再次使用它在SVN目录中构建真实的东西。

在规划良好的树中组织您的文档。有些部分需要为该部分提供“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模块中选取文档。

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

Answer 2

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

Answer 3

如前所述here和here，

• 斯芬克斯本地C++支持涉及高亮/格式化/引用，而不是在编码文档提取
• breathe已经开发的是chrisdew引用
讨论

[编辑插入在下方]：

我测试了d氧气+呼吸+狮身人面像工具链在一个由10个不同的模块/域组成的多10k的 C++库上。我的底部 行：

1. 尚未完全可用
2. 但保持观望
3. ，最重要的是，认为自己投入一些时间，如果 你正在寻找一个值得 一个有价值的开放源码软件项目的时间。

让我解释这些要点：

1. 我有问题：doxygen的标记内

   • 乳胶标记（目前不支持，但应该是很容易实现）
   • 一些解析器错误（几个函数头定义），这在sphinx解析器中看起来会导致 错误，但是如果我测试它们就不会有问题 直接在sphinx C++代码块中。不知道修复的难度，但这是一个严重的功能断路器。
   • 重载标识符有些问题。似乎有一些支持 用于在不同的类 和/或名称空间和/或doxygen xml输出文件中寻址具有相同名称的函数。但是显示或链接到 单个类中的10个重载构造函数的一个特定似乎是 不可行ATM。在参考/链接的情况下，甚至有一个平行的 （可能是暂时的）狮身人面的水平，其呼吸可能或不可能 能够解决。
   • 目前没有办法显示全部（或全部受保护/私密） 类的成员。这在某种程度上引入了另一个修复程序 ，并且修复必须非常简单。

   • 从更一般的意义上讲，请注意它是ATM是Doxygen的 xml输出的桥梁。不应该以这种方式理解这一点，它只会在上述限制的情况下精确输出doxygen的功能。 相反，它为您提供准确，而不是更多，而不是更少的可能性

     • 倾倒出一个doxygen的输出区域的一切到一个巨大的页面
     • 显示特定的功能，成员结构，枚举，类型定义，或类， 但是必须手工指定。 github上有一个分支，它可能会也可能不会想要解决这个总体概念问题，但是对于未来而言没有任何暗示。

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

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

作为最后指针，还注意到对于斯芬克斯的doxylink的contrib项目， ，其可以提供一个中间的解决方案：建立一个周围教程状 结构，其引用（CSS样式匹配的）旧Doxygen文档 （我想你甚至可以将相同的头文件注入到狮身人面像中，并在 doxygen文档的look'n'feels之上）。这样，你的项目对狮身人面像保持亲和力 ，当呼吸充分时，你准备跳到 。但是，再次考虑：如果符合你的日程安排，请考虑展示一些爱。