Improve docs, mostly behind the scenes

* Makes some changes to get RestructuredText to render correctly in VSCode.
* Improves .rst file searchability by straightening curly quotes/apostrophes as well as by removing manual line breaks throughout the Tech Note and User's Guide.
* Includes some small fixes and cleanup.

doc/design/dynamic_urban.rst

@@ -6,18 +6,18 @@
  Overview of this design document
 ==================================
 
-This documents some of the high-level design decisions made during implementation of 
+This documents some of the high-level design decisions made during implementation of
 dynamic urban landunits.
 
 ============================================================================
  The use of dzsoi_decomp for urban landunits to calculate totcolch4 in ch4Mod.F90
 ============================================================================
-During the first test simulation for dynamic urban, we encountered a methane conservation 
-error the first time PCT_URBAN changed. The dynamic adjustments for conc_ch4_sat_col and 
+During the first test simulation for dynamic urban, we encountered a methane conservation
+error the first time PCT_URBAN changed. The dynamic adjustments for conc_ch4_sat_col and
 conc_ch4_unsat_col (the column_state_updater in subroutine DynamicColumnAdjustments within
 ch4Mod.F90) were distributing non-zero values for roof and walls for layers 1,nlevsoi.
-When the total column ch4 is summed over the soil layers (or in this case, urban layers), the 
-summation is done over nlevsoi, not nlevurb, using dz. dz is 1.e36 for roof/wall layers 
+When the total column ch4 is summed over the soil layers (or in this case, urban layers), the
+summation is done over nlevsoi, not nlevurb, using dz. dz is 1.e36 for roof/wall layers
 that are greater than nlevurb, thus creating an imbalance.
 
 Rather than trying to keep the BGC variables physically meaningful in urban landunits,

doc/design/water_tracers.rst

@@ -30,7 +30,7 @@ Broadly speaking, we considered three ways to store information for each tracer:
    ``h2osoi_liq_col_tracer(c,j,m)`` for tracers).
 
 3. Multiple instances of ``waterstate_type`` (etc.), with no extra dimension required for
-   individual variables. 
+   individual variables.
 
 We decided to go with option (3) for a number of reasons:
 

doc/source/conf.py

@@ -37,7 +37,6 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.imgmath',
     'sphinx.ext.githubpages']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -94,8 +93,6 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-imgmath_image_format = 'svg'
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/source/lilac/obtaining-building-and-running/obtaining-and-building-ctsm.rst

@@ -250,7 +250,6 @@ Makefile-formatted file gives variables that should be set in the atmosphere mod
 build. :ref:`See below for information on how to use this
 file<including-ctsm-in-the-atmosphere-model-build>`.
 
-
 Rebuilding after changing CTSM source code
 ------------------------------------------
 

doc/source/lilac/specific-atm-models/index.rst

@@ -1,7 +1,7 @@
 .. _specific-atm-models:
 
 ==============================================================
- Instructions on using CTSM with specific atmosphere models 
+ Instructions on using CTSM with specific atmosphere models
 ==============================================================
 
 .. toctree::

doc/source/lilac/specific-atm-models/wrf-nesting.rst

@@ -11,15 +11,15 @@ nested domain.
 
 A nested domain is usually used to have a finer-resolution domain within the
 coarser model domain. A nested simulation enables running at a higher
-resolution over a smaller domain 
+resolution over a smaller domain
 
 .. note::
     A nest should cover a portion of the parent domain and is fully contained by
     the parent domain, so that it is driven along its lateral boundaries by the
-    parent domain. 
+    parent domain.
 
 .. todo::
-    Negin wants to add a flowchart showing the workflow of a nested case. 
+    Negin wants to add a flowchart showing the workflow of a nested case.
 
 There are currently two types of nesting available within WRF:
 
@@ -33,10 +33,10 @@ There are currently two types of nesting available within WRF:
         - Also, the averaged values from the inner domain are being sent back to the outer domain at the corresponding grid points.
 
 .. important::
-    Currently, the WRF-CTSM coupling infrastructure only support one-way nesting. 
-    This example clarifies the workflow for running a nested WRF-CTSM case using one-way nesting with ``ndown.exe``. 
+    Currently, the WRF-CTSM coupling infrastructure only support one-way nesting.
+    This example clarifies the workflow for running a nested WRF-CTSM case using one-way nesting with ``ndown.exe``.
 
-The procedure for running a nested simulation for WRF with CTSM is 
+The procedure for running a nested simulation for WRF with CTSM is
 similar to the workflow for running WRF real cases, except that it requires
 additional steps to (1) clone the CTSM repository, (2) build
 CTSM and LILAC, and (3) define namelist options reuired for CTSM.
@@ -46,14 +46,12 @@ A full description of all steps for a WRF-CTSM run are included here.
 .. important::
 
   This section assumes the user has completed all the steps required for
-  WRF-CTSM simulation single domain. 
+  WRF-CTSM simulation single domain.
   Therefore, we are not repeating the steps necessary for building WRF and
-  CTSM. 
-
+  CTSM.
 
 In this example we use a nested domain over the CONUS as shows below:
 
-
 .. _Figure ctsm-ndown:
 
 .. figure:: ndown_ctsm_diagram.svg
@@ -105,7 +103,7 @@ Nested Simulations : Pre-processing (ungrib.exe)
 -------------------------------------------------
 As mentioned previously, the purpose of the ungrib script is to unpack GRIB
 meteorological data and pack it into an intermediate file format.
-This step is exactly identical to a non-nested simulation. 
+This step is exactly identical to a non-nested simulation.
 
 Run ungrib to get gribbed data into usable format to be ingested by WRF.
 
@@ -128,12 +126,11 @@ Check ungrib log for the following message showing successful completion of ungr
 
 At this point, you should see ungrib output (intermediate files) in your WPS directory.
 
-
 Nested Simulations : Pre-processing (metgrid.exe)
 -------------------------------------------------
 Ensure that the `start_date` and `end_date` for domain two is set correctly for
 your simulation.
-Next, run ``metgrid.exe``:: 
+Next, run ``metgrid.exe``::
 
     ./metgrid.exe >& log.metgrid
 
@@ -144,14 +141,12 @@ metgrid step::
     !  Successful completion of metgrid.  !
     !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
-
 Running metgrid for two domains will create files like
 below::
+
     met_em.d01.*
     met_em.d02.*
 
-
-
 Nested Simulations : real.exe
 ------------------------------
 
@@ -160,31 +155,30 @@ both domains.
 
 In summary, complete the following steps:
 
-Move or link WPS output files (``met_em.d01*`` and ``met_em.d02`` files) to your WRF test directory. 
+Move or link WPS output files (``met_em.d01*`` and ``met_em.d02`` files) to your WRF test directory.
 
 Edit namelist.input for your WRF domain and desirable configurations.
 This should be the same domain as WPS namelist. Make sure you set ``max_dom =
-2,`` in the namelist. 
+2,`` in the namelist.
 
 To run WRF-CTSM, in your namelist change land-surface option to 6 for both
 domains::
 
-    sf_surface_physics = 6, 6, 
-
+    sf_surface_physics = 6, 6,
 
 Run real.exe (if compiled parallel submit a batch job) to generate
-initail and boundary condition files for both domain. 
+initail and boundary condition files for both domain.
 Make sure the following three files have been created in your directory::
 
     wrfinput_d01
     wrfinput_d02
     wrfbdy_d01
 
-The boundary condition file is only created for the outer domain. 
+The boundary condition file is only created for the outer domain.
 
-Check the last line of the real log file for the following message::
+Check the last line of the real log file for the following message:
 
-Rename wrfinput_d02 
+Rename wrfinput_d02
 -------------------
 Next, rename the ``wrfinput_d02`` file to ``wrfndi_d02``::
 
@@ -199,24 +193,24 @@ Add the following into your namelist.input file under ``&time_control``::
 
      io_form_auxinput2 = 2
 
-Run ndown.exe to create ``wrfinput_d02`` and ``wrfbdy_d02``. 
+Run ndown.exe to create ``wrfinput_d02`` and ``wrfbdy_d02``.
 
-Run WRF for coarser domain 
+Run WRF for coarser domain
 ---------------------------
 In this step, run WRF for the outer domain.
-Make sure that ``max_dom = 1`` to run only for the coarser domain. 
+Make sure that ``max_dom = 1`` to run only for the coarser domain.
 
 This step is exactly identical as the previous example and only creates the
