12.1 使用Doxygen构建文档

NOTE:此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-12/recipe-01 中找到，其中包含一个C++示例。该示例在CMake 3.5版(或更高版本)中是有效的，并且已经在GNU/Linux、macOS和Windows上进行过测试。

Doxygen(http://www.doxygen.nl )是非常流行的源代码文档工具。可以在代码中添加文档标记作为注释，而后运行Doxygen提取这些注释，并以Doxyfile配置文件中定义的格式创建文档。Doxygen可以输出HTML、XML，甚至LaTeX或PDF。本示例将展示，如何使用CMake来构建Doxygen文档。

准备工作

使用前几章中介绍的消息库的简化版本。目录结构如下:

  1. .
  2. ├── cmake
  3. │    └── UseDoxygenDoc.cmake
  4. ├── CMakeLists.txt
  5. ├── docs
  6. │    ├── Doxyfile.in
  7. │    └── front_page.md
  8. └── src
  9.     ├── CMakeLists.txt
  10.     ├── hello-world.cpp
  11.     ├── Message.cpp
  12.     └── Message.hpp

我们仍然在src子目录下放置源代码，并且在CMake子目录中有自定义的CMake模块。由于重点是文档，所以消除了对UUID的依赖，并简化了源代码。最大的区别是头文件中的大量代码注释：

  1. #pragma once
  3. #include <iosfwd>
  4. #include <string>
  6. / * ! \file Message.hpp * /
  8. /*! \class Message
  9. * \brief Forwards string to screen
  10. * \author Roberto Di Remigio
  11. * \date 2018
  12. * /
  14. class Message {
  15. public:
  16.   /*! \brief Constructor from a string
  17.   * \param[in] m a message
  18.   */
  19.   Message(const std::string &m) : message_(m) {}
  20.   /*! \brief Constructor from a character array
  21.   * \param[in] m a message
  22.   */
  23.   Message(const char * m): message_(std:: string(m)){}
  25.   friend std::ostream &operator<<(std::ostream &os, Message &obj) {
  26.     return obj.printObject(os);
  27.   }
  28. private:
  29.   /*! The message to be forwarded to screen */
  30.   std::string message_;
  31.   /*! \brief Function to forward message to screen
  32.   * \param[in, out] os output stream
  33.   */
  34.   std::ostream &printObject(std::ostream &os);
  35. };

这些注释的格式是/*!*/，并包含一些Doxygen可以理解的特殊标记(参见http://www.stack.nl/~dimitri/Doxygen/manual/docblocks.html )。

具体实施

首先，来看看根目录下的CMakeLists.txt：

  1. 我们声明了一个C++11项目：

    1. cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
    2. project(recipe-01 LANGUAGES CXX)
    3. set(CMAKE_CXX_STANDARD 11)
    4. set(CMAKE_CXX_EXTENSIONS OFF)
    5. set(CMAKE_CXX_STANDARD_REQUIRED ON)

  2. 为动态库和静态库，以及可执行文件定义了输出目录：

    1. include(GNUInstallDirs)
    2. set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY
    3.     ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
    4. set(CMAKE_LIBRARY_OUTPUT_DIRECTORY
    5.     ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
    6. set(CMAKE_RUNTIME_OUTPUT_DIRECTORY
    7.     ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_BINDIR})

  3. 将cmake子目录追加到CMAKE_MODULE_PATH。这是需要CMake找到我们的自定义模块：

    1. list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")

  4. UseDoxygenDoc.cmake自定义模块。将在后面讨论它的内容:

    1. include(UseDoxygenDoc)

  5. 然后添加src子目录:

    1. add_subdirectory(src)

src子目录中的CMakeLists.txt文件包含以下构建块:

  1. 添加了消息库:

    1. add_library(message STATIC
    2.   Message.hpp
    3.   Message.cpp
    4.   )

  2. 然后，声明add_doxygen_doc函数。这个函数可以理解这些参数：BUILD_DIR、DOXY_FILE、TARGET_NAME和COMMENT。使用cmake_parse_arguments标准CMake命令解析这些参数：

    1. function(add_doxygen_doc)
    2.   set(options)
    3.   set(oneValueArgs BUILD_DIR DOXY_FILE TARGET_NAME COMMENT)
    4.   set(multiValueArgs)
    6.   cmake_parse_arguments(DOXY_DOC
    7.     "${options}"
    8.     "${oneValueArgs}"
    9.     "${multiValueArgs}"
    10.     ${ARGN}
    11.   )
    13.   # ...
    14. endfunction()

  3. Doxyfile包含用于构建文档的所有Doxygen设置。一个模板Doxyfile.in文件作为函数参数DOXY_FILE传递，并解析为DOXY_DOC_DOXY_FILE变量。使用如下方式，配置模板文件Doxyfile.in:

    1. configure_file(
    2.   ${DOXY_DOC_DOXY_FILE}
    3.   ${DOXY_DOC_BUILD_DIR}/Doxyfile
    4.   @ONLY
    5.   )

  4. 然后，定义了一个名为DOXY_DOC_TARGET_NAME的自定义目标，它将使用Doxyfile中的设置执行Doxygen，并在DOXY_DOC_BUILD_DIR中输出结果:

    1. add_custom_target(${DOXY_DOC_TARGET_NAME}
    2.   COMMAND
    3.     ${DOXYGEN_EXECUTABLE} Doxyfile
    4.   WORKING_DIRECTORY
    5.     ${DOXY_DOC_BUILD_DIR}
    6.   COMMENT
    7.     "Building ${DOXY_DOC_COMMENT} with Doxygen"
    8.   VERBATIM
    9.   )

  5. 最后，为用户打印一条状态信息:

    1. message(STATUS "Added ${DOXY_DOC_TARGET_NAME} [Doxygen] target to build documentation")

可以像往常一样配置项目：

  1. $ mkdir -p build
  2. $ cd build
  3. $ cmake ..
  4. $ cmake --build .

可以通过调用自定义文档目标来构建文档:

  1. $ cmake --build . --target docs

您将注意到构建树中出现了一个_build子目录。它包含Doxygen从源文件生成的HTML文档。用浏览器打开index.html将显示Doxygen欢迎页面。

如果导航到类列表，例如：可以浏览Message类的文档:

12.1 使用Doxygen构建文档 - 图1

工作原理

默认情况下，CMake不支持文档构建。但是，我们可以使用add_custom_target执行任意操作。需要注意的是，需要确保构建文档所需的工具(本例中是Doxygen和Perl)在系统上可用。

此外，请注意UseDoxygenDoc.cmake自定义模块只做以下工作:

  • 执行对Doxygen和Perl可执行程序的搜索
  • 定义函数

使用add_doxygen_doc函数对文档目标进行创建。这个显式模式要优于隐式模式，我们也认为这是很好的实践方式：不要使用模块来执行类似宏(或函数)的操作。

为了限制变量定义的范围和可能出现的副作用，我们使用函数而不是宏实现了add_doxygen_doc。这种情况下，函数和宏都可以工作(并且会产生相同的结果)，但是建议优先使用函数而不是宏，除非需要修改父范围中的变量。

NOTE:在cmake 3.9中添加了FindDoxygen.cmake模块。实现了doxygen_add_docs函数，其行为与我们在本示例中给出的宏类似。要了解更多细节，请访问https://cmake.org/cmake/help/v3.9/module/FindDoxygen.html 查看在线文档。