如何使用Sphinx生成C++文档

写文档很重要吗？

当你写了上万行代码，几十几百个函数和类，然后面对源文件一脸懵逼的时候你就不会有这个疑问了。如果规模较小，那么文档系统可能对自己没有太大帮助。但是写文档总可以帮助自己总结和记录工作。对其他人而言，要知道你的软件和代码如何使用，首先就是看你的说明文档，就和产品说明书一样，所以写文档是非常重要的。文档系统是什么呢？随着软件系统的复杂度日益增大，人们迫切需要一种规范的软件文档使维护和使用他人软件代码更加方便和标准化。这就催生了文档系统，例如Javadoc。通过在源代码中特殊的注释方式，就可以通过Javadoc生成非常标准化的注释文档，并且文档系统会分析类之间的继承关系，区分类型，形成查询索引，大大减轻了人工创建和维护文档的负担。更方便地是，它可以直接生成在线的网页使得文档的查阅变得很方便。

文档系统是什么呢？

随着软件系统的复杂度日益增大，人们迫切需要一种规范的软件文档使维护和使用他人软件代码更加方便和标准化。这就催生了文档系统，例如Javadoc。通过在源代码中特殊的注释方式，就可以通过Javadoc生成非常标准化的注释文档，并且文档系统会分析类之间的继承关系，区分类型，形成查询索引，大大减轻了人工创建和维护文档的负担。更方便地是，它可以直接生成在线的网页使得文档的查阅变得很方便。

Customnpc 的Javadoc截图

为什么使用Sphinx

C++标准的文档系统是Doxygen，而且Doxygen也可以支持很多其他语言。而Sphinx主要是写python文档用的。那么为什么还要使用Sphinx呢？原因有：

1. Doxygen生成的文档很丑。这让你的工程看起来活在90年代。而Sphinx的文档主题（readthedoc主题）看起来很现代。

   
   
   Eigen的Doxygen文档
   
   
   Tornado的Sphinx文档

2. Sphinx可以在Readthedoc网站上在线编译并托管发布，不需要建立自己的网站就可以在线发布文档了。

那么问题来了，Sphinx是python的文档系统，一个Python的文档系统，怎么就跑去生成C++文档了呢，主要还是这个颜值和Sphinx的强大功能。接下来就简单说下怎么做。

Doxygen+breathe+Sphinx

由于C++文档需要Doxygen去生成，因此有人发明了breathe去桥接Sphinx和Doxygen两个文档系统。可以把Doxygen的输出作为输入给Sphinx。后来又有人做了简化的工具exhale，只需要如下命令：

pip install exhale

就可以集成到Sphinx里去了（不过Doxygen还得另外下载安装）。具体参见文档。

根据网站介绍，你的c++工程需要这样的结构。

工程结构

其中include和src是你的c++工程，和文档系统其实没有关系，只是文档系统需要分析的对象。只有docs文件夹里的内容才是文档系统的主体。其中又可以看到index.rst，这个文件是Sphinx文档的主页，规定要显示的页面内容。conf.py是Sphinx的配置文件，里面需要包括插件配置以及其他参数的设置。需要注意的是，实际上我们首先应该做的是在doc文件夹下运行sphinx-quickstart生成文档编译所需的各项文件，再去修改这些配置。然后在conf.py中添加网站所述样例代码，就成功配置exhale的文档插件了。

# The `extensions` list should already be in here from `sphinx-quickstart`
extensions = [
    # there may be others here already, e.g. 'sphinx.ext.mathjax'
    'breathe',
    'exhale'
]

# Setup the breathe extension
breathe_projects = {
    "My Project": "./doxyoutput/xml"
}
breathe_default_project = "My Project"

# Setup the exhale extension
exhale_args = {
    # These arguments are required
    "containmentFolder":     "./api",
    "rootFileName":          "library_root.rst",
    "rootFileTitle":         "Library API",
    "doxygenStripFromPath":  "..",
    # Suggested optional arguments
    "createTreeView":        True,
    # TIP: if using the sphinx-bootstrap-theme, you need
    # "treeViewIsBootstrap": True,
    "exhaleExecutesDoxygen": True,
    "exhaleDoxygenStdin":    "INPUT = ../include"
}

# Tell sphinx what the primary language being documented is.
primary_domain = 'cpp'

# Tell sphinx what the pygments highlight language should be.
highlight_language = 'cpp'

在这里，其实最重要的一个参数就是 exhaleDoxygenStdin 中的INPUT参数。它指向你想生成文档的头文件。这时，文档系统以及可以调用doxygen并生成文档了，但是还需要让他在页面上显示出来。这就需要在index.rst中添加exhale_args对象中定义的rootFileName。如下图中的api/library_root：

添加根文件

需要注意的是这些文件必须放在toctree指令下面，并且不能和上面冒号所表示的选项相连，要空一行。另外，Sphinx也可以支持markdown和rst混合，但是这需要recommonmark插件支持。完成这一步，就以及可以生成文档了！

Sphinx RTD Theme

为了拥有readthedoc那样的漂亮主题，还需要pip install sphinx_rtd_theme并且在conf.py中添加相应代码：

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
import os 
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

if not on_rtd:  # only import and set the theme if we're building docs locally
    import sphinx_rtd_theme
    html_theme = 'sphinx_rtd_theme'
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

文档生成

在doc文件夹下执行make html就可以得到html网页版的documentation。效果非常赞！需要注意的是默认doxygen是不会输出类的private成员的，需要修改doxygen的配置或参数。

image.png

在文档系统中，我们不仅仅可以写代码注释说明，还可以加入公式甚至图片，相比另外写一个单独的说明文档，不知道高到哪里去了！在别人在代码和word之间来回穿梭时你只需要好好写注释，然后make一下，然后就可以和小姐姐谈笑风生去了，回来就可以看到最新且完美的文档网页！并且所有类型的链接都自动关联好了，非常好查询。比如下图中我们可以显示LaTeX，并注释函数参数。具体如何去写这种文档注释，有很多风格，请参考Doxygen的官方文档。

你们搞的这个文档系统啊，Excited!

还有很多其他功能和配置，就不在这里一一展示了。

总结

Sphinx文档系统非常好用，而且网页很漂亮，读起来非常愉悦。利用exhale构建文档系统的方法也很简单，只需要做三件小事（不谈安装）：1.sphinx-quickstart；2.修改index和conf.py；3.make！真的非常方便了。那么，大家一起努力来写出精美漂亮的工程文档吧!

作者：高压电力电容器
https://www.bilibili.com/read/cv3247399
略有修改