CMake使用Doxygen自动生成文档

标签: C++学习与实践文|吴羽舒

引言

官网: https://www.doxygen.nl/

Doxygen is the de facto standard tool for generating documentation from annotated C++ sources.

Doxygen是一个应用广泛支持多种编程语言和多种输出格式的源码文档生成工具，从1.8.0版本开始支持Markdown语法标记文档。

安装

  • 软件包安装:
$ sudo yum install doxygen graphviz

$ doxygen --version
1.8.5
  • 源码编译安装：
$ git clone https://github.com/doxygen/doxygen.git
$ cd doxygen
$ mkdir build
$ cd build
$ cmake -G "Unix Makefiles" ..
$ make
$ make install

基本使用

  • 产生配置文件:
$ doxygen -g


Configuration file `Doxyfile' created.

Now edit the configuration file and enter

  doxygen Doxyfile

to generate the documentation for your project
  • 修改配置文件:
$ vim Doxyfile

PROJECT_NAME           = "Test Doxygen"
PROJECT_NUMBER         = 1.3.2
PROJECT_BRIEF          = Test Doxygen Tool
OUTPUT_DIRECTORY       = docs
RECURSIVE              = YES
INPUT                  = src
FILE_PATTERNS          = *.h *.c *.hpp *.cpp
  • 生成文档:
$ doxygen

$ open docs/html/index.html

CMake集成Doxygen工具

$ cat Doxyfile.in

PROJECT_NAME           = "Test Doxygen"
PROJECT_NUMBER         = 1.3.2
PROJECT_BRIEF          = Test Doxygen Tool
OUTPUT_DIRECTORY       = docs

INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/src/
FILE_PATTERNS          = *.h *.c *.hpp *.cpp

RECURSIVE              = YES

EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
  • 修改CMakeLists.txt调用Doxygen生成文档:
find_package(Doxygen)
if(DOXYGEN_FOUND)
   configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
   add_custom_target(doc ALL
       ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
       WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
       COMMENT "Generating API documentation with Doxygen" VERBATIM
   )
endif(DOXYGEN_FOUND)

这样执行make all时自动就执行了make doc，将会自动生成文档。

后记

如果有一个大型项目，Doxygen可以帮助快速建立文档，然后逐步完善文档。

▲