From 6b0794d0cda4bd2467e08714f512ba3b5bd82892 Mon Sep 17 00:00:00 2001 From: Edward Hartnett <38856240+edwardhartnett@users.noreply.github.com> Date: Tue, 21 Jan 2025 11:40:13 -0700 Subject: [PATCH] Fix the documentation build for fv3atm, getting the CI to work (#906) Change the CMake option ENABLE_DOCS to ENABLE_FV3ATM_DOCS, in order to avoid invoking the documentation build of UPP. Add a new CI workflow called "docs", and take the documentation build out of the GCC workflow. This will be more useful to programmers because having the "docs" CI run fail is pretty obvious. --- .github/workflows/GCC.yml | 15 +--- .github/workflows/docs.yml | 138 +++++++++++++++++++++++++++++++++++++ CMakeLists.txt | 5 +- docs/CMakeLists.txt | 20 +++--- docs/Doxyfile.in | 5 +- 5 files changed, 156 insertions(+), 27 deletions(-) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/GCC.yml b/.github/workflows/GCC.yml index 86d0bf668..4f8bbf7b5 100644 --- a/.github/workflows/GCC.yml +++ b/.github/workflows/GCC.yml @@ -74,8 +74,8 @@ jobs: steps: - # Only do Doxygen and gcovr build for one job - - name: decide-doc-gcovr-build + # Only do gcovr build for one job + - name: decide-gcovr-build run: | if [[ "${{ matrix.cmake_opts }}" == "-D32BIT=ON" && "${{ matrix.gcc_ver }}" == 12 && "${{ matrix.mpi }}" == mpich ]]; then echo 'devbuild=ON' | tee -a ${GITHUB_ENV} @@ -86,7 +86,6 @@ jobs: - name: install-utilities run: | - sudo apt-get install doxygen graphviz python3 -m pip install gcovr - name: install-cmake @@ -121,7 +120,7 @@ jobs: export CC=mpicc export CXX=mpicxx export FC=mpif90 - cmake ${GITHUB_WORKSPACE}/fv3atm -DBUILD_TESTING=ON ${{ matrix.cmake_opts }} -DENABLE_DOCS=ON ${{ env.gcov_cmake }} + cmake ${GITHUB_WORKSPACE}/fv3atm -DBUILD_TESTING=ON ${{ matrix.cmake_opts }} ${{ env.gcov_cmake }} make -j2 - name: run-tests @@ -144,14 +143,6 @@ jobs: ${{ github.workspace }}/build/*.html ${{ github.workspace }}/build/*.css - - name: upload-docs - uses: actions/upload-artifact@v4 - if: ${{ env.devbuild == 'ON' }} - with: - name: docs-fv3atm - path: | - build/docs/html - - name: debug-artifacts uses: actions/upload-artifact@v4 if: ${{ failure() }} diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..fbc145e65 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,138 @@ +# This is a CI workflow for the fv3atm project. +# +# This workflow builds the fv3atm doxygen documentation. +# +# Ed Hartnett, 1/9/25 + +name: docs +on: + push: + branches: + - develop + pull_request: + branches: + - develop + +jobs: + build_spack: + runs-on: ubuntu-latest + + strategy: + matrix: + gcc_ver: ["12"] + mpi: ["mpich"] + + steps: + + - name: checkout-fv3atm + uses: actions/checkout@v4 + with: + path: ${{ github.workspace }}/fv3atm + submodules: recursive + + - name: install-cmake + run: | + cd ${{ github.workspace }} + curl -f -s -S -R -L https://github.com/Kitware/CMake/releases/download/v3.29.2/cmake-3.29.2-Linux-x86_64.tar.gz | tar -zx + echo "${{ github.workspace }}/cmake-3.29.2-linux-x86_64/bin" >> $GITHUB_PATH + + - name: cache-spack + id: cache-spack + uses: actions/cache@v4 + with: + path: ${{ github.workspace }}/spack-develop + key: spack-${{ hashFiles('fv3atm/ci/spack.yaml') }}-gcc${{ matrix.gcc_ver }}-${{ matrix.mpi }} + + # Building dependencies takes 40+ min + - name: spack-install + if: steps.cache-spack.outputs.cache-hit != 'true' + run: | + wget --no-verbose https://github.com/spack/spack/archive/refs/heads/develop.zip + unzip develop.zip -d ${GITHUB_WORKSPACE}/ &> unzip.out + . ${GITHUB_WORKSPACE}/spack-develop/share/spack/setup-env.sh + spack env create gcc${{ matrix.gcc_ver }} ${GITHUB_WORKSPACE}/fv3atm/ci/spack.yaml + spack env activate gcc${{ matrix.gcc_ver }} + spack compiler find | grep gcc@${{ matrix.gcc_ver }} + spack external find gmake cmake git git-lfs perl python ${{ matrix.mpi }} + spack config add "packages:all:require:['%gcc@${{ matrix.gcc_ver }}']" + spack config add "packages:mpi:require:'${{ matrix.mpi }}'" + spack concretize |& tee ${SPACK_ENV}/log.concretize + spack install -j2 --fail-fast + echo "spackrc=$?" >> ${GITHUB_ENV} + spack clean --all + + build_docs: + needs: build_spack + runs-on: ubuntu-latest + + strategy: + matrix: + cmake_opts: ["-D32BIT=ON"] + gcc_ver: ["12"] + mpi: ["mpich"] + + steps: + + # Only do Doxygen and gcovr build for one job + - name: decide-doc-gcovr-build + run: | + if [[ "${{ matrix.cmake_opts }}" == "-D32BIT=ON" && "${{ matrix.gcc_ver }}" == 12 && "${{ matrix.mpi }}" == mpich ]]; then + echo 'devbuild=ON' | tee -a ${GITHUB_ENV} + echo 'gcov_cmake="-DCMAKE_Fortran_FLAGS=-fprofile-abs-path -fprofile-arcs -ftest-coverage -O0"' | tee -a ${GITHUB_ENV} + else + echo 'devbuild=OFF' | tee -a ${GITHUB_ENV} + fi + + - name: install-utilities + run: | + sudo apt-get install doxygen graphviz + + - name: install-cmake + run: | + cd ${{ github.workspace }} + curl -f -s -S -R -L https://github.com/Kitware/CMake/releases/download/v3.29.2/cmake-3.29.2-Linux-x86_64.tar.gz | tar -zx + echo "${{ github.workspace }}/cmake-3.29.2-linux-x86_64/bin" >> $GITHUB_PATH + + - name: checkout-fv3atm + uses: actions/checkout@v4 + with: + path: ${{ github.workspace }}/fv3atm + submodules: recursive + + - name: cache-spack + id: cache-spack + uses: actions/cache/restore@v4 + with: + path: ${{ github.workspace }}/spack-develop + key: spack-${{ hashFiles('fv3atm/ci/spack.yaml') }}-gcc${{ matrix.gcc_ver }}-${{ matrix.mpi }} + + - name: docs-build + run: | + . ${GITHUB_WORKSPACE}/spack-develop/share/spack/setup-env.sh + spack env activate gcc${{ matrix.gcc_ver }} + spack load $(spack find --format "{name}") + cd ${GITHUB_WORKSPACE}/fv3atm + git clone https://github.com/NOAA-EMC/CMakeModules + git clone --recurse-submodules https://github.com/NOAA-PSL/stochastic_physics stochastic_physics_repo + mkdir ${GITHUB_WORKSPACE}/build + cd ${GITHUB_WORKSPACE}/build + export CC=mpicc + export CXX=mpicxx + export FC=mpif90 + cmake ${GITHUB_WORKSPACE}/fv3atm -DBUILD_TESTING=ON ${{ matrix.cmake_opts }} -DENABLE_FV3ATM_DOCS=ON ${{ env.gcov_cmake }} + make doxygen_doc + + - name: upload-docs + uses: actions/upload-artifact@v4 + if: ${{ env.devbuild == 'ON' }} + with: + name: docs-fv3atm + path: | + build/docs/html + + - name: debug-artifacts + uses: actions/upload-artifact@v4 + if: ${{ failure() }} + with: + name: ccpp_prebuild_logs-gcc${{ matrix.gcc_ver }}-${{ matrix.mpi }}-${{ matrix.cmake_opts }} + path: ${{ github.workspace }}/build/ccpp/ccpp_prebuild.* diff --git a/CMakeLists.txt b/CMakeLists.txt index cdf597df2..cef00a251 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -4,10 +4,11 @@ cmake_minimum_required(VERSION 3.19) # Handle user build options. -option(ENABLE_DOCS "Enable generation of doxygen-based documentation." OFF) +option(ENABLE_FV3ATM_DOCS "Enable generation of doxygen-based documentation." OFF) # Determine whether or not to generate documentation. -if(ENABLE_DOCS) +if(ENABLE_FV3ATM_DOCS) + message(STATUS "We will build the fv3atm doxygen documentation.") find_package(Doxygen REQUIRED) add_subdirectory(docs) endif() diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 6273869d8..17ed6c084 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -2,16 +2,12 @@ # # Ed Hartnett 12/28/23 -IF(ENABLE_DOCS) - - # Create doxyfile. - SET(abs_top_srcdir "${CMAKE_SOURCE_DIR}") - SET(abs_top_builddir "${CMAKE_BINARY_DIR}") - CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY) - ADD_CUSTOM_TARGET(doxygen_doc ALL - ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Generating API Documentation with Doxygen" VERBATIM) - -ENDIF(ENABLE_DOCS) +# Create doxyfile. +SET(abs_top_srcdir "${CMAKE_SOURCE_DIR}") +SET(abs_top_builddir "${CMAKE_BINARY_DIR}") +CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY) +ADD_CUSTOM_TARGET(doxygen_doc ALL + ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMENT "Generating API Documentation with Doxygen" VERBATIM) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index d89e7145e..5c4a8b8f4 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -864,8 +864,11 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. +# Note EJH: Add @abs_top_srcdir@ after doxygenating those code +# files. The comments in one of them are activating a bug in doxygen +# and need to be cleaned up to get a doxygen build working. + INPUT = @abs_top_srcdir@/docs/user_guide.md \ - @abs_top_srcdir@ \ @abs_top_srcdir@/ccpp \ @abs_top_srcdir@/cpl \ @abs_top_srcdir@/io \