fix the documentation build for fv3atm, getting the CI to work

.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() }}

.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.*

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()

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)
 

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 \