有人用Sphinx为C++项目写文档吗？

44 投票

3 回答

20937 浏览

数据工程师

提问于 2025-04-15 11:27

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

这个工具适合用来记录C++项目吗？
有没有工具可以把现有的文档（比如doxygen生成的）转换成Sphinx格式？
有没有在线或可下载的C++项目示例是使用Sphinx的？
有没有使用过Sphinx的人能分享一些经验？

3 个回答

可以看看这个链接：http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html，里面有关于用XML的方法。

回答于 2025-04-15 由 Python大师

分享举报

首先，保持两个文件夹结构，一个叫 source，另一个叫 build。把 source 放在版本控制里，也就是说要记录它的变化。不要把 build 放在版本控制里，安装的时候再重新生成它。

其次，阅读一下这个链接，了解如何设置文档源。

使用 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/

回答于 2025-04-15 由 Python大师

分享举报

正如在这里和这里提到的，

Sphinx对C++的原生支持主要是用来高亮、格式化和引用，并不是用来提取代码中的文档
breathe是基于chrisdew提到的讨论发展而来的

[下面是编辑内容]:

我在一个包含10个不同模块/领域的多万行C++库上测试了doxygen+breathe+sphinx工具链。我的总结是：

目前还不能完全使用
但要继续关注
最重要的是，如果你正在寻找一个值得投入时间的开源项目，可以考虑自己花点时间去参与。

让我详细解释一下这些观点：

我遇到了一些问题：
- 在doxygen标记中使用Latex标记（目前不支持，但应该容易实现）
- 一些解析错误（几个函数头定义），这些错误似乎会导致sphinx解析器出错，但如果我直接在sphinx的C++代码块中测试它们则没有问题。我不知道修复这些错误的难度，但这确实是个严重的功能障碍。
- 关于重载标识符的一些麻烦。似乎有一些支持可以处理在不同类和/或命名空间和/或doxygen xml输出文件中具有相同名称的函数。但是在一个类中显示或链接到10个重载构造函数中的一个，当前似乎不可行。在引用/链接的情况下，sphinx层面甚至有一个平行的（可能是暂时的）限制，breathe可能能够或不能够绕过。
- 目前没有办法显示一个类的所有（或所有受保护/私有）成员。这是由于另一个修复引入的，应该是非常简单的修复。
- 更一般来说，要知道目前这是通往Doxygen的xml输出的桥梁。这并不是说它会完全输出doxygen的内容，只是有上述的限制。相反，它提供了正好、不过多也不过少的可能性来：
  - 将所有内容在一个doxygen输出域中输出到一个巨大的页面上
  - 显示特定的函数、成员、结构体、枚举、类型定义或类，但这些必须手动指定。GitHub上有一个分支可能会想要解决这个整体概念问题，但目前没有未来的线索。
在我看来，一个完全功能的breathe将填补一个重要的空白，并开辟一条很酷的道路。所以仅仅因为潜在的收益，值得关注。
遗憾的是，创作者的维护似乎在未来会大幅减少。所以如果你在公司工作，并且能说服你的老板breathe适合他，或者你有一些空闲时间并在寻找一个真正有价值的项目，可以考虑给它一个分支！

最后提醒一下，也请注意doxylink这个Sphinx的贡献项目，它可能提供一个中间解决方案：建立一个类似教程的结构，引用（与css样式匹配的）旧的doxygen文档（我认为你甚至可以将相同的头部注入到sphinx中，并在doxygen文档上方显示）。这样，你的项目与sphinx保持关联，当breathe完全可用时，你就可以准备好跳入。但再次强调：如果它符合你的计划，请考虑给breathe一些支持。

回答于 2025-04-15 由 Python大师

分享举报

有人用Sphinx为C++项目写文档吗？

3 个回答

撰写回答