splitting doxygen builds so each utility gets its own documentation build

docs/Doxyfile.in

@@ -745,7 +745,7 @@ WARN_AS_ERROR = NO
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT = @abs_top_srcdir@/docs/user_guide.md @abs_top_srcdir@/sorc 
+INPUT = @abs_top_srcdir@/docs/user_guide.md 
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -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/chgres_cube.fd
+EXCLUDE                = @abs_top_srcdir@/sorc
 
 # 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

@@ -13,41 +13,47 @@ https://github.com/NOAA-EMC/UFS_UTILS.
 - <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
-  to update the GFS once per day.
+- <a href="emcsfc_ice_blend/index.html">emcsfc_ice_blend</a> - Blends
+  National Ice Center sea ice cover and EMC sea ice concentration data
+  to create a global sea ice analysis used to update the GFS once per
+  day.
 
-- emcsfc_snow2mdl - Blends National Ice Center snow cover and Air
-  Force snow depth data to create a global depth analysis used to
-  update the GFS snow field once per day.
+- <a href="emcsfc_snow2mdl/index.html">emcsfc_snow2mdl</a> - Blends
+  National Ice Center snow cover and Air Force snow depth data to
+  create a global depth analysis used to update the GFS snow field
+  once per day.
 
 - fre-nctools - Tools to remap data; and to create the geo-reference
   fields (latitude, longitude, etc.) for an FV3 grid.
 
-- fvcom_tools - - Replaces lake surface and lake ice temperature along
-  with aerial ice concentration generated from the Great Lakes
-  Operational Forecast System (GLOFS) in an FV3 surface restart
-  file. See [fvcom documentation](@ref fvcom_readme).
+- <a href="fvcom_tools/index.html">fvcom_tools</a> - Replaces lake
+  surface and lake ice temperature along with aerial ice concentration
+  generated from the Great Lakes Operational Forecast System (GLOFS)
+  in an FV3 surface restart file. See [fvcom documentation](@ref
+  fvcom_readme).
 
-- global_cycle - Updates the GFS surface conditions using external
-  snow and sea ice analyses. Updates monthly climatological fields
-  such as plant greenness fraction and albedo. Runs as part of the GFS
-  and GDAS cycles.
-
-- grid_tools - Utilities to filter topography, to create regional
-  extended Schmidt gnomonic grids, and to compute the equivalent
-  global resolution of a regional grid.
-
-- orog_mask_tools - Utilities to create land mask, terrain and gravity
-  wave drag fields; set lake fraction and depth; creates an inland
-  land mask.
-
-- sfc_climo_gen - Creates surface climatological fields, such as
-  vegetation type and albedo, for an FV3 grid.
-
-- vcoord_gen - Generates hybrid coordinate parameters from fields such
-  as surface pressure, model top and the number of vertical
-  levels. Outputs the 'ak' and 'bk' parameters used by the forecast
-  model to define the hybrid levels.
+- <a href="global_cycle/index.html">global_cycle</a> -
+  Updates the GFS surface conditions using external snow and sea ice
+  analyses. Updates monthly climatological fields such as plant
+  greenness fraction and albedo. Runs as part of the GFS and GDAS
+  cycles.
+
+- <a href="grid_tools/index.html">grid_tools</a> -
+  Utilities to filter topography, to create regional extended Schmidt
+  gnomonic grids, and to compute the equivalent global resolution of a
+  regional grid.
+
+- <a href="orog_mask_tools/index.html">orog_mask_tools</a> - Utilities
+  to create land mask, terrain and gravity wave drag fields; set lake
+  fraction and depth; creates an inland land mask.
+
+- <a href="sfc_climo_gen/index.html">sfc_climo_gen</a> - Creates
+  surface climatological fields, such as vegetation type and albedo,
+  for an FV3 grid.
+
+- <a href="vcoord_gen/index.html">vcoord_gen</a> - Generates hybrid
+  coordinate parameters from fields such as surface pressure, model
+  top and the number of vertical levels. Outputs the 'ak' and 'bk'
+  parameters used by the forecast model to define the hybrid levels.
 
 

sorc/chgres_cube.fd/docs/CMakeLists.txt

@@ -12,4 +12,7 @@ add_custom_target(chgres_cube_doc ALL
   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
   COMMENT "Generating API Documentation with Doxygen" VERBATIM)
 
+# Ensure top-level docs have been generated.
+add_dependencies(chgres_cube_doc doc)
+
 

sorc/chgres_cube.fd/docs/Doxyfile.in

@@ -881,7 +881,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = 
+USE_MDFILE_AS_MAINPAGE = user_guide.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

sorc/chgres_cube.fd/docs/user_guide.md

@@ -1,4 +1,3 @@
-@mainpage
 
 # chgres_cube
 

sorc/emcsfc_ice_blend.fd/CMakeLists.txt

@@ -1,3 +1,8 @@
+# This is the CMake build file for the emcsfc_ice_blend utility in the
+# UFS_UTILS package.
+#
+# George Gayno, Mark Potts
+
 set(fortran_src
     emcsfc_ice_blend.f90)
 
@@ -10,3 +15,8 @@ target_link_libraries(
   w3nco::w3nco_4)
 
 install(TARGETS ${exe_name} RUNTIME DESTINATION ${exec_dir})
+
+# If doxygen documentation we enabled, build it.
+if(ENABLE_DOCS)
+  add_subdirectory(docs)  
+endif()

sorc/emcsfc_ice_blend.fd/docs/CMakeLists.txt

@@ -0,0 +1,18 @@
+# This is the CMake file for building the docs directory of UFS_UTILS
+# utility emcsfc_ice_blend.
+#
+# Ed Hartnett 3/9/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(emcsfc_ice_blend_doc ALL
+  ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+  COMMENT "Generating API Documentation with Doxygen" VERBATIM)
+
+# Ensure top-level docs have been generated.
+add_dependencies(emcsfc_ice_blend_doc doc)
+
+