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

Question

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

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

score 23 · Accepted Answer

如here和here所述，

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

[编辑插入下面]：

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

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

让我详细说明以下几点：

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

作为最后的指针，还要注意 sphinx 的doxylink contrib 项目，它可以提供一个中间解决方案：建立一个类似教程的结构，它引用（css 样式匹配的）旧 doxygen 文档（我认为你甚至可以注入相同的标头进入 sphinx 并在 doxygen 文档之上查看'n'feels）。这样，您的项目就可以与 sphinx 保持密切联系，并且当呼吸完全到位时，您就可以继续前进了。但再说一遍：如果它符合您的议程，请考虑表现出一些爱。

score 11 · Accepted Answer

首先，保留两个目录树，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/

score 4 · Accepted Answer

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

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

3 回答 3

Related

Reference