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

Has anyone used Sphinx to document a C++ project?

提问by Nick

Sphinxis a new documentation tool for Python. It looks very nice. What I'm wondering is:

Sphinx是一个新的 Python 文档工具。它看起来很不错。我想知道的是：

• How suitable this is for documenting a C++ project?
• Are there any tools for converting existing documentation (e.g. doxygen) to Sphinx format?
• Are there online/downloadable examples of C++ projects that use Sphinx?
• Any tips from anyone who has used Sphinx?

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

回答by daspostloch

As mentioned hereand here,

正如这里和这里提到的，

• Sphinx native C++ support is related to highlighting/formatting/referencing, not in-code documentation extraction
• breathehas developed out of the discussion that chrisdew referenced

• Sphinx 本机 C++ 支持与突出显示/格式化/引用有关，而不是代码中的文档提取
• 呼吸是从克里斯德引用的讨论中发展起来的

[Edit inserted below]:

[下面插入的编辑]：

I tested the doxygen+breathe+sphinx toolchain on a multi-10k C++ library consisting of 10 different modules/domains. My bottom line is:

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

1. not yet fully usable
2. but keep watching
3. and, most importantly, consider devoting some time yourself if you are currently looking for a valuable OSS project that deserves your time.

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

Let me elaborate these points:

让我详细说明以下几点：

1. I had problems with:

   • Latex markup within the doxygen markup (not supported currently, but should be easy to implement)
   • Some parser errors (several function header definitions), which seemingly cause errors in the sphinx parser, but make no trouble if I test them in sphinx c++ code blocks directly. No idea on the difficulty of fixing, but this is a serious functionality breaker.
   • Some trouble with overloaded identifiers. There seems to be some support for addressing functions with the same name in different classes and/or namespaces and/or doxygen xml output files. But showing of or linking to one specific of 10 overloaded constructors in a single class seems infeasible ATM. In the reference/linking case, there even is a parallel (maybe temporary) limitation on the sphinx level which breathe may or may not be able to work around.
   • Currently there is no way to show all (or all protected/private) members of a class. This was somehow introduced with another fix and must be really trivial to repair.

   • In a more general sense, be aware that it ATM is a bridge to Doxygen's xml output. That should not be understood in such a way that it will exactly output what doxygen does, just with the above limitations. Rather, it offers you exactly, not more, not less, the possibilities to

     • dump out everything in one doxygen output domain onto one giant page
     • show specific functions, members, structs, enums, typedefs, or classes, which however must be specified by hand. There is a fork on github which may or may not want to address this overall conceptual issue, but no hints for the future there.

2. In my opinion, a fully functional breathe would fill a major gap and open up quite a cool road. So it is worth watching just because of the potential gain.

3. It sadly seems that maintainance through the creator will go down severely in the future. So if you are working in a company and can convince your boss that breathe would suit him, or have some free time and are looking for a really valuable project, consider to give it a fork!

1. 我遇到了以下问题：

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

   • 在更一般的意义上，请注意 ATM 是通向 Doxygen 的 xml 输出的桥梁。这不应该被理解为它会准确地输出 doxygen 所做的事情，只是有上述限制。相反，它为您提供了准确的，而不是更多，而不是更少的可能性

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

2. 在我看来，功能齐全的呼吸将填补一个主要空白并开辟一条很酷的道路。因此，仅仅因为潜在的收益就值得关注。

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

As a final pointer, also note the doxylinkcontrib project for sphinx, which may provide an intermediate solution: build up a surrounding tutorial-like structure which references the (css-style matched) old doxygen documentation (i think you could even inject the same header into sphinx and on top of the doxygen documentation for look'n'feels). That way, your project keeps an affinity to sphinx, and when breathe is fully there, you are prepared to jump on. But again: consider showing breathe some love if it fits your agenda.

作为最后一个指针，还要注意sphinx的doxylinkcontrib 项目，它可能提供一个中间解决方案：建立一个类似教程的结构，它引用（css 样式匹配）旧的 doxygen 文档（我认为你甚至可以注入相同的头进入狮身人面像并在 doxygen 文档的顶部以查看外观）。这样，您的项目就会与狮身人面像保持密切联系，当呼吸充足时，您就可以继续前进了。但同样：如果适合您的议程，请考虑表现出一些爱。

回答by S.Lott

First, keep two directory trees, sourceand build. Put sourceunder version control. Don't put buildunder version control, rebuild it as part of installation.

首先，保留两个目录树，source和build. 把source版本控制之下。不要将其build置于版本控制之下，将其作为安装的一部分进行重建。

Second, read http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources.

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

Use the sphinx-quickstartto build a practice documentation tree. Play with this for a few days to learn how it works. Then use it again to build the real thing in SVN directories.

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

Organize your documentation in a well-planned tree. Some sections need an "index.rst" for that section, some don't. It depends on how "stand-alone" the section is.

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

Our top-level index.rstlooks like this.

我们的顶层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 $

Note, we don't "include" the API, we just reference it with an ordinary HTML link.

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

Sphinx has a very cool add-on, called automodule, which picks the docstrings out of Python modules.

Sphinx 有一个非常酷的附加组件，称为 automodule，它从 Python 模块中挑选文档字符串。

UpdateAs of Sphinx 1.0, C and C++ are supported. http://sphinx.pocoo.org/

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

回答by fadedbee

Have a look at http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.htmlfor an XML approach.

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