如何配置Codedocs.xyz等工具在构建后生成CMake项目文档？

一、配置Codedocs.xyz预生成Doxyfile #

Codedocs支持自定义预构建步骤来生成Doxyfile，具体操作如下：

• 在项目根目录创建codedocs.yml配置文件（也可通过平台网页界面配置），指定pre-build阶段的命令，调用CMake生成Doxyfile。
  比如你的CMake脚本通过configure_file(Doxyfile.in Doxyfile @ONLY)生成Doxyfile，预构建命令可写：

  cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
  

• 若平台环境未预装CMake或Doxygen，可在pre-build阶段添加安装命令（以Linux环境为例）：

  sudo apt update && sudo apt install -y cmake doxygen
  

二、确保文档生成依赖指定构建工作流 #

有两种可靠方案实现这一需求：

1. CMake内部构建依赖约束 #

在CMakeLists.txt中，将文档生成目标绑定到核心构建目标的成功状态。比如你的项目主目标是MyApp，可这样配置：

add_executable(MyApp src/main.cpp)
# 定义文档生成目标
add_custom_target(doc
  COMMAND doxygen ${CMAKE_BINARY_DIR}/Doxyfile
  DEPENDS MyApp  # 依赖主构建目标，确保先完成编译再生成文档
  WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
)

无论本地还是远程执行文档生成命令，都会先检查主目标是否构建成功，失败则终止文档生成。

2. 托管平台工作流编排 #

在codedocs.yml中拆分工作流阶段，设置文档阶段依赖构建阶段的成功：

stages:
  - build
  - docs

build:
  script:
    - cmake -S . -B build
    - cmake --build build

docs:
  script:
    - cmake -S . -B build -DDOCS_BUILD=ON
    - cmake --build build --target doc
  needs: build  # 仅当build阶段成功完成，才触发docs阶段

这种方式直接在平台层面控制执行顺序，完全避免了构建失败后无效的文档生成操作。

内容的提问来源于stack exchange，提问作者joaocandre