新版本发布时自动在 Github 个页面上构建文档

Question

在 github 存储库 my_repo 上，我可以正确设置 github 操作来触发构建、测试和文档：

name: CMake

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

env:
  # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
  BUILD_TYPE: Release

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Install dependencies
      run: sudo apt-get install -y --no-install-recommends libboost-all-dev libgdal-dev doxygen graphviz

    - name: Configure CMake
      run: cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}

    - name: Build
      run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}

    - name: Test
      working-directory: ${{github.workspace}}/build
      run: ctest -C ${{env.BUILD_TYPE}}

    - name: Docs
      working-directory: ${{github.workspace}}/build
      run: make doc

我还实现了 Release Drafter 来自动执行升级版本的过程：

name: Release Drafter

on:
  push:
    branches:
      - master
  pull_request:

    types: [opened, reopened, synchronize]

jobs:
  update_release_draft:
    runs-on: ubuntu-latest
    steps:

      - uses: release-drafter/release-drafter@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

现在，我想自动执行以下操作：

repo 中发布了主要版本 my_repo
这会触发我的 Github 页面存储库中的一个事件
文档内置于我的 Github 页面回购文件夹 softs/my_repo/docs
网站发布（相当于提交修改推送master分支）

我不太清楚如何实现它。我是否应该在我的 Github 页面中编写一个 github 工作流来“倾听”my_repo 项目中发生的事情？另外，我可以将版本从 my_repo 转发到 Doxygen 吗？

Answer 1

我最终能够实现我的目标。我将 post 这个示例代码，以防它可以使下一个初学者受益 Github 自动化文档构建的操作：

    name: CMake
    
    on:
      push:
        branches: [ master ]
      pull_request:
        branches: [ master ]
    
    env:
      # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
      BUILD_TYPE: Release
    
    jobs:
      build:
        # The CMake configure and build commands are platform agnostic and should work equally well on Windows or Mac.
        # You can convert this to a matrix build if you need cross-platform coverage.
        # See: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
        runs-on: ubuntu-latest
    
        steps:
        - uses: actions/checkout@v2
          with:
            # we want to find git tags to pass version to doxygen
            fetch-depth: 0
    
        - name: Install quetzal and Doxygen dependencies
          run: sudo apt-get install -y --no-install-recommends libboost-all-dev libgdal-dev doxygen graphviz
    
        - name: Configure CMake
          # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
          # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
          run: cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
    
        - name: Build
          # Build your program with the given configuration
          run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
    
        - name: Test
          working-directory: ${{github.workspace}}/build
          # Execute tests defined by the CMake configuration.
          # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
          run: ctest -C ${{env.BUILD_TYPE}}
    
        - name: Generate documentation
          working-directory: ${{github.workspace}}/build
          # this is defined in the repo docs/CMakeLists.txt file
          run: make docs
    
        - name: Moving Files
          run: |
            mv ${{github.workspace}}/build/docs/html ./docs/api
    
          # Deploy to GitHub Pages
        - name: Deploy
          uses: peaceiris/actions-gh-pages@v3
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: ./

在project/docs/CMakeLists.txt中：

# look for Doxygen package
# Require dot, treat the other components as optional
find_package(Doxygen
             REQUIRED dot
             OPTIONAL_COMPONENTS mscgen dia)

if(DOXYGEN_FOUND)
  # exclude sqlite code
  set(DOXYGEN_EXCLUDE_PATTERNS
        */sqlite3/*
  )
  # doxygen settings can be set here, prefixed with "DOXYGEN_"
  set(DOXYGEN_PROJECT_NAME "my-project")
  set(DOXYGEN_INPUT "mainpage.md")
  set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "mainpage.md")
  set(DOXYGEN_EXCLUDE_PATTERNS "README.md")
  set(DOXYGEN_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/docs")
  # this target will only be built if specifically asked to.
  # run "make docs" to create the doxygen documentation
  doxygen_add_docs(
    docs
    ${PROJECT_SOURCE_DIR}
    COMMENT "Generate API-documents for NoteSearch."
  )
endif(DOXYGEN_FOUND)

为了自动检索版本号并将其传递给 Doxygen（以及 C++ 代码），我可以采用 Brian Milco 在这里给出的解决方案：https://ipenguin.ws/2012/11/cmake-automatically-use-git-tags-as.html。他们在 2012 年 post 编辑了解决方案，因此在 2022 年可能会有更简单的方法来做同样的事情。但是，就我而言，它对我有用！

在根目录中CMakeLists.txt:

cmake_minimum_required(VERSION 3.5 FATAL_ERROR)

#
# VERSIONING
#

# Appends the cmake/modules path to MAKE_MODULE_PATH variable.
set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules ${CMAKE_MODULE_PATH})

include(GetGitRevisionDescription)
git_describe(VERSION --tags --dirty=-d)

#parse the version information into pieces.
string(REGEX REPLACE "^v([0-9]+)\..*" "\1" VERSION_MAJOR "${VERSION}")
string(REGEX REPLACE "^v[0-9]+\.([0-9]+).*" "\1" VERSION_MINOR "${VERSION}")
string(REGEX REPLACE "^v[0-9]+\.[0-9]+\.([0-9]+).*" "\1" VERSION_PATCH "${VERSION}")
string(REGEX REPLACE "^v[0-9]+\.[0-9]+\.[0-9]+(.*)" "\1" VERSION_SHA1 "${VERSION}")
set(VERSION_SHORT "${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}")

configure_file(${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules/version.cpp.in
                ${CMAKE_CURRENT_BINARY_DIR}/version.cpp)

set(version_file "${CMAKE_CURRENT_BINARY_DIR}/version.cpp")

#Add the version_file to the executables being built or it won't compile.
#add_executable(${PROJECT_NAME} ${source_files} ${ui_files} ${version_file})

#
# PROJECT DESCRIPTION
#
project(
  "project_name"
  LANGUAGES CXX
  VERSION ${VERSION_SHORT}

这会将 CMake 项目版本设置为自动检索的 git 版本标记，并默认在 set(DOXYGEN_PROJECT_NUMBER $(PROJECT_VERSION).

传递给 Doxygen 模块

可以在我的项目 https://github.com/Becheler/quetzal-CoalTL/commit/2ef5851cc6a34391d7a9ea64fb7c7122feb23b0a

中找到完整的工作解决方案

新版本发布时自动在 Github 个页面上构建文档

Automate doc build on Github pages when new version is released

versioning

doxygen

github-actions