Document internal APIs (NOAA-GFDL#274)

* Initial commit of custom CSS for autodoc (only)

Attempt to tweak spacing of elements in autodoc pages. Styling of rest
of documentation site is unchanged.

* Fix docstring 'Returns:' formatting

* Docstring formatting fixes

* Add manually written doc section to framework TOC

* Tweak autodoc settings to remove unneeded output

* Add more space, grouping between class docstrings

* Improve mamba usage in CI

- install mamba (https://github.com/mamba-org/mamba) first, and use it
to speed up installation of all other conda envs, including the one for
synthetic data. Note that currently only the dependency solve is
accelerated (mamba-org/mamba#633), but this is
sufficient for a large improvement over conda.

- Remove the --mamba flag from the conda_env_setup.sh script's
arguments, as this was taken out in NOAA-GFDL#166.

* Add temp extremes distshape to CI (NOAA-GFDL#273)

* Initial commit of code from Arielle Catalano

* Correct extension for settings.jsonc

* Add freq=day to varlist for backwards compatibility

* Commit conda env for temp_extremes_distshape

* Commit conda env for temp_extremes_distshape

* Run temp_extremes_distshape in python_base instead of custom env

* adding new POD, documentation, and obs subset code

* Fix case of CF variable names

* Set Matplotlib backend in settings.jsonc

* Propagate gs command-line flags to GFDL branch

* Temporary debugging statements

* Update temp_extremes_distshape settings.jsonc

* Update format of settings.jsonc

* Add missing 'log' argument to GFDL data source attribute classes

* log InitVar must be 1st arg to __post_init__ due to inheritance

* Restore missing class attributes to GFDL CMIP6 DataSources

* Convert .pdf documentation to .rst

* Fix obs filenames and templating in html

* Write temp files to WK_DIR, not POD_HOME

temp_extremes_distshapes code was writing temporary parameter .json
files to $POD_HOME, which should be read-only. Change root directory for
writing all these files from $POD_HOME to $WK_DIR.

* Correct variable names

* Correct method for colorbar tick labels

* Handle case where no contours are labeled

* Correct cartopy longitude set_extents

* Correct Moments_plot colorbar positioning

* Add documentation for set_extent() fix

* add test jsonc files for temp_extremes_distshape CMIP

* added test yaml file just for temp_extremes_distshape

* add call create the inputdata directory before untarring the obs_data file to the test yaml

* add checks to test yaml

* Specify full paths in ubuntu set3 jsonc

* remove comments from test jsonc files
change CASENAME to match the format output by updated synthetic data generator in the set3 test jsonc files

* update mdtf_tests.yml to include this branch for testing before PR is submitted

* remove this branch from mdtf_tests.yml

* Switch paths back to relative locations in ubuntu set 3 jsonc

* change model name to synthetic in github actions set 3 jsonc files

* changed ls to just show temp_extremes_distshape obs_data directory

* fixed path in ls

* added print statements for path checks

* add pring statement to group_relative_links

* removed print statements from output_manager and verify_links

* changed test yml to experimental status and added ls for wkdir after POD runs

* fix typo

* remove some test lines in test_cmip.yml

* change exit status for missing files to 0 for debugging in verify_links.py

* remove debugging in verify_links
comment out pod.deactivate call in verify_links  for debugging

* removed PS from the output figure path in TempExtDistShape_CircComps_usp.py bc file is png not postscript

* changed ls to wildcard in test_cmip.yml

* dump output log to terminal

* define output figure path as separate variable with os.path.join in TempExtDistShape_ShiftRatio_util.py

* revert changes to path name

* change set3 env to python3

* change cartopy to version 0.19 in env_python3_base.yml

* revert debugging mods to output_manager.py

* remove extraneous checks from mdtf_tests.yml
test yaml with MDTF_base environment for set 3 tests

* replace _MDTF_python3_base with _MDTF_base in mdtf_tests.yml set 3 tests

Co-authored-by: Thomas Jackson <tom.jackson314@gmail.com>
Co-authored-by: tsjackson-noaa <thomas.jackson@noaa.gov>
Co-authored-by: Arielle Catalano <acat2@ggr-ch-412-ac.psu.ds.pdx.edu>

* Abbreviate logger in function/method signatures

* Set more prominent CSS highlight color

* Expand docstrings for src/util

* Commit manual doc for util subpackage

* Stop sphinx-apidoc from importing unit tests

* Fix mocking of external imports when docs are built

* Sphinx CSS tweaks

Increase item spacing, fix shading, add border for code literal
blockquotes

* Improve coverage of class attributes

Set inherited-members to True to include inherited dataclass fields and
simplify navigating class heirarchy. Define skip_members_handler() to
remove docstrings of methods we don't want to include (eg from stdlib).

* Update 'supporting modules' docstrings

* Partial commit of updated docstrings for main modules

* Fix documentation .rst syntax errors

* Initial commit of remaining manually-generated internal API docs

* Split up data source docs across multiple pages

Include sphinx links to relevant docs in module summary docstrings.

* More crossreferences in docs

* Fix module docstrings

Sphinx autosummary only includes first sentence of docstring, not first
paragraph.

Co-authored-by: Jess <20195932+wrongkindofdoctor@users.noreply.github.com>
Co-authored-by: Thomas Jackson <tom.jackson314@gmail.com>
Co-authored-by: Arielle Catalano <acat2@ggr-ch-412-ac.psu.ds.pdx.edu>

doc/conf.py

@@ -505,3 +505,4 @@ def setup(app):
         # 'enable_auto_doc_ref': True, # deprecated, now default behavior
     }, True)
     app.add_transform(AutoStructify)
+