added docs workflow

.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_fv3atm:
+    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-fv3atm
+      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 -j2
+
+    - 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,10 @@
 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)
   find_package(Doxygen REQUIRED)
   add_subdirectory(docs)
 endif()