Add doxygen to the cmake build and add doxygen build to CI. (#759)

Add doxygen to the cmake build and add doxygen build to CI.

.github/workflows/GCC.yml

@@ -26,6 +26,10 @@ jobs:
 
     steps:
 
+    - name: install-doxygen
+      run: |
+        sudo apt-get install doxygen graphviz
+        
     - name: checkout-fv3atm
       uses: actions/checkout@v3
       with:
@@ -37,7 +41,7 @@ jobs:
       uses: actions/cache@v3
       with:
         path: ${{ github.workspace }}/spack-develop
-        key: spack-${{ hashFiles('fv3atm/ci/spack.yaml') }}-gcc${{ matrix.gcc_ver }}-2
+        key: spack-${{ hashFiles('fv3atm/ci/spack.yaml') }}-gcc${{ matrix.gcc_ver }}-2-${{ matrix.cmake_opts }}-${{ matrix.mpich }}
 
     # Building dependencies takes 40+ min
     - name: spack-install
@@ -55,13 +59,6 @@ jobs:
         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 }}-2
-
     - name: build-fv3atm
       run: |
         . ${GITHUB_WORKSPACE}/spack-develop/share/spack/setup-env.sh
@@ -71,13 +68,22 @@ jobs:
         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
+        sed -i 's/doc /upp_doc /' upp/docs/CMakeLists.txt
         cd ${GITHUB_WORKSPACE}/build
-        cmake ${GITHUB_WORKSPACE}/fv3atm -DBUILD_TESTING=ON ${{ matrix.cmake_opts }}
+        cmake ${GITHUB_WORKSPACE}/fv3atm -DBUILD_TESTING=ON ${{ matrix.cmake_opts }} -DENABLE_DOCS=ON
         make -j2
+        ls -l /home/runner/work/fv3atm/fv3atm/fv3atm/io
 
+    - uses: actions/upload-artifact@v3
+      with:
+        name: docs
+        path: |
+          build/docs/html
+          
     - 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,6 +1,19 @@
+# This is the main CMake file for fv3atm.
+#
+# Dusan Jovic, Alex Richert
+cmake_minimum_required(VERSION 3.19)
+
+# Handle user build options.
+option(ENABLE_DOCS "Enable generation of doxygen-based documentation." OFF)
+
+# Determine whether or not to generate documentation.
+if(ENABLE_DOCS)
+  find_package(Doxygen REQUIRED)
+  add_subdirectory(docs)  
+endif()
+
 # Enable CI build & unit testing:
 if(BUILD_TESTING)
-  cmake_minimum_required(VERSION 3.19)
   project(fv3atm VERSION 1.0 LANGUAGES C CXX Fortran)
   include(ci/CMakeLists.txt)
 endif()

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