docs: documentation updates (NOAA-GFDL#935)

Reorganizes the doxygen site and adds missing pages for certain routines/files

Author: rem1776

.github/workflows/update_docs.yml

@@ -12,14 +12,14 @@ jobs:
       - name: Setup repo
         run: | # do autotool's job for substitutes since we don't need a full build environement
           mkdir gen_docs
-          sed 's/@abs_top_builddir@\/docs/gen_docs/' docs/Doxyfile.in > gen_docs/Doxyfile
-          sed -i 's/@abs_top_srcdir@/./' gen_docs/Doxyfile
+          sed 's/@abs_top_builddir@\/docs/gen_docs/g' docs/Doxyfile.in > gen_docs/Doxyfile
+          sed -i 's/@abs_top_srcdir@/./g' gen_docs/Doxyfile
           # grab version number from configure.ac
           export VER="`awk '/AC_INIT/{getline;print}' configure.ac | cut -d "[" -f2 | cut -d "]" -f1`"
-          sed -i "s/@PACKAGE_VERSION@/$VER/" gen_docs/Doxyfile
+          sed -i "s/@PACKAGE_VERSION@/$VER/g" gen_docs/Doxyfile
       - name: Install and run doxygen
         run: |
-          sudo apt -y install doxygen
+          sudo apt -y install doxygen graphviz
           doxygen gen_docs/Doxyfile
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3

affinity/affinity.c

@@ -40,12 +40,8 @@
 // skips doc parsing for includes and license
 
 /**
- * \file
- * \brief Routines to set and get thread CPU affinity
- * Get, set, and helper functions for thread CPU affinity to be interfaced
- * in fortran via fms_affinity_mod
- * \author @bensonr
- * \ingroup affinity
+ * \addtogroup affinity
+ * \@{
  */
 
 /**
@@ -146,3 +142,4 @@ int set_cpu_affinity(int cpu)
 #endif
   return 0;
 }
+///@}

affinity/fms_affinity.F90

@@ -20,14 +20,11 @@
 !> @defgroup fms_affinity_mod fms_affinity_mod
 !> @ingroup affinity
 !> @brief Fortran API interfaces to set the thread affinity.
-!! API interfaces to allow setting and getting thread affinity.  The thread affinity get and set
-!! are managed in the C routines in affinity.c.
+!! API interfaces to allow setting and getting thread affinity.  The routines @ref get_cpuset
+!! , @ref set_cpu_affinity , and @ref fms_affinity_get are defined via C routines in affinity.c.
 !!
 !! @author Rusty Benson
 
-!> @file
-!> File for @ref fms_affinity_mod
-
 !> @addtogroup fms_affinity_mod
 !> @{
 module fms_affinity_mod
@@ -49,7 +46,6 @@ module fms_affinity_mod
     !> Interface to get affinity from the current component.
     !!
     !> Defined in @ref affinity.c.
-    !> @ingroup fms_affinity_mod
     integer(KIND=c_int) function fms_affinity_get() bind(c, name="get_cpu_affinity")
       import c_int
     end function fms_affinity_get

amip_interp/amip_interp.F90

@@ -26,10 +26,9 @@
 !!
 !> When using these routines three possible data sets are available:
 !!
-!! 1. AMIP @link http://www-pcmdi.llnl.gov/amip @endlink from Jan 1979 to Jan 1989 (2 deg x 2 deg)
-!! 2. Reynolds OI @link amip_interp.rey_oi.txt @endlink from Nov 1981 to Jan 1999 (1 deg x 1 deg)
-!! 3. Reynolds EOF @link ftp://podaac.jpl.nasa.gov/pub/sea_surface_temperature/reynolds/rsst/doc/rsst.html
-!! @endlink from Jan 1950 to Dec 1998 (2 deg x 2 deg)
+!! 1. AMIP http://www.pcmdi.github.io/mips/amip from Jan 1979 to Jan 1989 (2 deg x 2 deg)
+!! 2. Reynolds OI @ref amip_interp.rey_oi.txt from Nov 1981 to Jan 1999 (1 deg x 1 deg)
+!! 3. Reynolds EOF podaac.jpl.nasa.gov/ from Jan 1950 to Dec 1998 (2 deg x 2 deg)
 !!
 !! All original data are observed monthly means. This module
 !! interpolates linearly in time between pairs of monthly means.
@@ -62,10 +61,55 @@
 !!         amip1           INPUT/amip1_sst.data
 !!         reynolds_io     INPUT/reyoi_sst.data
 !!         reynolds_eof    INPUT/reynolds_sst.data
-
-
-!> @file
-!> File for amip_interp_mod
+!!
+!> @var character(len=24) data_set
+!! Name/type of SST data that will be used.
+!!        Possible values (case-insensitive) are:
+!!                          1) amip1
+!!                          2) reynolds_eof
+!!                          3) reynolds_oi
+!!        See the @ref amip_interp_oi page for more information
+!! @var character(len=16) date_out_of_range
+!!     Controls the use of climatological monthly mean data when
+!!     the requested date falls outside the range of the data set.<BR/>
+!!     Possible values are:
+!!     <PRE>
+!!   fail      - program will fail if requested date is prior
+!!               to or after the data set period.
+!!   initclimo - program uses climatological requested data is
+!!               prior to data set period and will fail if
+!!               requested date is after data set period.
+!!   climo     - program uses climatological data anytime.
+!!    </PRE>
+!! @var real tice_crit
+!!     Freezing point of sea water in degC or degK. Defaults to -1.80
+!! @var integer verbose
+!!     Controls printed output, 0 <= verbose <= 3, default=0
+!!     additional parameters for controlling zonal prescribed sst ----
+!!     these parameters only have an effect when use_zonal=.true. ----
+!! @var logical use_zonal
+!!     Flag to selected zonal sst or data set. Default=.false.
+!! @var real teq
+!!     sst at the equator. Default=305
+!! @var real tdif
+!!     Equator to pole sst difference. Default=50
+!! @var real tann
+!!     Amplitude of annual cycle. Default=20
+!! @var real tlag
+!!     Offset for time of year (for annual cycle). Default=0.875
+!! @var integer amip_date
+!!     Single calendar date in integer "(year,month,day)" format
+!!     that is used only if set with year>0, month>0, day>0.
+!!     If used, model calendar date is replaced by this date,
+!!     but model time of day is still used to determine ice/sst.
+!!     Used for repeating-single-day (rsd) experiments.
+!!     Default=/-1,-1,-1/
+!! @var real sst_pert
+!!     Temperature perturbation in degrees Kelvin added onto the SST.
+!!                The perturbation is globally-uniform (even near sea-ice).
+!!                It is only used when abs(sst_pert) > 1.e-4.  SST perturbation runs
+!!                may be useful in accessing model sensitivities.
+!!     Default=0.
 
 !> @addtogroup amip_interp_mod
 !> @{
@@ -299,56 +343,6 @@ module amip_interp_mod
  logical :: interp_oi_sst = .false. !< changed to false for regular runs
  logical :: use_mpp_io = .false. !< Set to .true. to use mpp_io, otherwise fms2io is used
 
-!> @page amip_interp_nml @ref amip_interp_mod Namelist
-!!
-!> @var character(len=24) data_set
-!! Name/type of SST data that will be used.
-!!        Possible values (case-insensitive) are:
-!!                          1) amip1
-!!                          2) reynolds_eof
-!!                          3) reynolds_oi
-!!        See the @ref amip_interp_oi page for more information
-!! @var character(len=16) date_out_of_range
-!!     Controls the use of climatological monthly mean data when
-!!     the requested date falls outside the range of the data set.<BR/>
-!!     Possible values are:
-!!     <PRE>
-!!   fail      - program will fail if requested date is prior
-!!               to or after the data set period.
-!!   initclimo - program uses climatological requested data is
-!!               prior to data set period and will fail if
-!!               requested date is after data set period.
-!!   climo     - program uses climatological data anytime.
-!!    </PRE>
-!! @var real tice_crit
-!!     Freezing point of sea water in degC or degK. Defaults to -1.80
-!! @var integer verbose
-!!     Controls printed output, 0 <= verbose <= 3, default=0
-!!     additional parameters for controlling zonal prescribed sst ----
-!!     these parameters only have an effect when use_zonal=.true. ----
-!! @var logical use_zonal
-!!     Flag to selected zonal sst or data set. Default=.false.
-!! @var real teq
-!!     sst at the equator. Default=305
-!! @var real tdif
-!!     Equator to pole sst difference. Default=50
-!! @var real tann
-!!     Amplitude of annual cycle. Default=20
-!! @var real tlag
-!!     Offset for time of year (for annual cycle). Default=0.875
-!! @var integer amip_date
-!!     Single calendar date in integer "(year,month,day)" format
-!!     that is used only if set with year>0, month>0, day>0.
-!!     If used, model calendar date is replaced by this date,
-!!     but model time of day is still used to determine ice/sst.
-!!     Used for repeating-single-day (rsd) experiments.
-!!     Default=/-1,-1,-1/
-!! @var real sst_pert
-!!     Temperature perturbation in degrees Kelvin added onto the SST.
-!!                The perturbation is globally-uniform (even near sea-ice).
-!!                It is only used when abs(sst_pert) > 1.e-4.  SST perturbation runs
-!!                may be useful in accessing model sensitivities.
-!!     Default=0.
  namelist /amip_interp_nml/ use_ncep_sst, no_anom_sst, use_ncep_ice,  tice_crit, &
                             interp_oi_sst, data_set, date_out_of_range,          &
                             use_zonal, teq, tdif, tann, tlag, amip_date,         &

amip_interp/amip_interp.rey_oi.txt amip_interp/amip_interp.rey_oi.md

@@ -1,9 +1,8 @@
-\file
-\ingroup amip_interp
+@ingroup amip_interp
 
-(This file was edited for the Flexible Modeling System on July 26, 1999)
+## Information for the use of the monthly NMC SST analyzed fields
 
-Information for the use of the monthly NMC SST analyzed fields
+(This file was edited for the Flexible Modeling System on July 26, 1999)
 
 The monthly optimum interpolation (OI) fields are derived by a linear
 interpolation of the weekly OI fields to daily fields then averaging

astronomy/astronomy.F90

@@ -24,10 +24,6 @@
 !!        radiation packages.
 !> @author Fei Liu
 
-
-!> @file
-!> @brief File for @ref astronomy_mod
-
 !> @addtogroup astronomy_mod
 !> @{
 module astronomy_mod

axis_utils/axis_utils.F90

@@ -19,11 +19,11 @@
 !> @defgroup axis_utils_mod axis_utils_mod
 !> @ingroup axis_utils
 !> @brief A set of utilities for manipulating axes and extracting axis attributes,
+!! A more recent version of this module using the updated fms2_io is available, @ref axis_utils2
+!! but this module should be used if still using @ref mpp_io
+!!
 !> @author M.J. Harrison
 
-!> @file
-!> @brief File for @ref axis_utils_mod
-
 !> @addtogroup axis_utils_mod
 !> @{
 module axis_utils_mod

axis_utils/axis_utils2.F90

@@ -19,13 +19,9 @@
 !> @defgroup axis_utils2_mod axis_utils2_mod
 !> @ingroup axis_utils
 !> @brief A set of utilities for manipulating axes and extracting axis attributes.
-!!
-!> FMS2_IO equivalent version of @ref axis_utils_mod.
+!! FMS2_IO equivalent version of @ref axis_utils_mod.
 !> @author M.J. Harrison
 
-!> @file
-!> @brief File for @ref axis_utils2_mod
-
 !> @addtogroup axis_utils2_mod
 !> @{
 module axis_utils2_mod

block_control/block_control.F90

@@ -21,9 +21,6 @@
 !> @brief Routines for "blocks" used for  OpenMP threading of column-based
 !!        calculations
 
-!> @file
-!> @brief File for @ref block_control_mod
-
 module block_control_mod
 
 use mpp_mod,         only: mpp_error, NOTE, WARNING, FATAL

column_diagnostics/column_diagnostics.F90

@@ -20,9 +20,6 @@
 !> @ingroup column_diagnostics
 !! @brief Module to locate and mark desired diagnostic columns
 
-!> @file
-!> @brief File for @ref column_diagnostics_mod
-
 !> @addtogroup column_diagnostics_mod
 !> @{
 module column_diagnostics_mod

constants/constants.F90

@@ -16,13 +16,35 @@
 !* You should have received a copy of the GNU Lesser General Public
 !* License along with FMS.  If not, see <http://www.gnu.org/licenses/>.
 !***********************************************************************
+!> @file
+!> @brief File for @ref constants_mod
+
 !> @defgroup constants_mod constants_mod
 !> @ingroup constants
 !> @brief compatibility module as we transition to an FMSConstants module
 !!
-!> @file
-!> @brief File for @ref constants_mod
+!>    Constants have been declared as type REAL, PARAMETER.
+!!
+!!    The value a constant can not be changed in a users program.
+!!    New constants can be defined in terms of values from the
+!!    constants module using a parameter statement.<br><br>
+!!
+!!    The name given to a particular constant may be changed.<br><br>
+!!
+!!    Constants can be used on the right side on an assignment statement
+!!    (their value can not be reassigned).
+!!
+!!    Example:
+!!
+!! @verbatim
+!!    use constants_mod, only:  TFREEZE, grav_new => GRAV
+!!    real, parameter :: grav_inv = 1.0 / grav_new
+!!    tempc(:,:,:) = tempk(:,:,:) - TFREEZE
+!!    geopotential(:,:) = height(:,:) * grav_new
+!! @endverbatim
 
+!> @addtogroup constants_mod
+!> @{
 module constants_mod
 
 !> rename to not conflict with any other version vars

coupler/atmos_ocean_fluxes.F90

@@ -37,9 +37,6 @@
 !!
 !! http://ocmip5.ipsl.fr/documentation/OCMIP/phase2/simulations/Biotic/HOWTO-Biotic.html
 
-!> @file
-!> @brief File for @ref atmos_ocean_fluxes_mod
-
 !> @addtogroup atmos_ocean_fluxes_mod
 !> @{
 module  atmos_ocean_fluxes_mod

coupler/coupler_types.F90

@@ -21,9 +21,6 @@
 !> @brief This module contains type declarations for the coupler.
 !> @author Richard Slater, John Dunne
 
-!> @file
-!> @brief File for @ref coupler_types_mod
-
 !> @addtogroup coupler_types_mod
 !> @{
 module coupler_types_mod

coupler/ensemble_manager.F90

@@ -20,9 +20,6 @@
 !> @ingroup coupler
 !> @brief Routines for setting up and managing ensembles and ensemble pe lists.
 
-!> @file
-!> @brief File for @ref ensemble_manager_mod
-
 !> @addtogroup ensemble_manager_mod
 !> @{
 module ensemble_manager_mod

data_override/data_override.F90

@@ -36,9 +36,6 @@
 !! A field can be overriden globally (by default) or users can specify one or two regions in which
 !! data_override will take place, field values outside the region will not be affected.
 
-!> @file
-!> @brief File for @ref data_override_mod
-
 module data_override_mod
 use yaml_parser_mod
 use constants_mod, only: PI

data_override/get_grid_version.F90

@@ -16,12 +16,9 @@
 !* You should have received a copy of the GNU Lesser General Public
 !* License along with FMS.  If not, see <http://www.gnu.org/licenses/>.
 !***********************************************************************
-!> @defgroup get_grid_version_fms2_io_mod get_grid_version_fms2_io_mod
+!> @defgroup get_grid_version_mod get_grid_version_mod
 !> @ingroup data_override
-!> @brief fms2_io implementations of grid routines for @ref data_override_mod
-
-!> @file
-!> @brief File for @ref get_grid_version_mod
+!> @brief get_grid implementations and helper routines for @ref data_override_mod
 
 !> @addtogroup get_grid_version_mod
 !> @{