有没有人使用 Sphinx 来记录 C++ 项目？ [关闭]

Question

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

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

Answer 1

正如提到的here和here，

• Sphinx 原生 C++ 支持与突出显示/格式化/引用相关，而不是代码内文档提取
• breathe 源于 chrisdew 引用的讨论

[编辑插入下方]：

我在 multi-10k 上测试了 doxygen+breathe+sphinx 工具链 C++ 库由 10 个不同的模块/域组成。我的底 行是：

1. 尚未完全可用
2. 但请继续观看
3. ，最重要的是，考虑在以下情况下自己花一些时间 您目前正在寻找一个有价值的 OSS 项目，值得 你的时间。

让我详细说明以下几点：

1. 我遇到了问题：

   • doxygen 标记中的乳胶标记（目前不支持，但应该易于实现）
   • 一些解析器错误（几个函数头定义），这似乎会导致 狮身人面像解析器中的错误，但如果我测试它们就没有问题 直接在 sphinx c++ 代码块中。不知道修复的难度， 但这是一个严重的功能破坏。
   • 重载标识符的一些问题。好像有点支持 用于寻址不同类中具有相同名称的函数 和/或命名空间和/或 doxygen xml 输出文件。但显示或链接到 单个类中的 10 个重载构造函数中的一个似乎 不可行的自动取款机。在引用/链接的情况下，甚至有一个并行 （可能是暂时的）限制呼吸的狮身人面像水平可能会或可能不会 能够解决问题。
   • 目前无法显示所有（或所有受保护/私有） 一个班级的成员。这以某种方式引入了另一个修复程序 并且必须非常容易修复。

   • 在更一般的意义上，请注意 ATM 是通往 Doxygen 的桥梁 xml 输出。不应该这样理解 完全输出 doxygen 的作用，只是具有上述限制。 相反，它为您提供了准确的，而不是更多，而不是更少的可能性

     • 将一个 doxygen 输出域中的所有内容转储到一个巨大的页面上
     • 显示特定的函数、成员、结构、枚举、类型定义或类， 但是必须手动指定。 github上有一个fork 它可能想也可能不想解决这个整体概念问题，但是 那里没有关于未来的暗示。

2. 在我看来，功能齐全的呼吸将填补一个主要空白，并且 开辟了一条相当酷的道路。所以值得一看只是因为 潜在收益。

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

作为最后的指针，还要注意 sphinx 的 doxylink contrib 项目， 这可能会提供一个中间解决方案：建立一个类似教程的周边 引用（css 样式匹配的）旧 doxygen 文档的结构 （我认为您甚至可以将相同的标头注入 sphinx 并在 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 有一个非常酷的插件，称为 automodule，它可以从 Python 模块中挑选文档字符串。

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

Answer 3

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