Question

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

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

Answer 1

如上所述here和here，

Sphinx本机C ++支持与突出显示/格式化/引用相关，而不是代码内文档提取
breathe是在chrisdew引用

[编辑插入下方]：

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

尚未完全使用
但继续观看
并且，最重要的是，考虑自己投入一些时间您目前正在寻找值得的有价值的OSS项目你的时间。

让我详细说明以下几点：

我遇到了问题：
- doxygen标记内的Latex标记（目前不支持，但应该易于实现）
- 一些解析器错误（几个函数头定义），这似乎是导致的 sphinx解析器中的错误，但如果我测试它们会毫无问题在sphinx c ++代码中直接阻止。不知道修复的难度，但这是一个严重的功能破坏者。
- 重载标识符有些问题。似乎有一些支持用于在不同的类中寻址具有相同名称的函数和/或命名空间和/或doxygen xml输出文件。但显示或链接到似乎在一个类中有一个特定的10个重载构造函数不可行的ATM。在参考/链接情况下，甚至存在并行（也许是暂时的）对狮身人面像水平的限制，呼吸可能会也可能不会能够解决。
- 目前无法显示所有（或所有受保护/私有）班级成员。这是以某种方式引入另一个修复并且必须非常简单地修复。
- 从更一般的意义上讲，要注意ATM是通往Doxygen的桥梁 xml输出。不应该以这样的方式理解这一点正好输出doxygen所做的，只是有上述限制。相反，它为您提供了
  的可能性，而不是更多，而不是更少
  - 将一个doxygen输出域中的所有内容转储到一个巨大的页面上
  - 显示特定的函数，成员，结构，枚举，typedef或类，但必须手工指定。 github上有一个fork 可能会或可能不想解决这个整体概念问题，但是对那里的未来没有任何暗示。
在我看来，一个功能齐全的呼吸将填补一个主要的差距和开辟了一条很酷的道路。因此，值得关注潜在收益。
遗憾的是，通过创作者的维护会严重下降在将来。所以如果你在一家公司工作并且可以说服他们你呼吸的老板会适合他，或者有空闲时间寻找一个非常有价值的项目，考虑给它一个分叉！

作为最终指针，还要注意sphinx的doxylink contrib项目，这可能提供一个中间解决方案：建立一个周围的教程引用（css风格匹配）旧的doxygen文档的结构（我认为你甚至可以将相同的标题注入狮身人面像和顶部 look'n'feels的doxygen文档。这样，你的项目保持一个对狮身人面像的亲和力，当呼吸完全在那里时，你已经准备好了跳上。但是，如果适合你的议程，请考虑展示一些爱。

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/

Answer 3

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

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

3 个答案: