From 2dddfc8144543cbb04f1ed3a5b254a1f03b089e3 Mon Sep 17 00:00:00 2001 From: Alistair Adcroft Date: Wed, 12 Jul 2017 20:21:54 -0600 Subject: [PATCH 1/6] Try to reduce RTD memory usage --- docs/Doxyfile_rtd | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/Doxyfile_rtd b/docs/Doxyfile_rtd index 523510b678..6d27049173 100644 --- a/docs/Doxyfile_rtd +++ b/docs/Doxyfile_rtd @@ -2130,7 +2130,7 @@ PERL_PATH = /usr/bin/perl # powerful graphs. # The default value is: YES. -CLASS_DIAGRAMS = YES +CLASS_DIAGRAMS = NO # You can define message sequence charts within doxygen comments using the \msc # command. Doxygen will then run the mscgen tool (see: @@ -2203,7 +2203,7 @@ DOT_FONTPATH = # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -CLASS_GRAPH = YES +CLASS_GRAPH = NO # If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a # graph for each documented class showing the direct and indirect implementation @@ -2212,14 +2212,14 @@ CLASS_GRAPH = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -COLLABORATION_GRAPH = YES +COLLABORATION_GRAPH = NO # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for # groups, showing the direct groups dependencies. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -GROUP_GRAPHS = YES +GROUP_GRAPHS = NO # If the UML_LOOK tag is set to YES, doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling @@ -2257,7 +2257,7 @@ TEMPLATE_RELATIONS = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -INCLUDE_GRAPH = YES +INCLUDE_GRAPH = NO # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are # set to YES then doxygen will generate a graph for each documented file showing @@ -2266,7 +2266,7 @@ INCLUDE_GRAPH = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -INCLUDED_BY_GRAPH = YES +INCLUDED_BY_GRAPH = NO # If the CALL_GRAPH tag is set to YES then doxygen will generate a call # dependency graph for every global function or class method. @@ -2297,7 +2297,7 @@ CALLER_GRAPH = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -GRAPHICAL_HIERARCHY = YES +GRAPHICAL_HIERARCHY = NO # If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the # dependencies a directory has on other directories in a graphical way. The @@ -2306,7 +2306,7 @@ GRAPHICAL_HIERARCHY = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -DIRECTORY_GRAPH = YES +DIRECTORY_GRAPH = NO # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. For an explanation of the image formats see the section @@ -2383,7 +2383,7 @@ PLANTUML_INCLUDE_PATH = # Minimum value: 0, maximum value: 10000, default value: 50. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_GRAPH_MAX_NODES = 10000 +DOT_GRAPH_MAX_NODES = 100 # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs # generated by dot. A depth value of 3 means that only nodes reachable from the @@ -2395,7 +2395,7 @@ DOT_GRAPH_MAX_NODES = 10000 # Minimum value: 0, maximum value: 1000, default value: 0. # This tag requires that the tag HAVE_DOT is set to YES. -MAX_DOT_GRAPH_DEPTH = 0 +MAX_DOT_GRAPH_DEPTH = 4 # Set the DOT_TRANSPARENT tag to YES to generate images with a transparent # background. This is disabled by default, because dot on Windows does not seem @@ -2431,4 +2431,4 @@ GENERATE_LEGEND = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_CLEANUP = YES +DOT_CLEANUP = NO From 122e550a14e447ef9781e61a9f14e938e7ab51a5 Mon Sep 17 00:00:00 2001 From: Alistair Adcroft Date: Wed, 12 Jul 2017 21:07:38 -0600 Subject: [PATCH 2/6] Turned off gen-HTML and listings --- docs/Doxyfile_rtd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Doxyfile_rtd b/docs/Doxyfile_rtd index 6d27049173..09e56b12e4 100644 --- a/docs/Doxyfile_rtd +++ b/docs/Doxyfile_rtd @@ -1069,7 +1069,7 @@ IGNORE_PREFIX = # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. -GENERATE_HTML = YES +GENERATE_HTML = NO # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1910,7 +1910,7 @@ XML_OUTPUT = xml # The default value is: YES. # This tag requires that the tag GENERATE_XML is set to YES. -XML_PROGRAMLISTING = YES +XML_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # Configuration options related to the DOCBOOK output From 2e79064396947c14ecad932fee40dbdf1865b2ac Mon Sep 17 00:00:00 2001 From: Alistair Adcroft Date: Wed, 12 Jul 2017 21:17:43 -0600 Subject: [PATCH 3/6] Return to orig w/o HTML --- docs/Doxyfile_rtd | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/Doxyfile_rtd b/docs/Doxyfile_rtd index 09e56b12e4..253d213693 100644 --- a/docs/Doxyfile_rtd +++ b/docs/Doxyfile_rtd @@ -1910,7 +1910,7 @@ XML_OUTPUT = xml # The default value is: YES. # This tag requires that the tag GENERATE_XML is set to YES. -XML_PROGRAMLISTING = NO +XML_PROGRAMLISTING = YES #--------------------------------------------------------------------------- # Configuration options related to the DOCBOOK output @@ -2130,7 +2130,7 @@ PERL_PATH = /usr/bin/perl # powerful graphs. # The default value is: YES. -CLASS_DIAGRAMS = NO +CLASS_DIAGRAMS = YES # You can define message sequence charts within doxygen comments using the \msc # command. Doxygen will then run the mscgen tool (see: @@ -2203,7 +2203,7 @@ DOT_FONTPATH = # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -CLASS_GRAPH = NO +CLASS_GRAPH = YES # If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a # graph for each documented class showing the direct and indirect implementation @@ -2212,14 +2212,14 @@ CLASS_GRAPH = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -COLLABORATION_GRAPH = NO +COLLABORATION_GRAPH = YES # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for # groups, showing the direct groups dependencies. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -GROUP_GRAPHS = NO +GROUP_GRAPHS = YES # If the UML_LOOK tag is set to YES, doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling @@ -2257,7 +2257,7 @@ TEMPLATE_RELATIONS = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -INCLUDE_GRAPH = NO +INCLUDE_GRAPH = YES # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are # set to YES then doxygen will generate a graph for each documented file showing @@ -2266,7 +2266,7 @@ INCLUDE_GRAPH = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -INCLUDED_BY_GRAPH = NO +INCLUDED_BY_GRAPH = YES # If the CALL_GRAPH tag is set to YES then doxygen will generate a call # dependency graph for every global function or class method. @@ -2297,7 +2297,7 @@ CALLER_GRAPH = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -GRAPHICAL_HIERARCHY = NO +GRAPHICAL_HIERARCHY = YES # If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the # dependencies a directory has on other directories in a graphical way. The @@ -2306,7 +2306,7 @@ GRAPHICAL_HIERARCHY = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -DIRECTORY_GRAPH = NO +DIRECTORY_GRAPH = YES # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. For an explanation of the image formats see the section @@ -2383,7 +2383,7 @@ PLANTUML_INCLUDE_PATH = # Minimum value: 0, maximum value: 10000, default value: 50. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_GRAPH_MAX_NODES = 100 +DOT_GRAPH_MAX_NODES = 10000 # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs # generated by dot. A depth value of 3 means that only nodes reachable from the @@ -2395,7 +2395,7 @@ DOT_GRAPH_MAX_NODES = 100 # Minimum value: 0, maximum value: 1000, default value: 0. # This tag requires that the tag HAVE_DOT is set to YES. -MAX_DOT_GRAPH_DEPTH = 4 +MAX_DOT_GRAPH_DEPTH = 0 # Set the DOT_TRANSPARENT tag to YES to generate images with a transparent # background. This is disabled by default, because dot on Windows does not seem @@ -2431,4 +2431,4 @@ GENERATE_LEGEND = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_CLEANUP = NO +DOT_CLEANUP = YES From 375a8e55757c68dc0e5e65ec6f2302f1a7beeccb Mon Sep 17 00:00:00 2001 From: Alistair Adcroft Date: Wed, 12 Jul 2017 21:27:40 -0600 Subject: [PATCH 4/6] Removed program listing --- docs/Doxyfile_rtd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Doxyfile_rtd b/docs/Doxyfile_rtd index 253d213693..3e94ed0eb3 100644 --- a/docs/Doxyfile_rtd +++ b/docs/Doxyfile_rtd @@ -1910,7 +1910,7 @@ XML_OUTPUT = xml # The default value is: YES. # This tag requires that the tag GENERATE_XML is set to YES. -XML_PROGRAMLISTING = YES +XML_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # Configuration options related to the DOCBOOK output From c4b50435891bb561cdf32bab780de48036c3592e Mon Sep 17 00:00:00 2001 From: Alistair Adcroft Date: Tue, 18 Jul 2017 23:40:39 -0600 Subject: [PATCH 5/6] Fixes to avoid errors when running doxygen on source - This removes all errors and warnings that appear in doxygen.log except for warnings about undocumented variables. - Removed repeated re-use of the same label "section_gridlayout". - Fixed conflict between sphinx and doxygen for references. Trailing underscore is a reference in sphinx. - Corrected indentation of bullets in MOM_ice_shelf.F90. sphinx complained! - Documented CPP macros in MOM_memory.h and MOM_memory_macros.h. - Added section in MOM_thickness_diffuse.F90 to fix sub-section error. - Removed string "Adcroft's" from MOM_kappa_shear.F90 which for some reason was causing the preprocessor in doxygen to miscount #ifdef's!!! - Added some todo's for missing references. - Fixed numerous spelling errors. - Revised Doxyfile configurations for both pure doxygen (github.io) and readthdocs. - Removed api/todo.rst since it wasn't being used. - Removed tutorial.rst since the MOM6-examples wiki now has a list. - Added front_page.md for github.io. - Removed unused .html files from config_src/*. --- .../coupled_driver/ocean_model_MOM.html | 205 ------------------ config_src/dynamic_symmetric/MOM_memory.h | 47 ++-- config_src/solo_driver/coupler_types.html | 115 ---------- docs/Doxyfile_nortd | 31 +-- docs/Doxyfile_rtd | 24 +- docs/api/todo.rst | 12 - docs/apiref.rst | 4 + docs/front_page.md | 22 ++ docs/index.rst | 1 - docs/tutorials.rst | 9 - src/core/MOM.F90 | 31 --- src/core/MOM_dynamics_split_RK2.F90 | 32 --- src/core/MOM_grid.F90 | 4 +- src/framework/MOM_memory_macros.h | 63 ++++-- src/framework/_Diagnostics.dox | 4 +- src/framework/_Horizontal_indexing.dox | 2 + src/framework/_Runtime_parameter_system.dox | 8 +- src/ice_shelf/MOM_ice_shelf.F90 | 2 +- .../lateral/MOM_mixed_layer_restrat.F90 | 2 +- .../lateral/MOM_thickness_diffuse.F90 | 2 + .../vertical/MOM_diabatic_driver.F90 | 31 --- .../vertical/MOM_kappa_shear.F90 | 2 +- .../vertical/MOM_set_diffusivity.F90 | 4 +- src/tracer/MOM_tracer_advect.F90 | 30 --- src/tracer/MOM_tracer_hor_diff.F90 | 30 --- src/tracer/boundary_impulse_tracer.F90 | 2 +- src/user/SCM_CVmix_tests.F90 | 2 +- 27 files changed, 143 insertions(+), 578 deletions(-) delete mode 100644 config_src/coupled_driver/ocean_model_MOM.html delete mode 100644 config_src/solo_driver/coupler_types.html delete mode 100644 docs/api/todo.rst create mode 100644 docs/front_page.md delete mode 100644 docs/tutorials.rst diff --git a/config_src/coupled_driver/ocean_model_MOM.html b/config_src/coupled_driver/ocean_model_MOM.html deleted file mode 100644 index a4a009ce50..0000000000 --- a/config_src/coupled_driver/ocean_model_MOM.html +++ /dev/null @@ -1,205 +0,0 @@ - - - -Module ocean_model_mod - - - - -PUBLIC INTERFACE ~ - PUBLIC DATA ~ - PUBLIC ROUTINES ~ - NAMELIST ~ - DIAGNOSTIC FIELDS ~ - ERROR MESSAGES ~ - REFERENCES ~ - NOTES -
-

Module ocean_model_mod

- - -
-Contact:  Robert Hallberg -
-Reviewers:  -
-Change History: WebCVS Log -
-
-
- - -
-

OVERVIEW

- -

This code is a stop-gap wrapper of the MOM code to enable it to be called - in the same way as MOM4.

- - - -
-
- - -
-

OTHER MODULES USED

- -
-
      MOM_constants
  MOM_diag_mediator
        MOM_domains
  MOM_error_handler
             MOM_io
                MOM
    MOM_file_parser
        MOM_restart
     MOM_sum_output
MOM_surface_forcing
   MOM_time_manager
      MOM_variables
  coupler_types_mod
            fms_mod
    mpp_domains_mod
-
- - - -
-

PUBLIC INTERFACE

- -
- - -
-

PUBLIC DATA

- -
None.
-
-
- - -
-

PUBLIC ROUTINES

- -
    -
  1. - -

    ocean_model_init

    -
    -
    -DESCRIPTION -
    -
    Initialize the ocean model.
    -
    -
    -
    -
    2. -
  2. - -

    update_ocean_model

    -
    -
    -DESCRIPTION -
    -
    Update in time the ocean model fields. This code wraps the call to step_MOM - with MOM4's call.
    -
    -
    -
    -
    3. -
  3. - -

    ocean_model_end

    -
    -
    -DESCRIPTION -
    -
    Close down the ocean model
    -
    -
    -
    -
    4. -
  4. - -

    write_ice_ocean_boundary

    -
    -
    -DESCRIPTION -
    -
    Write the surface boundary conditions for use in coupled modeling.
    -
    -
    -
    -
    5. -
  5. - -

    read_ice_ocean_boundary

    -
    -
    -DESCRIPTION -
    -
    Read the surface boundary conditions for use in coupled modeling.
    -
    -
    -
    -
    6. -
  6. - -

    init_default_ice_ocean_boundary

    -
    -
    -DESCRIPTION -
    -
    Default surface boundary conditions for use in coupled modeling.
    -
    -
    -
    -
    7. -
- - - - - - - - - -
-

DATA SETS

-
None.
-
-
- - - - - -
-

ERROR MESSAGES

-
None.
-
-
- -
-
-top -
- - diff --git a/config_src/dynamic_symmetric/MOM_memory.h b/config_src/dynamic_symmetric/MOM_memory.h index 76061c3259..125dcf212f 100644 --- a/config_src/dynamic_symmetric/MOM_memory.h +++ b/config_src/dynamic_symmetric/MOM_memory.h @@ -1,48 +1,33 @@ -!********+*********+*********+*********+*********+*********+*********+* -!* This include file determines the compile-time memory settings * -!* for the Modular Ocean Model (MOM), versions 6 and later. * -!********+*********+*********+*********+*********+*********+*********+* +!/*! \brief Compile-time memory settings */ +!/*! \details This include file determines the compile-time memory settings. There are several variants of this file and only one should be in the search path for compilation. */ +!/*! \file MOM_memory.h */ -! Specify the numerical domain. +!/*! The number of thickness grid points in the i-direction of the global domain. */ #define NIGLOBAL_ NONSENSE_NIGLOBAL +!/*! The number of thickness grid points in the j-direction of the global domain. */ #define NJGLOBAL_ NONSENSE_NJGLOBAL - ! NIGLOBAL_ and NJGLOBAL_ are the number of thickness - ! grid points in the zonal and meridional - ! directions of the physical domain. +!/*! The number of layers in the vertical direction. */ #define NK_ NONSENSE_NK - ! The number of layers. +!/*! \def STATIC_MEMORY_ If STATIC_MEMORY_ is defined, the principle variables will have sizes that are statically determined at compile time. Otherwise the sizes are not determined until run time. */ #undef STATIC_MEMORY_ - ! If STATIC_MEMORY_ is defined, the principle - ! variables will have sizes that are statically - ! determined at compile time. Otherwise the - ! sizes are not determined until run time. The - ! STATIC option is substantially faster, but - ! does not allow the PE count to be changed at - ! run time. + +!/*! If SYMMETRIC_MEMORY_ is defined, the velocity point data domain includes every face of the thickness points. In other words, some arrays are larger than others, depending on where they are on the staggered grid. */ #define SYMMETRIC_MEMORY_ - ! If defined, the velocity point data domain - ! includes every face of the thickness points. - ! In other words, some arrays are larger than - ! others, depending on where they are on the - ! staggered grid. +!/*! The number of processors in the i-direction. */ #define NIPROC_ NONSENSE_NIPROC - ! NIPROC_ is the number of processors in the - ! x-direction. + +!/*! The number of processors in the j-direction. */ #define NJPROC_ NONSENSE_NJPROC - ! NJPROC_ is the number of processors in the - ! y-direction. +!/*! The maximum permitted number (each) of restart variables, time derivatives, etc. This is mostly used for the size of pointer arrays, so it should be set generously. */ #define MAX_FIELDS_ 50 - ! The maximum permitted number (each) of - ! restart variables, time derivatives, etc. - ! This is mostly used for the size of pointer - ! arrays, so it should be set generously. +!/*! The number of memory halo cells on each side of the computational domain in the i-direction */ #define NIHALO_ 2 + +!/*! The number of memory halo cells on each side of the computational domain in the j-direction */ #define NJHALO_ 2 - ! NIHALO_ and NJHALO_ are the sizes of the - ! memory halos on each side. #include diff --git a/config_src/solo_driver/coupler_types.html b/config_src/solo_driver/coupler_types.html deleted file mode 100644 index 752425d682..0000000000 --- a/config_src/solo_driver/coupler_types.html +++ /dev/null @@ -1,115 +0,0 @@ - - - -Module coupler_types_mod - - - - -PUBLIC INTERFACE ~ - PUBLIC DATA ~ - PUBLIC ROUTINES ~ - NAMELIST ~ - DIAGNOSTIC FIELDS ~ - ERROR MESSAGES ~ - REFERENCES ~ - NOTES -
-

Module coupler_types_mod

- - -
-Contact:  Stephen Griffies -
-Reviewers:  -
-Change History: WebCVS Log -
-
-
- - -
-

OVERVIEW

- -

This module contains simplified type declarations for the coupler - of an ocean-only model. With mom4, this is used with ocean_solo_mod - as the driver, and with MOM it is used with MOM_driver.

- - - -
This module contains simplified type declarations for the coupler - of an ocean-only model. With mom4, this is used with ocean_solo_mod - as the driver, and with MOM it is used with MOM_driver.
-
- - -
-

OTHER MODULES USED

- -
-

-

-
-
-
-

-
PUBLIC INTERFACE

-

-

-

-

-
-
-

-
PUBLIC DATA

-
-
None.

-

-

-
-
-

-
PUBLIC ROUTINES

-
-
    
-
-
-
-
-
-
-
-
-
-
    
-
    DATA SETS
    
-
    None.
    
-
    
-
    
-
-
-
-
-
-
    
-
    ERROR MESSAGES
    
-
    None.
    
-
    
-
    
-
-
    
-
    
-top
-
    
-
-
diff --git a/docs/Doxyfile_nortd b/docs/Doxyfile_nortd
index a75384ebed..0d34cc4764 100644
--- a/docs/Doxyfile_nortd
+++ b/docs/Doxyfile_nortd
@@ -780,7 +780,12 @@ WARN_LOGFILE           = doxygen.log
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../config_src ../src ../README.md
+INPUT                  = ../src \
+                         front_page.md \
+                         ../config_src/solo_driver \
+                         ../config_src/dynamic_symmetric \
+                         ../config_src/coupled_driver/coupler_util.F90 \
+                         ../config_src/coupled_driver/ocean_model_MOM.F90
 
 # 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
@@ -839,7 +844,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = ../src/equation_of_state/TEOS10
 
 # 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
@@ -855,7 +860,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = makedep.py
+EXCLUDE_PATTERNS       = makedep.py Makefile INSTALL
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -872,7 +877,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = ../config_src ../src
+EXAMPLE_PATH           = ../src
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -892,7 +897,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = images ../config_src ../src
+IMAGE_PATH             = images ../src
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -948,7 +953,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 = ../README.md
+USE_MDFILE_AS_MAINPAGE = front_page.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
@@ -1052,7 +1057,7 @@ ALPHABETICAL_INDEX     = YES
 # Minimum value: 1, maximum value: 20, default value: 5.
 # This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
 
-COLS_IN_ALPHA_INDEX    = 5
+COLS_IN_ALPHA_INDEX    = 1
 
 # In case all classes in a project start with a common prefix, all classes will
 # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag
@@ -2014,7 +2019,7 @@ MACRO_EXPANSION        = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = YES
+EXPAND_ONLY_PREDEF     = NO
 
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2028,7 +2033,7 @@ SEARCH_INCLUDES        = YES
 # preprocessor.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           = ../src/framework
+INCLUDE_PATH           = ../src/framework ../config_src/dynamic_symmetric
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the
@@ -2036,7 +2041,7 @@ INCLUDE_PATH           = ../src/framework
 # used.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-INCLUDE_FILE_PATTERNS  =
+INCLUDE_FILE_PATTERNS  = *.h
 
 # The PREDEFINED tag can be used to specify one or more macro names that are
 # defined before the preprocessor is started (similar to the -D option of e.g.
@@ -2046,7 +2051,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = ALLOCABLE_=allocatable
+PREDEFINED             =
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
@@ -2065,7 +2070,7 @@ EXPAND_AS_DEFINED      =
 # The default value is: YES.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-SKIP_FUNCTION_MACROS   = YES
+SKIP_FUNCTION_MACROS   = NO
 
 #---------------------------------------------------------------------------
 # Configuration options related to external references
@@ -2431,4 +2436,4 @@ GENERATE_LEGEND        = YES
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_CLEANUP            = YES
+DOT_CLEANUP            = NO
diff --git a/docs/Doxyfile_rtd b/docs/Doxyfile_rtd
index 523510b678..dcaf701dde 100644
--- a/docs/Doxyfile_rtd
+++ b/docs/Doxyfile_rtd
@@ -780,7 +780,11 @@ WARN_LOGFILE           = doxygen.log
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../config_src ../src ../README.md
+INPUT                  = ../src \
+                         ../config_src/solo_driver \
+                         ../config_src/dynamic_symmetric \
+                         ../config_src/coupled_driver/coupler_util.F90 \
+                         ../config_src/coupled_driver/ocean_model_MOM.F90
 
 # 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
@@ -839,7 +843,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = ../src/equation_of_state/TEOS10
 
 # 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
@@ -872,7 +876,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = ../config_src ../src
+EXAMPLE_PATH           = ../src
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -892,7 +896,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = images ../config_src ../src
+IMAGE_PATH             = images ../src
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1069,7 +1073,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = YES
+GENERATE_HTML          = NO
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -2014,7 +2018,7 @@ MACRO_EXPANSION        = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = YES
+EXPAND_ONLY_PREDEF     = NO
 
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2028,7 +2032,7 @@ SEARCH_INCLUDES        = YES
 # preprocessor.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           = ../src/framework
+INCLUDE_PATH           = ../src/framework ../config_src/dynamic_symmetric
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the
@@ -2036,7 +2040,7 @@ INCLUDE_PATH           = ../src/framework
 # used.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-INCLUDE_FILE_PATTERNS  =
+INCLUDE_FILE_PATTERNS  = *.h
 
 # The PREDEFINED tag can be used to specify one or more macro names that are
 # defined before the preprocessor is started (similar to the -D option of e.g.
@@ -2046,7 +2050,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = ALLOCABLE_=allocatable
+PREDEFINED             =
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
@@ -2065,7 +2069,7 @@ EXPAND_AS_DEFINED      =
 # The default value is: YES.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-SKIP_FUNCTION_MACROS   = YES
+SKIP_FUNCTION_MACROS   = NO
 
 #---------------------------------------------------------------------------
 # Configuration options related to external references
diff --git a/docs/api/todo.rst b/docs/api/todo.rst
deleted file mode 100644
index 614ca70e76..0000000000
--- a/docs/api/todo.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. _Todo:
-
-Todo list
-=========
-
-.. raw:: html
-
-      
-      
-
-      
-      
diff --git a/docs/apiref.rst b/docs/apiref.rst
index 2b27921531..7f94e1c4b9 100644
--- a/docs/apiref.rst
+++ b/docs/apiref.rst
@@ -3,6 +3,10 @@
 API Reference
 =============
 
+This API reference is a partial image of the complete API documentation.
+The pages you find here are linkable - the url for the page is static.
+The complete API documentation is generated with doxygen and can be found at http://noaa-gfdl.github.io/MOM6/APIs/.
+
 .. toctree::
   :maxdepth: 1
 
diff --git a/docs/front_page.md b/docs/front_page.md
new file mode 100644
index 0000000000..4997244524
--- /dev/null
+++ b/docs/front_page.md
@@ -0,0 +1,22 @@
+# MOM6 APIs
+
+This is the generated documentation for the MOM6 source code which describes the APIs as well as some features of the code.
+
+This documentation is also available as web-linkable pages hosted on [read the docs](http://mom6.readthedocs.io/), where the pages are generated with sphinx.
+
+If you are looking for a user guide, start at the [MOM6-examples wiki](https://github.com/NOAA-GFDL/MOM6-examples/wiki) which has installation instructions, links to tutorials, and more.
+
+The APIs in MOM6 are documented using doxygen - you are viewing the result. A brief style guide for using doxygen in MOM6 is available at https://github.com/NOAA-GFDL/MOM6/wiki/Doxygen.
+
+***
+
+## Contents
+
+- [List of modules](namespaces.html)
+   - Alphabetical list of modules
+- [List of classes](annotated.html)
+   - Modules with types
+- [List of files](files.html)
+   - File structure
+- [List of feature pages](pages.html)
+   - Detailed description of some features of the code
diff --git a/docs/index.rst b/docs/index.rst
index a143c94d0a..61a11c2a91 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -15,7 +15,6 @@ Contents:
   equations/overview
   parameterizations
   working_with_MOM6
-  tutorials
   apiref
 
 
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
deleted file mode 100644
index ec12ebc9d3..0000000000
--- a/docs/tutorials.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-Tutorial
-========
-
-Tutorials and walk through will be hosted on the `MOM6-examples wiki `_.
-
-Jupyter notebooks
------------------
-
-Some examples contain jupyter notebooks to illustrate analysis of model output.
diff --git a/src/core/MOM.F90 b/src/core/MOM.F90
index 1b19d45ea7..f2286c3673 100644
--- a/src/core/MOM.F90
+++ b/src/core/MOM.F90
@@ -4093,37 +4093,6 @@ end subroutine MOM_end
 !!  * set_restart_fields is used to specify those fields that are
 !!    written to and read from the restart file.
 !!
-!!  Macros written all in capital letters are defined in MOM_memory.h.
-!!
-!!  \section section_gridlayout MOM grid layout
-!!
-!!  A small fragment of the grid is shown below:
-!!
-!! \verbatim
-!!    j+1  x ^ x ^ x
-!!
-!!    j+1  > o > o >
-!!
-!!    j    x ^ x ^ x
-!!
-!!    j    > o > o >
-!!
-!!    j-1  x ^ x ^ x
-!!
-!!        i-1  i  i+1
-!!
-!!           i  i+1
-!!
-!! \endverbatim
-!!
-!!  Fields at each point
-!!  * x =  q, CoriolisBu
-!!  * ^ =  v, PFv, CAv, vh, diffv, tauy, vbt, vhtr
-!!  * > =  u, PFu, CAu, uh, diffu, taux, ubt, uhtr
-!!  * o =  h, bathyT, eta, T, S, tr
-!!
-!!  The boundaries always run through q grid points (x).
-!!
 !!  \section section_heat_budget Diagnosing MOM heat budget
 !!
 !!  Here are some example heat budgets for the ALE version of MOM6.
diff --git a/src/core/MOM_dynamics_split_RK2.F90 b/src/core/MOM_dynamics_split_RK2.F90
index 4d86e7f639..512774522f 100644
--- a/src/core/MOM_dynamics_split_RK2.F90
+++ b/src/core/MOM_dynamics_split_RK2.F90
@@ -1202,37 +1202,5 @@ end subroutine end_dyn_split_RK2
 !!  does not have its own control structure, but shares the same
 !!  control structure with MOM.F90 and the other MOM_dynamics_...
 !!  modules.
-!!
-!!  Macros written all in capital letters are defined in MOM_memory.h.
-!!
-!!  \section section_gridlayout MOM grid layout
-!!
-!!  A small fragment of the grid is shown below:
-!!
-!! \verbatim
-!!    j+1  x ^ x ^ x
-!!
-!!    j+1  > o > o >
-!!
-!!    j    x ^ x ^ x
-!!
-!!    j    > o > o >
-!!
-!!    j-1  x ^ x ^ x
-!!
-!!        i-1  i  i+1
-!!
-!!           i  i+1
-!!
-!! \endverbatim
-!!
-!!  Fields at each point
-!!  * x =  q, CoriolisBu
-!!  * ^ =  v, PFv, CAv, vh, diffv, tauy, vbt, vhtr
-!!  * > =  u, PFu, CAu, uh, diffu, taux, ubt, uhtr
-!!  * o =  h, bathyT, eta, T, S, tr
-!!
-!!  The boundaries always run through q grid points (x).
-
 
 end module MOM_dynamics_split_RK2
diff --git a/src/core/MOM_grid.F90 b/src/core/MOM_grid.F90
index 6d5597ce4e..abb6329ef2 100644
--- a/src/core/MOM_grid.F90
+++ b/src/core/MOM_grid.F90
@@ -578,7 +578,7 @@ end subroutine MOM_grid_end
 !! u-, v- and q- point coordinates are follow same pattern of replacing T with Cu, Cv and Bu respectively.
 !!
 !! Each location also has a 2D mask indicating whether the entire column is land or ocean.
-!! `mask2dT` is 1. is the column is wet or 0. is the T-cell is land.
-!! `mask2dCu` is 1. if both neighboring column are ocean, and 0. if either is land.
+!! `mask2dT` is 1 if the column is wet or 0 if the T-cell is land.
+!! `mask2dCu` is 1 if both neighboring column are ocean, and 0 if either is land.
 
 end module MOM_grid
diff --git a/src/framework/MOM_memory_macros.h b/src/framework/MOM_memory_macros.h
index dcac15beed..7de33e4949 100644
--- a/src/framework/MOM_memory_macros.h
+++ b/src/framework/MOM_memory_macros.h
@@ -1,8 +1,10 @@
-!***********************************************************************
-! This is a header file to define macros for static and dynamic memory *
-! allocation.  Define STATIC_MEMORY_ in MOM_memory.h for static memory *
-! allocation.  Otherwise dynamic memory allocation will be assumed.    *
-!***********************************************************************
+!//! \brief Memory macros
+!//! \details This is a header file to define macros for static and dynamic memory allocation.
+!//! Define STATIC_MEMORY_ in MOM_memory.h for static memory allocation.
+!//! Otherwise dynamic memory allocation will be assumed.
+!//!
+!//! For explanation of symmetric and non-symmetric memory modes see \ref Horizontal_indexing.
+!//! \file MOM_memory_macros.h
 
 #ifdef STATIC_MEMORY_
 #  define DEALLOC_(x)
@@ -11,12 +13,12 @@
 #  define PTR_
 #  define TO_NULL_
 
-!   NIMEM and NJMEM are the maximum number of grid points in the
+! NIMEM and NJMEM are the maximum number of grid points in the
 ! x- and y-directions on each processsor.
 #  define NIMEM_ (((NIGLOBAL_-1)/NIPROC_)+1+2*NIHALO_)
 #  define NJMEM_ (((NJGLOBAL_-1)/NJPROC_)+1+2*NJHALO_)
 
-! These are the macors that should be used when setting up ALLOCABLE_ or
+! These are the macros that should be used when setting up ALLOCABLE_ or
 ! PTR_ (heap) variables.
 #  ifdef SYMMETRIC_MEMORY_
 #    define NIMEMB_   0:NIMEM_
@@ -47,50 +49,85 @@
 #  define SZJBS_(G)   0:NJMEM_
 
 #else
-! Dynamic memory allocation
+!/* Dynamic memory allocation section */
 
+!/*! Deallocates array x when using dynamic memory mode. Does nothing in static memory mode.*/
 #  define DEALLOC_(x) deallocate(x)
+!/*! Allocates array x when using dynamic memory mode. Does nothing in static memory mode.*/
 #  define ALLOC_(x)   allocate(x)
+!/*! Attaches the ALLOCATABLE attribute to an array in dynamic memory mode. Does nothing in static memory mode.*/
 #  define ALLOCABLE_ ,allocatable
+!/*! Attaches the POINTER attribute to an array in dynamic memory mode. Does nothing in static memory mode.*/
 #  define PTR_       ,pointer
+!/*! Nullify a pointer in dynamic memory mode. Does nothing in static memory mode.*/
 #  define TO_NULL_   =>NULL()
 
-! These are the macors that should be used when setting up ALLOCABLE_ or
-! PTR_ (heap) variables.
+!/* These are the macros that should be used when setting up ALLOCABLE_ or PTR_ (heap) variables. */
+
+!/*! Expands to : in dynamic memory mode, or is the i-shape of a tile in static memory mode. Use for heap (ALLOCABLE_ or PTR_) variables at h- or v- points. */
 #  define NIMEM_      :
+!/*! Expands to : in dynamic memory mode, or is the j-shape of a tile in static memory mode. Use for heap (ALLOCABLE_ or PTR_) variables at h- or u- points. */
 #  define NJMEM_      :
+!/*! Expands to : in dynamic memory mode, or to NIMEMB_ in static memory mode. Use for heap (ALLOCABLE_ or PTR_) variables at h- or v- points. */
 #  define NIMEMB_PTR_ :
+!/*! Expands to : in dynamic memory mode, or to NJMEMB_ in static memory mode. Use for heap (ALLOCABLE_ or PTR_) variables at h- or u- points. */
 #  define NJMEMB_PTR_ :
 #  ifdef SYMMETRIC_MEMORY_
+!/*! Expands to : or 0: in dynamic memory mode, or is the staggered i-shape of a tile in static memory mode. Use for heap (ALLOCABLE_ or PTR_) variables at q- or u- points. */
 #    define NIMEMB_   0:
+!/*! Expands to : or 0: in dynamic memory mode, or is the staggered j-shape of a tile in static memory mode. Use for heap (ALLOCABLE_ or PTR_) variables at q- or v- points. */
 #    define NJMEMB_   0:
 #  else
 #    define NIMEMB_   :
 #    define NJMEMB_   :
 #  endif
+!/*! Expands to 0: in dynamic memory mode, or is the staggered i-shape of a tile in static memory mode. Use for always-symmetric heap (ALLOCABLE_ or PTR_) variables at q- or u- points. */
 #  define NIMEMB_SYM_ 0:
+!/*! Expands to 0: in dynamic memory mode, or is the staggered j-shape of a tile in static memory mode. Use for always-symmetric heap (ALLOCABLE_ or PTR_) variables at q- or v- points. */
 #  define NJMEMB_SYM_ 0:
+!/*! Expands to : in dynamic memory mode or is to the number of layers in static memory mode. Use for heap (ALLOCABLE_ or PTR_) layer variables. */
 #  define NKMEM_      :
+!/*! Expands to 0: in dynamic memory mode or to 0:NK_ in static memory mode. Use for heap (ALLOCABLE_ or PTR_) interface variables. */
 #  define NKMEM0_     0:
+!/*! Expands to : in dynamic memory mode or to NK_+1 in static memory mode. Use for heap (ALLOCABLE_ or PTR_) interface variables. */
 #  define NK_INTERFACE_  :
+!/*! Expands to : or 1. UNKNOWN PURPOSE! */
 #  define C1_         :
+!/*! Expands to : or 2. UNKNOWN PURPOSE! */
 #  define C2_         :
+!/*! Expands to : or 3. UNKNOWN PURPOSE! */
 #  define C3_         :
-! These are the macros that should be used for subroutine arguments
-! or for automatically allocated (stack) variables.
+
+!/*! \todo Explain or remove C1_, C2_ and C3_ */
+
+!/* These are the macros that should be used for subroutine arguments or for automatically allocated (stack) variables. */
+
+!/*! The i-shape of a dummy argument staggered at h- or v-points. */
 #  define SZI_(G)     G%isd:G%ied
+!/*! The j-shape of a dummy argument staggered at h- or u-points. */
 #  define SZJ_(G)     G%jsd:G%jed
+!/*! The k-shape of a layer dummy argument. */
 #  define SZK_(G)     G%ke
+!/*! The k-shape of an interface dummy argument. */
 #  define SZK0_(G)    0:G%ke
+!/*! The i-shape of a dummy argument staggered at q- or u-points. */
 #  define SZIB_(G)    G%IsdB:G%IedB
+!/*! The j-shape of a dummy argument staggered at q- or v-points. */
 #  define SZJB_(G)    G%JsdB:G%JedB
+!/*! The i-shape of a symmetric dummy argument staggered at q- or u-points. */
 #  define SZIBS_(G)   G%isd-1:G%ied
+!/*! The j-shape of a symmetric dummy argument staggered at q- or v-points. */
 #  define SZJBS_(G)   G%jsd-1:G%jed
 
 #endif
 
-! These dynamic size macros always give the same results (for now).
+!/* These dynamic size macros always give the same results (for now). */
+
+!/*! The i-shape of a dynamic dummy argument staggered at h- or v-points. */
 #define SZDI_(G)  G%isd:G%ied
+!/*! The i-shape of a dynamic dummy argument staggered at q- or u-points. */
 #define SZDIB_(G) G%IsdB:G%IedB
+!/*! The j-shape of a dynamic dummy argument staggered at h- or u-points. */
 #define SZDJ_(G)  G%jsd:G%jed
+!/*! The j-shape of a dynamic dummy argument staggered at q- or v-points. */
 #define SZDJB_(G) G%JsdB:G%JedB
diff --git a/src/framework/_Diagnostics.dox b/src/framework/_Diagnostics.dox
index af5f36c209..853ad2cadd 100644
--- a/src/framework/_Diagnostics.dox
+++ b/src/framework/_Diagnostics.dox
@@ -152,8 +152,8 @@ The run-time parameter `NUM_DIAG_COORDS` controls how many diagnostic coordinate
 
 The run-time parameter `DIAG_COORDS` defines the mapping between each coordinate, the name of the module in the diag_table and run-time parameter names that define the coordinate.
 A list of string tuples, separated by commas, with each tuple in the form of MODULE_SUFFIX PARAMETER_SUFFIX COORDINATE_NAME.
-`MODULE_SUFFIX` is the string appended to "ocean_model_" to create a module in the diag_table.
-`PARAMETER_SUFFIX` is the string appended to "DiAG_COORD_DEF_", and other paramaters, used to control the generation of the named coordinate.
+`MODULE_SUFFIX` is the string appended to "ocean_model" to create a module in the diag_table.
+`PARAMETER_SUFFIX` is the string appended to "DiAG_COORD_DEF", and other parameters, used to control the generation of the named coordinate.
 `COORDINATE_NAME` is a name understood by the MOM6 regridding module. Valid examples are "ZSTAR", "SIGMA", "RHO", etc.
 
 By default, `NUM_DIAG_COORDS=1` and `DIAG_COORDS="z Z ZSTAR"`, meaning the module "ocean_model_z" provides diagnostics in "z*" coordinates and uses the parameter `DIAG_COORD_DEF_Z`.
diff --git a/src/framework/_Horizontal_indexing.dox b/src/framework/_Horizontal_indexing.dox
index fb15604e82..ea9f7ffde9 100644
--- a/src/framework/_Horizontal_indexing.dox
+++ b/src/framework/_Horizontal_indexing.dox
@@ -80,6 +80,8 @@ The file MOM_memory_macros.h provides the macros `SZI_`, `SZJ_`, `SZIB_` and `SZ
 - `real, dimension(SZI_(HI), SZJB_(HI)) :: Dv !< Depth at v-points (m)`
 - `real, dimension(SZIB_(HI), SZJB_(HI)) :: Dq !< Depth at q-points (m)`
 
+See MOM_memory_macros.h for the complete list of macros used in various memory modes.
+
 \section Global_index Calculating a global index
 
 For the most part MOM6 code should be independent of an equivalent absolute global index.
diff --git a/src/framework/_Runtime_parameter_system.dox b/src/framework/_Runtime_parameter_system.dox
index 25e9e5031e..20baa8a0a3 100644
--- a/src/framework/_Runtime_parameter_system.dox
+++ b/src/framework/_Runtime_parameter_system.dox
@@ -9,7 +9,7 @@ MOM6 has an extensive set of parameters that are set at run-time by parsing an i
 Run-time parameters are provided to the model in two phases:
 
 1. A very small set of logistical parameters are read as namelist variables from the FMS parameter file `input.nml`. One of these logistical parameters is a list of ascii files that contain all the other run-time parameters.
-1. All of the above-named parameter files are scanned for MOM6 model parameters, default values assigned and replaced, conflicts detected and various parameter summaries logged to files and/or the standard output.
+2. All of the above-named parameter files are scanned for MOM6 model parameters, default values assigned and replaced, conflicts detected and various parameter summaries logged to files and/or the standard output.
 
 \subsection mom6_namelist Namelist parameters (`input.nml`)
 
@@ -33,9 +33,7 @@ Parameter names must be constructed from the characters `[A-Za-z0-9_]` and by so
 
 Parameters that are not specified in the parameter files may assume a default value. It is not an error to specify a parameter more than once with the same value. It is an error to specify different values.
 
-The keyword `#override` indicates that this parameter specification takes precedence over other specifications. It is **not** an error to have two #override specifications for a single parameter with the same values. It is an error to have two #override statements with different values.
-
-The __soon to be deprecated__ #define keyword causes the parameter to assume the provided value (or in the case of logical parameters to be set to .TRUE.). If the parameter has a default value, the value provided will be assumed and the default value ignored. It is not an error to have two #define statements for a single parameter with the same values. It is an error to have two #define statements with different values.
+The keyword \#override indicates that this parameter specification takes precedence over other specifications. It is **not** an error to have two \#override specifications for a single parameter with the same values. It is an error to have two \#override statements with different values.
 
 Some illustrations:
 \code{.unparsed}
@@ -77,7 +75,7 @@ In addition, there are also calls that log derived quantities (e.g., a time-step
 There are several techniques that are used for error checking on MOM6 parameters:
 
 - Some parameters have internal error messages if they are set to nonsensical values.
-- No parameter can be set twice inconsistently without an explicit `#override` specification.
+- No parameter can be set twice inconsistently without an explicit \#override specification.
 - If the run-time parameter REPORT_UNUSED_PARAMS is true, a warning will be issued for any entries in the input parameter files that are not read in, for instance if they are misspelled.
 - Setting the run-time parameter FATAL_UNUSED_PARAMS to true causes a fatal error that will bring down the model if there are any unused entries in the input parameter files.
 
diff --git a/src/ice_shelf/MOM_ice_shelf.F90 b/src/ice_shelf/MOM_ice_shelf.F90
index 0af1dd7ee5..853a62a29c 100644
--- a/src/ice_shelf/MOM_ice_shelf.F90
+++ b/src/ice_shelf/MOM_ice_shelf.F90
@@ -6715,7 +6715,7 @@ end subroutine ice_shelf_advect_temp_y
 !!                  (ISSUE:  No need to use control structure - add arguments.
 !!      matrix_diagonal_triangle - LET'S TAKE THIS OUT
 !!  ice_shelf_advect - Given the melt rate and velocities, it advects the ice shelf THICKNESS
-!!        - modified h_shelf, area_shelf_h, hmask
+!!      - modified h_shelf, area_shelf_h, hmask
 !!        (maybe should updater mass_shelf as well ???)
 !!    ice_shelf_advect_thickness_x, ice_shelf_advect_thickness_y - These
 !!        subroutines determine the mass fluxes through the faces.
diff --git a/src/parameterizations/lateral/MOM_mixed_layer_restrat.F90 b/src/parameterizations/lateral/MOM_mixed_layer_restrat.F90
index e76cbad338..85ef9aeaf8 100644
--- a/src/parameterizations/lateral/MOM_mixed_layer_restrat.F90
+++ b/src/parameterizations/lateral/MOM_mixed_layer_restrat.F90
@@ -996,7 +996,7 @@ end subroutine mixedlayer_restrat_register_restarts
 !! \f[
 !!    \bar{H} \leftarrow \max \left( H, \frac{ \Delta t H + \tau_h \bar{H} }{ \Delta t + \tau_h } \right)
 !! \f]
-!! which allows the effective mixed-layer depth seen by the parameterization, $\bar{H}$, to instantaneously deepen
+!! which allows the effective mixed-layer depth seen by the parameterization, \f$\bar{H}\f$, to instantaneously deepen
 !! but to decay with time-scale \f$ \tau_h \f$.
 !! \f$ \bar{H} \f$ is substituted for \f$ H \f$ in the above equations.
 !!
diff --git a/src/parameterizations/lateral/MOM_thickness_diffuse.F90 b/src/parameterizations/lateral/MOM_thickness_diffuse.F90
index 0d658bbaf6..1b18c80c2f 100644
--- a/src/parameterizations/lateral/MOM_thickness_diffuse.F90
+++ b/src/parameterizations/lateral/MOM_thickness_diffuse.F90
@@ -1816,6 +1816,8 @@ end subroutine thickness_diffuse_end
 
 !> \namespace mom_thickness_diffuse
 !!
+!! \section section_gm Thickness diffusion (aka Gent-McWilliams)
+!!
 !! Thickness diffusion is implemented via along-layer mass fluxes
 !! \f[
 !! h^\dagger \leftarrow h^n - \Delta t \nabla \cdot ( \vec{uh}^* )
diff --git a/src/parameterizations/vertical/MOM_diabatic_driver.F90 b/src/parameterizations/vertical/MOM_diabatic_driver.F90
index 0302e3ce8e..d261a9675d 100644
--- a/src/parameterizations/vertical/MOM_diabatic_driver.F90
+++ b/src/parameterizations/vertical/MOM_diabatic_driver.F90
@@ -2381,36 +2381,5 @@ end subroutine diabatic_driver_end
 !!  the length of time over which to act (dt).  The velocities and
 !!  thickness are taken as inputs and modified within the subroutine.
 !!  There is no limit on the time step.
-!!
-!!
-!!  \section section_gridlayout MOM grid layout
-!!
-!!  A small fragment of the grid is shown below:
-!!
-!! \verbatim
-!!    j+1  x ^ x ^ x
-!!
-!!    j+1  > o > o >
-!!
-!!    j    x ^ x ^ x
-!!
-!!    j    > o > o >
-!!
-!!    j-1  x ^ x ^ x
-!!
-!!        i-1  i  i+1
-!!
-!!           i  i+1
-!!
-!! \endverbatim
-!!
-!!  Fields at each point
-!!  * x =  q, CoriolisBu
-!!  * ^ =  v, PFv, CAv, vh, diffv, tauy, vbt, vhtr
-!!  * > =  u, PFu, CAu, uh, diffu, taux, ubt, uhtr
-!!  * o =  h, bathyT, eta, T, S, tr
-!!
-!!  The boundaries always run through q grid points (x).
-!!
 
 end module MOM_diabatic_driver
diff --git a/src/parameterizations/vertical/MOM_kappa_shear.F90 b/src/parameterizations/vertical/MOM_kappa_shear.F90
index 18957e12e4..52e48f4a00 100644
--- a/src/parameterizations/vertical/MOM_kappa_shear.F90
+++ b/src/parameterizations/vertical/MOM_kappa_shear.F90
@@ -808,7 +808,7 @@ subroutine Calculate_kappa_shear(u_in, v_in, h, tv, p_surf, kappa_io, tke_io, &
             ksrc_av(K) = (1.0-wt_itt)*ksrc_av(K) + wt_itt*k_src(K)
             wt_tot = wt_tot + dz_Int(K) * ksrc_av(K)
           enddo
-          ! Use Adcroft's 1/0=0 convention.
+          ! Use the 1/0=0 convention.
           I_wt_tot = 0.0 ; if (wt_tot > 0.0) I_wt_tot = 1.0/wt_tot
 
           do K=1,nzc+1
diff --git a/src/parameterizations/vertical/MOM_set_diffusivity.F90 b/src/parameterizations/vertical/MOM_set_diffusivity.F90
index 4e37a5755f..f026a7f477 100644
--- a/src/parameterizations/vertical/MOM_set_diffusivity.F90
+++ b/src/parameterizations/vertical/MOM_set_diffusivity.F90
@@ -1313,9 +1313,11 @@ end subroutine find_N2
 
 !> This subroutine sets the additional diffusivities of temperature and
 !! salinity due to double diffusion, using the same functional form as is
-!! used in MOM4.1, and taken from an NCAR technical note (###REF?) that updates
+!! used in MOM4.1, and taken from an NCAR technical note (REF?) that updates
 !! what was in Large et al. (1994).  All the coefficients here should probably
 !! be made run-time variables rather than hard-coded constants.
+!!
+!! \todo Find reference for NCAR tech note above.
 subroutine double_diffusion(tv, h, T_f, S_f, j, G, GV, CS, Kd_T_dd, Kd_S_dd)
   type(ocean_grid_type),    intent(in)  :: G   !< The ocean's grid structure.
   type(verticalGrid_type),  intent(in)  :: GV  !< The ocean's vertical grid structure.
diff --git a/src/tracer/MOM_tracer_advect.F90 b/src/tracer/MOM_tracer_advect.F90
index 3bd4569b53..98aa65c5e3 100644
--- a/src/tracer/MOM_tracer_advect.F90
+++ b/src/tracer/MOM_tracer_advect.F90
@@ -939,35 +939,5 @@ end subroutine tracer_advect_end
 !!  it is essential that the volume fluxes should be correct.  It is
 !!  also important that the tracer advection occurs before each
 !!  calculation of the diabatic forcing.
-!!
-!!  \section section_gridlayout MOM grid layout
-!!
-!!  A small fragment of the grid is shown below:
-!!
-!! \verbatim
-!!    j+1  x ^ x ^ x
-!!
-!!    j+1  > o > o >
-!!
-!!    j    x ^ x ^ x
-!!
-!!    j    > o > o >
-!!
-!!    j-1  x ^ x ^ x
-!!
-!!        i-1  i  i+1
-!!
-!!           i  i+1
-!!
-!! \endverbatim
-!!
-!!  Fields at each point
-!!  * x =  q, CoriolisBu
-!!  * ^ =  v, PFv, CAv, vh, diffv, tauy, vbt, vhtr
-!!  * > =  u, PFu, CAu, uh, diffu, taux, ubt, uhtr
-!!  * o =  h, bathyT, eta, T, S, tr
-!!
-!!  The boundaries always run through q grid points (x).
-!!
 
 end module MOM_tracer_advect
diff --git a/src/tracer/MOM_tracer_hor_diff.F90 b/src/tracer/MOM_tracer_hor_diff.F90
index 0fd5d697f8..8840970037 100644
--- a/src/tracer/MOM_tracer_hor_diff.F90
+++ b/src/tracer/MOM_tracer_hor_diff.F90
@@ -1464,35 +1464,5 @@ end subroutine tracer_hor_diff_end
 !!  diffusion if Khtr is defined and positive.  The tracer diffusion
 !!  can use a suitable number of iterations to guarantee stability
 !!  with an arbitrarily large time step.
-!!
-!!  \section section_gridlayout MOM grid layout
-!!
-!!  A small fragment of the grid is shown below:
-!!
-!! \verbatim
-!!    j+1  x ^ x ^ x
-!!
-!!    j+1  > o > o >
-!!
-!!    j    x ^ x ^ x
-!!
-!!    j    > o > o >
-!!
-!!    j-1  x ^ x ^ x
-!!
-!!        i-1  i  i+1
-!!
-!!           i  i+1
-!!
-!! \endverbatim
-!!
-!!  Fields at each point
-!!  * x =  q, CoriolisBu
-!!  * ^ =  v, PFv, CAv, vh, diffv, tauy, vbt, vhtr
-!!  * > =  u, PFu, CAu, uh, diffu, taux, ubt, uhtr
-!!  * o =  h, bathyT, eta, T, S, tr
-!!
-!!  The boundaries always run through q grid points (x).
-!!
 
 end module MOM_tracer_hor_diff
diff --git a/src/tracer/boundary_impulse_tracer.F90 b/src/tracer/boundary_impulse_tracer.F90
index d4e29c02f5..be586320e9 100644
--- a/src/tracer/boundary_impulse_tracer.F90
+++ b/src/tracer/boundary_impulse_tracer.F90
@@ -503,7 +503,7 @@ end subroutine boundary_impulse_tracer_end
 !! mean age.
 !!
 !! A boundary impulse response (BIR) is a passive tracer whose surface boundary condition is a rectangle
-!! function with width $\Delta t$. In the case of unsteady flow, multiple BIRs, initiated at different
+!! function with width \f$\Delta t\f$. In the case of unsteady flow, multiple BIRs, initiated at different
 !! times in the model can be used to infer the transit time distribution or Green's function between
 !! the oceanic surface and interior. In the case of steady or cyclostationary flow, a single BIR is
 !! sufficient.
diff --git a/src/user/SCM_CVmix_tests.F90 b/src/user/SCM_CVmix_tests.F90
index bd135c5046..82f228d687 100644
--- a/src/user/SCM_CVmix_tests.F90
+++ b/src/user/SCM_CVmix_tests.F90
@@ -47,7 +47,7 @@ module SCM_CVmix_tests
 
 !> Initializes temperature and salinity for the SCM CVmix test example
 subroutine SCM_CVmix_tests_TS_init(T, S, h, G, GV, param_file, just_read_params)
-  real, dimension(NIMEM_,NJMEM_, NKMEM_), intent(out) :: T !< Potential tempera\ture (degC)
+  real, dimension(NIMEM_,NJMEM_, NKMEM_), intent(out) :: T !< Potential temperature (degC)
   real, dimension(NIMEM_,NJMEM_, NKMEM_), intent(out) :: S !< Salinity (psu)
   real, dimension(NIMEM_,NJMEM_, NKMEM_), intent(in)  :: h !< Layer thickness (m or Pa)
   type(ocean_grid_type),                  intent(in)  :: G !< Grid structure

From baf4a823014a4196bcae947e3d81144c9b4eacdb Mon Sep 17 00:00:00 2001
From: Alistair Adcroft 
Date: Wed, 19 Jul 2017 08:55:12 -0600
Subject: [PATCH 6/6] Updated pip requirements.txt

---
 docs/requirements.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index f9922d0257..56b47c40d4 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1,2 @@
--e git+https://github.com/angus-g/sphinxcontrib-autodoc_doxygen.git#egg=sphinxcontrib-autodoc_doxygen
--e git+https://github.com/angus-g/sphinx-fortran.git#egg=sphinx-fortran
+git+https://github.com/angus-g/sphinxcontrib-autodoc_doxygen.git#egg=sphinxcontrib-autodoc_doxygen
+git+https://github.com/angus-g/sphinx-fortran.git#egg=sphinx-fortran