-``wrfout*`` files for the coarser domain. 
+``wrfout*`` files for the coarser domain.
 
 Please make sure to copy ``lnd_in`` , ``lilac_in``, and ``lnd_modelio`` for the
-coarser domain in this directory. 
+coarser domain in this directory.
 
 Create CTSM runtime files for the fine domain
 ---------------------------------------------
 This step is in addition creating CTSM runtime files for coarser domain which
 was explained here. For succesfully completing the previous step you should
-have already created these files for the coarser domain. 
+have already created these files for the coarser domain.
 
 .. seealso::
 
@@ -225,7 +219,6 @@ have already created these files for the coarser domain.
     files for the finer domain you should follow the steps in section
     :numref:`setting-ctsm-runtime-options`.
 
-
 Again, the goal here is to create files that determine CTSM runtime options which
 are defined within these three files:
 
@@ -235,28 +228,24 @@ are defined within these three files:
 
 - ``lilac_in``: This namelist controls the operation of LILAC
 
-
-Run WRF for the finer domain 
+Run WRF for the finer domain
 -----------------------------
 First, save (rename or move) the data from the coarser domain simulation
 (``wrfout_d01_*`` files).
 Next, rename ``wrfinput_d02`` and ``wrfbdy_d02`` to ``wrfinput_d01`` and ``wrfbdy_d01``, respectively.
 
-
 Edit namelist.input, moving all of the fine-grid domain data from column 2 to column 1
 so that this run will be for the fine-grid domain only. Make sure you set
 `max_dom=1` and set your `time_step` based on the finer domain.
 
-.. note:: 
-    It may be beneficial to save namelist.input to something else prior to this step in case you need to repeat this 
+.. note::
+    It may be beneficial to save namelist.input to something else prior to this step in case you need to repeat this
     process in the future. Save the newly-edited namelist as namelist.input .
 
 Now run wrf.exe by submitting a job similar to a not-nested case.
 
 .. important::
 
     The output for the finer domain is wrfout_d01_* not wrfout_d02_* and although
-    in the name it is saying d01 it is technically d02 domain. 
-
-
+    in the name it is saying d01 it is technically d02 domain.
 

doc/source/lilac/specific-atm-models/wrf-tools.rst

@@ -9,16 +9,13 @@
 This section includes instructions on tools and utilities developed for
 WRF-CTSM simulations.
 
-
-
 Generate CTSM surface dataset for a WRF domain
 ----------------------------------------------
 
 Before this step, make sure you have successfully created geo_em* files for
 your specific WRF domain using WPS. Instructions on how to run ``geogrid.exe``
 is described in here.
 
-
 1. Create SCRIP grid file from WRF ``geo_em*`` files, using the following ncl
    script::
 
@@ -39,7 +36,6 @@ is described in here.
 
     ncl mkunitymap.ncl
 
-
 .. warning::
 
     This will throw some git errors if not run in a repository.
@@ -52,7 +48,6 @@ is described in here.
 
      ../../../configure --macros-format Makefile --mpilib mpi-serial
 
-
 5. Generate CTSM domain files using ``get_domain`` tool::
 
      ./gen_domain -m /glade/work/$USER/ctsm/nldas_grid/scrip/wrf2clm_mapping_noneg.nc -o wrf2clm_ocn_noneg -l wrf2clm_lnd_noneg
@@ -61,20 +56,15 @@ is described in here.
 
      ./mksurfdata.pl -res usrspec -usr_gname "nldas" -usr_gdate "190124" -usr_mapdir "/glade/work/$USER/ctsm/nldas_grid/map" -y 2000 -exedir "/glade/u/home/$USER/src/ctsm/ctsm_surfdata/tools/mksurfdata_map" -no-crop
 
-
-
 Merge WRF initial conditions into an existing CTSM initial condition file
 --------------------------------------------------------------------------
 
 The following procedure is if you'd wish to merget WRF inital conditions from
 ``wrfinput`` file into CTSM initial condition file ::
 
-
     ncl transfer_wrfinput_to_ctsm_with_snow.ncl 'finidat="the_existing_finidat_file.nc"' 'wrfinput="your_wrfinput_file"' 'merged="the_merged_finidat_file.nc"'
 
-
 .. todo::
 
  Sam, can you please make the above ncl script available.
 
-