Automate doc build on Github pages when new version is released

On a github repository my_repo, I could correctly set up github actions to trigger build, tests and documentation:

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

I also implemented Release Drafter to automate the process of bumping versions:

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 }}

Now, I would like to automate the following:

a major version is released in the repo my_repo
this triggers an event in my Github Pages repo
the documentation is built in my Github Pages repo in the folder softs/my_repo/docs
the website is published (that is equivalent to commiting the changes and pushing the master branch)

I don't exactly know how to implement that. Should I write a github workflow in my Github pages to "listen" what is happening in the my_repo project? Also, I can I forward the version from the my_repo to Doxygen?

Solution

I ended up being able to reach my goals. I will post this sample code in case it could benefit the next beginner with Github Action to automate the documentation building:

    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: ./

In the 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)

To automatically retrieve the version number and pass it to Doxygen (as well as to the C++ code), I could adapt the solution given by Brian Milco here: https://ipenguin.ws/2012/11/cmake-automatically-use-git-tags-as.html . They posted the solution in 2012, so there may be easier ways to do the same thing in 2022. But, as far as I am concerned, it works for me!

In the root 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}

This sets the CMake project version to the automatically retrieved git version tag, and it is passed to the Doxygen module by a default on set(DOXYGEN_PROJECT_NUMBER $(PROJECT_VERSION).

A complete working solution can be find on my project at https://github.com/Becheler/quetzal-CoalTL/commit/2ef5851cc6a34391d7a9ea64fb7c7122feb23b0a