【CMake 系列】(六)用 Doxygen、Sphinx 与 Breathe 创建文档
Opened this issue · 0 comments
今天,来说说 CMake 中另外一个可能比较枯燥的环节:文档。
前言
说起文档,就不得不提文档的维护了,如果纯手写,难免会遇到代码与文档不一致的情况,理想的状态下,最好全部由解析代码后生成,再加上开发人员少量写的说明性文档即可。
之前我也在 你的团队需要更好的 API 文档流程 里说过,好的 API 文档的特点也是类似。
至于我们今天要说的 C/C++ 的文档,主流的方案就是 Doxygen + Sphinx + Breathe,其它的工具相对显得小众了,可以去维基上看看 (实际上我也没有细看 :P)。
准备环境
- 安装 Doxygen:
sudo apt install doxygen
; - 安装 Sphinx 与 Breathe:
pip3 install Sphinx breathe
,注意 目前 Sphinx 需要 Python3,这里也是用 pip3 安装的;
下面来依次介绍下它们三个。
Doxygen
Doxygen 算是 C/C++ 中最有名的,历史悠久(1997/10/26 发布了第一个版本),众多开源的 C/C++ 也是选择了它作为文档工具。
Doxygen 的原理很简单,就是给函数、变量声明等地方加上 comments,然后通过解析它们来生成对应的文档。
如下,就是官网里面给出的一个小例子:
/*! \fn int open(const char *pathname,int flags)
\brief Opens a file descriptor.
\param pathname The name of the descriptor.
\param flags Opening flags.
*/
其它内容也很容易学习,这里不再赘述。
使用 Doxygen 也很简单,你可以三步走:
- 运行
doxygen -g Doxyfile
来生成配置; - 按需求修改配置;
- 运行
doxygen
生成文档;
如果你配置了 HTML 的输出,那就可以直接在浏览器打开。
到这里,Doxygen 能做到很简单就能生成文档了,但还是差一些,因为这样生成的文档,比较不符合现代的审美。
那该怎么办呢?接下来就该 Sphinx 上场了。
Sphinx 与 Breathe
Sphinx 目前的『市场』占有率非常高,因为它有免费的文档托管 Read the Docs,支持线上预览以及版本历史等,由此大多数的 Python 文档都是选择它来生成文档的。
对的,你没听错,一开始它确实是为了 Python 文档而出现的,后来也逐渐支持其它语言,包括 C/C++,只是,Doxygen 与 Sphinx 不能直接关联,即 Sphinx 不能直接使用 Doxygen 生成的内容来生成 Sphinx 文档,它还需要一个插件来做适配,Breathe 就是为了连接 Doxygen 与 Sphinx 而生。
Sphinx 默认的解析文档是 reStructureText
,你可以认为是高级版本的 Markdown
,也就是比它功能更强大。当然,你也可以使用 Markdown 来写文档,它有一个专门的插件来做这件事。
所以,操作流程大致如下:
- Doxygen 解析源码文件中的 comments 生成 xml 文档素材;
- Sphinx 使用 Breathe 插件解析的 xml 文档素材,以及解析现成的
reStructureText
文档,生成最后的 HTML 或者其他文档类型;
具体的操作参考 Breathe 文档 以及 sampledoc tutorial 进行:
开始之前需要准备 index.rst
:
My Awesome project's documentation!
===================================
.. doxygenindex::
:project: doxygen_docs
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
- 将
Doxygen
中的GENERATE_XML
设置为YES
; - 用
sphinx-quickstart
这个交互式命令生成conf.py
,与index.rst
放在一起,然后还可以进一步修改里面的相关内容; - 确保 Breathe 在 Python path 内,不在的话,需要在
conf.py
内加上sys.path.append( "/path/to/breathe/" )
; - 在
conf.py
加上 Breathe 需要的配置:breathe_projects = { "myproject": "/path/to/doxygen/xml" }
,breathe_default_project = "myproject"
; - 执行
sphinx-build -b html -c /path/to/conf.py_dir /path/to/doxygen/xml /output/dir
最后,就能看到生成的 HTML 文档了,对比下之前 Doxygen 直接生成的 HTML 文档,会发现美观了很多。
CMake 配置
终于来到了 CMake 环节,我们该如何把上述的复杂步骤结合起来?
CMake 提供了很简单的 doxygen_add_docs
,通过简单配置,你就能生成 Doxygen 文档:
find_package(Doxygen REQUIRED)
# 这里只是举例,其它 Doxygen 配置加上 `DOXYGEN_` 前缀即可
set(DOXYGEN_GENERATE_HTML YES)
set(DOXYGEN_EXTRACT_ALL YES)
set(DOXYGEN_BUILTIN_STL_SUPPORT YES)
doxygen_add_docs(doxygen_docs "${PROJECT_SOURCE_DIR}/src")
那么 Sphinx 呢?我找到一个现成可以用的:cmake-sphinx ,但是需要修改一部分,大体上这里的功能可以完全满足我们的使用。
# 别忘了生成 XML,同时可以去掉上面的 DOXYGEN_GENERATE_HTML
set(DOXYGEN_GENERATE_XML YES)
find_package(Sphinx REQUIRED COMPONENTS breathe)
set(SPHINX_VERSION ${PROJECT_VERSION})
set(SPHINX_LANGUAGE zh_CN)
sphinx_add_docs(
docs
BREATHE_PROJECTS
doxygen_docs
BUILDER
html
SOURCE_DIRECTORY
.)
然后,在编译目录下,打开 docs/docs/index.html
就能看到美观的文档了。