separate chgres_cube doxygen build from rest of UFS_UTILS, fix remaining chgres_cube doxygen warnings, turn on WARN_AS_ERROR for chgres_cube

.github/workflows/esmf-8.0.1_jasper-2.0.22_nceplibs-1.3.0.yml

@@ -120,6 +120,8 @@ jobs:
 
     - name: build-ufs-utils
       run: |
+        set -x
+        pwd
         export ESMFMKFILE=~/esmf/lib/esmf.mk
         cd ufs_utils
         mkdir build && cd build

CMakeLists.txt

@@ -71,6 +71,15 @@ if(EMC_EXEC_DIR)
   set(exec_dir exec)
 endif()
 
+# If doxygen documentation we enabled, build it. This must come before
+# adding the source code directories; the main documentation build
+# must happen before any of the utility document builds.
+if(ENABLE_DOCS)
+  find_package(Doxygen REQUIRED)
+  set(abs_top_srcdir "${CMAKE_SOURCE_DIR}")
+  add_subdirectory(docs)  
+endif()
+
 add_subdirectory(sorc)
 
 # Run unit tests.
@@ -79,8 +88,3 @@ if(BUILD_TESTING)
   add_subdirectory(tests)
 endif()
 
-# If doxygen documentation we enabled, build it.
-if(ENABLE_DOCS)
-  find_package(Doxygen REQUIRED)
-  add_subdirectory(docs)  
-endif()

docs/CMakeLists.txt

@@ -1,9 +1,9 @@
-# This is the CMake file for building the docs directory of NCEPLIBS-ip.
+# This is the CMake file for building the docs directory of NCEPLIBS
+# UFS_UTILS project.
 #
 # Ed Hartnett 10/5/20
 
 # Create doxyfile.
-set(abs_top_srcdir "${CMAKE_SOURCE_DIR}")
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
 
 # Build documentation with target all.

docs/Doxyfile.in

@@ -780,7 +780,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = @abs_top_srcdir@/sorc/fre-nctools.fd  @abs_top_srcdir@/sorc/nst_tf_chg.fd
+EXCLUDE                = @abs_top_srcdir@/sorc/fre-nctools.fd  @abs_top_srcdir@/sorc/chgres_cube.fd
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

docs/user_guide.md

@@ -10,8 +10,8 @@ https://github.com/NOAA-EMC/UFS_UTILS.
 
 ## The Utilities
 
-- chgres_cube - Creates cold start initial conditions for FV3 model
-  runs.
+- <a href="chgres_cube/index.html">chgres_cube</a> - Creates cold
+  start initial conditions for FV3 model runs.
 
 - emcsfc_ice_blend - Blends National Ice Center sea ice cover and EMC
   sea ice concentration data to create a global sea ice analysis used

sorc/chgres_cube.fd/CMakeLists.txt

@@ -43,3 +43,9 @@ if(OpenMP_Fortran_FOUND)
 endif()
 
 install(TARGETS ${exe_name} RUNTIME DESTINATION ${exec_dir})
+
+# If doxygen documentation we enabled, build it.
+if(ENABLE_DOCS)
+  add_subdirectory(docs)  
+endif()
+

sorc/chgres_cube.fd/atmosphere.F90

@@ -781,7 +781,9 @@ end subroutine convert_winds
 !!     PS           REAL (IX) SURFACE PRESSURE (PA)                      
 !!   OUTPUT ARGUMENT LIST:                                               
 !!     PM           REAL (IX,KM) MID-LAYER PRESSURE (PA)                 
-!!     DP           REAL (IX,KM) LAYER DELTA PRESSURE (PA)               
+!!     DP           REAL (IX,KM) LAYER DELTA PRESSURE (PA)
+!!
+!! @param localpet ESMF local persistent execution thread  
 !!
 !! @author HANN_MING HENRY JUANG, JUANG, Fanglin Yang, S. Moorthi
  subroutine newpr1(localpet)

sorc/chgres_cube.fd/docs/CMakeLists.txt

@@ -0,0 +1,15 @@
+# This is the CMake file for building the docs directory of UFS_UTILS
+# utility chgres_cube.
+#
+# Ed Hartnett 3/8/21
+
+# Create doxyfile.
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+
+# Build documentation with target all.
+add_custom_target(chgres_cube_doc ALL
+  ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+  COMMENT "Generating API Documentation with Doxygen" VERBATIM)
+
+