写文档重要吗？
当您编写数万行代码、数百个函数和类，然后面对源文件时，您不会遇到这个问题。如果规模较小，文档系统可能对您帮助不大。但是写文档总是可以帮助你总结和记录你的工作。对于其他人来说，要知道如何使用软件和代码，第一件事就是查看文档，就像产品手册一样，因此编写文档非常重要。
文档系统是什么呢？
随着软件系统的复杂度日益增大，人们迫切需要一种规范的软件文档使维护和使用他人软件代码更加方便和标准化。这就催生了文档系统，例如Javadoc。通过在源代码中特殊的注释方式，就可以通过Javadoc生成非常标准化的注释文档，并且文档系统会分析类之间的继承关系，区分类型，形成查询索引，大大减轻了人工创建和维护文档的负担。更方便地是，它可以直接生成在线的网页使得文档的查阅变得很方便。
为什么使用Sphinx
C++标准的文档系统是Doxygen，而且Doxygen也可以支持很多其他语言。而Sphinx主要是写python文档用的。那么为什么还要使用Sphinx呢？原因有：
- Doxygen生成的文档很丑。这让你的工程看起来活在90年代。而Sphinx的文档主题（readthedoc主题）看起来很现代。
- Sphinx可以在Readthedoc网站上在线编译并托管发布，不需要建立自己的网站就可以在线发布文档了。
那么问题来了，Sphinx是python的文档系统，一个Python的文档系统，怎么就跑去生成C++文档了呢，主要还是这个颜值和Sphinx的强大功能。接下来就简单说下怎么做。
Doxygen+breathe+Sphinx
由于C++文档需要Doxygen去生成，因此有人发明了breathe去桥接Sphinx和Doxygen两个文档系统。可以把Doxygen的输出作为输入给Sphinx。后来又有人做了简化的工具exhale，只需要如下命令：
pip install exhale
根据网站介绍，你的c++工程需要这样的结构。
其中include和src是你的c++工程，和文档系统其实没有关系，只是文档系统需要分析的对象。只有docs文件夹里的内容才是文档系统的主体。其中又可以看到index.rst，这个文件是Sphinx文档的主页，规定要显示的页面内容。conf.py是Sphinx的配置文件，里面需要包括插件配置以及其他参数的设置。需要注意的是，实际上我们首先应该做的是在doc文件夹下运行sphinx-quickstart生成文档编译所需的各项文件，再去修改这些配置。然后在conf.py中添加网站所述样例代码，就成功配置exhale的文档插件了。
在这里，其实最重要的一个参数就是 “exhaleDoxygenStdin” 中的INPUT参数。它指向你想生成文档的头文件。这时，文档系统以及可以调用doxygen并生成文档了，但是还需要让他在页面上显示出来。这就需要在index.rst中添加exhale_args对象中定义的rootFile。如下图中的api/library_root：
需要注意的是这些文件必须放在toctree指令下面，并且不能和上面冒号所表示的选项相连，要空一行。另外，Sphinx也可以支持markdown和rst混合，但是这需要recommonmark插件支持。完成这一步，就以及可以生成文档了！
文档生成
在doc文件夹下执行make html就可以得到html网页版的documentation。效果非常赞！需要注意的是默认doxygen是不会输出类的private成员的，需要修改doxygen的配置或参数。
还有很多其他功能和配置，就不在这里一一展示了。
总结