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

Question

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

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

Answer 1

如这里和这里提到的,

• Sphinx本机C++支持与突出显示/格式化/引用相关,而不是代码内文档提取
• 呼吸是由chrisdew引用的讨论发展而来的

[编辑插入下方]:

我在由10个不同模块/域组成的多个10k C++库中测试了doxygen + breathe + sphinx工具链.我的底线是:

1. 尚未完全使用
2. 但继续看
3. 而且,最重要的是,如果您正在寻找值得花时间的宝贵OSS项目,请考虑自己花一些时间.

让我详细说明以下几点:

1. 我有问题:

   • doxygen标记内的Latex标记(目前不支持,但应该易于实现)
   • 一些解析器错误(几个函数头定义),似乎导致sphinx解析器中的错误,但如果我直接在sphinx c ++代码块中测试它们就不会有问题.不知道修复的难度,但这是一个严重的功能破坏者.
   • 重载标识符有些麻烦.似乎有一些支持在不同的类和/或命名空间和/或doxygen xml输出文件中寻址具有相同名称的函数.但是在单个类中显示或链接到10个重载构造函数中的一个特定似乎是不可行的ATM.在参考/连接情况下,甚至在狮身人面像水平上存在平行(可能是暂时的)限制,呼吸可能会或可能不会解决.
   • 目前无法显示类的所有(或所有受保护/私有)成员.这是以某种方式引入另一个修复程序,并且必须非常简单地修复.

   • 从更一般的意义上讲,要注意它是通往Doxygen的xml输出的桥梁.这不应该以这样的方式理解,即只要具有上述限制,它将准确地输出doxygen所做的事情.相反,它为您提供准确,而不是更多,而不是更少的可能性

     • 将一个doxygen输出域中的所有内容转储到一个巨大的页面上
     • 显示特定的函数,成员,结构,枚举,typedef或类,但必须手动指定.在github上有一个fork可能会或可能不想解决这个整体概念问题,但没有提示未来.

2. 在我看来,一个功能齐全的呼吸将填补一个主要的差距,并开辟一条很酷的道路.因此潜在的收益值得关注.

3. 可悲的是,通过创作者的维护将来会严重下降.因此,如果你在一家公司工作并且可以说服你的老板呼吸适合他,或者有空闲时间并且正在寻找一个非常有价值的项目,那么考虑给它一个分叉!

作为最终指针,还要注意sphinx 的doxylink contrib项目,它可以提供一个中间解决方案:构建一个类似于教程的结构,引用(css样式匹配的)旧的doxygen文档(我想你甚至可以注入相同的标题进入狮身人面像,并在doxygen文档的顶部看起来'n'感觉).这样,你的项目与狮身人面像保持着亲密关系,当呼吸完全在那里时,你就准备好继续前进.但是又一次:如果适合你的议程,考虑表现出一些爱.

Answer 2

首先,保留两个目录树,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有一个非常酷的附加组件,称为自动模块,它从Python模块中选择文档字符串.

更新自Sphinx 1.0起,支持C和C++. http://sphinx.pocoo.org/