Convert rules document to an automated ReadTheDocs build, add comments to metadata files

.gitignore

@@ -1 +1,2 @@
 *.pyc
+docs/_build/

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

README.md

@@ -2,7 +2,10 @@
 
 The Earth System Modeling Standard Names Repository contains community-accepted Standard Names, publishing tools, and search tools.
 
-Rules governing the designation and format of standard names can be found in [StandardNamesRules.rst](https://github.com/ESCOMP/ESMStandardNames/blob/main/StandardNamesRules.rst).
+Rules governing the designation and format of standard names are published as a chaptered
+Sphinx/Read the Docs site built from the [docs/](docs/) directory; see
+[docs/index.rst](https://github.com/ESCOMP/ESMStandardNames/blob/main/docs/index.rst) for the
+table of contents, or build it locally with `sphinx-build -b html docs docs/html`.
 
 A [Markdown file describing the standard names is included](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.md), as well as a [YAML version of the XML file](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.yaml).
 

docs/chapters/aliases.rst

@@ -0,0 +1,67 @@
+.. _Aliases:
+
+Acronyms, Abbreviations, and Aliases
+====================================
+
++---------------------+---------------------------------------------------------+
+| **Short**           |  **Meaning**                                            |
++=====================+=========================================================+
+| cnvc90              | GFS Convective Cloud Diagnostics                        |
++---------------------+---------------------------------------------------------+
+| edmf                | eddy-diffusivity/mass-flux                              |
++---------------------+---------------------------------------------------------+
+| gwd                 | gravity wave drag                                       |
++---------------------+---------------------------------------------------------+
+| gfdl                | Geophysical Fluid Dynamics Laboratory                   |
++---------------------+---------------------------------------------------------+
+| gfs                 | Global Forecast System                                  |
++---------------------+---------------------------------------------------------+
+| ir                  | infrared                                                |
++---------------------+---------------------------------------------------------+
+| lwe                 | liquid water equivalent                                 |
++---------------------+---------------------------------------------------------+
+| max                 | maximum                                                 |
++---------------------+---------------------------------------------------------+
+| min                 | minimum                                                 |
++---------------------+---------------------------------------------------------+
+| myj                 | Mellor-Yamada-Janjic scheme                             |
++---------------------+---------------------------------------------------------+
+| mynn                | Mellor-Yamada-Nakanishi-Niino scheme                    |
++---------------------+---------------------------------------------------------+
+| nir                 | near-infrared part of the EM spectrum (radiation)       |
++---------------------+---------------------------------------------------------+
+| nrl                 | Naval Research Lab                                      |
++---------------------+---------------------------------------------------------+
+| nsstm               | GFS near-surface sea temperature scheme                 |
++---------------------+---------------------------------------------------------+
+| pbl                 | planetary boundary layer                                |
++---------------------+---------------------------------------------------------+
+| pdf                 | probability density function                            |
++---------------------+---------------------------------------------------------+
+| rrtmgp              | Rapid Radiative Transfer Model for General circulation  |
+|                     | model applications - Parallel                           |
++---------------------+---------------------------------------------------------+
+| sas                 | simplified Arakawa-Schubert scheme                      |
++---------------------+---------------------------------------------------------+
+| skeb                | stochastic kinetic energy backscatter                   |
++---------------------+---------------------------------------------------------+
+| shoc                | simplified higher-order closure stochastic scheme       |
++---------------------+---------------------------------------------------------+
+| shum                | stochastically perturbed boundary-layer humidity scheme |
++---------------------+---------------------------------------------------------+
+| sppt                | stochastically perturbed physics tendencies             |
++---------------------+---------------------------------------------------------+
+| stp                 | standard temperature (0 degC) and pressure (101325 Pa)  |
++---------------------+---------------------------------------------------------+
+| tke                 | turbulent kinetic energy                                |
++---------------------+---------------------------------------------------------+
+| toa                 | top of atmosphere                                       |
++---------------------+---------------------------------------------------------+
+| ugwp                | Unified Gravity Wave Physics                            |
++---------------------+---------------------------------------------------------+
+| uv                  | ultraviolet part of the EM spectrum (radiation)         |
++---------------------+---------------------------------------------------------+
+| vis                 | visible part of the EM spectrum (radiation)             |
++---------------------+---------------------------------------------------------+
+| wrt                 | with respect to                                         |
++---------------------+---------------------------------------------------------+

docs/chapters/common_components.rst

@@ -0,0 +1,57 @@
+Other common standard name components
+=====================================
+
+Reserved phrase
+---------------
+
+These words/phrases should not be used outside of the described context
+
++------------------------+-------------------------------------------------------------------------------------+
+| **Phrase**             |  **Usage**                                                                          |
++========================+=====================================================================================+
+| ccpp                   | Variable names provided by the CCPP framework                                       |
++------------------------+-------------------------------------------------------------------------------------+
+
+
+Special phrases
+---------------
+
++------------------------+-------------------------------------------------------------------------------------+
+| **Phrase**             |  **Meaning**                                                                        |
++========================+=====================================================================================+
+| anomaly                | difference from climatology                                                         |
++------------------------+-------------------------------------------------------------------------------------+
+| area                   | horizontal area unless otherwise stated                                             |
++------------------------+-------------------------------------------------------------------------------------+
+| atmosphere             | used instead of in_air for quantities which are large-scale rather than local       |
++------------------------+-------------------------------------------------------------------------------------+
+| condensed_water        | liquid and ice                                                                      |
++------------------------+-------------------------------------------------------------------------------------+
+| frozen_water           | ice                                                                                 |
++------------------------+-------------------------------------------------------------------------------------+
+| interface              | The vertical boundary of a model layer.                                             |
++------------------------+-------------------------------------------------------------------------------------+
+| longwave               | Longwave radiation. Defined as thermal emission of radiation from the planet.       |
++------------------------+-------------------------------------------------------------------------------------+
+| moisture               | water in all phases contained in soil                                               |
++------------------------+-------------------------------------------------------------------------------------+
+| ocean                  | used instead of in_sea_water for quantities which are large-scale rather than local |
++------------------------+-------------------------------------------------------------------------------------+
+| shortwave              | Shortwave radiation. Defined as electromagnetic emissions from the sun              |
++------------------------+-------------------------------------------------------------------------------------+
+| specific               | per unit mass unless otherwise stated                                               |
++------------------------+-------------------------------------------------------------------------------------+
+| surface                | The top of the solid or liquid medium below the atmosphere                          |
++------------------------+-------------------------------------------------------------------------------------+
+| unfrozen_water         | liquid and vapor                                                                    |
++------------------------+-------------------------------------------------------------------------------------+
+| water                  | water in all phases if not otherwise qualified                                      |
++------------------------+-------------------------------------------------------------------------------------+
+| dimensionless          | lacking units                                                                       |
++------------------------+-------------------------------------------------------------------------------------+
+| kinematic              | refers to surface fluxes in "native" units (K m s-1 and kg kg-1 m s-1)              |
++------------------------+-------------------------------------------------------------------------------------+
+| direct                 | used in radiation (as opposed to diffuse)                                           |
++------------------------+-------------------------------------------------------------------------------------+
+| diffuse                | used in radiation (as opposed to direct)                                            |
++------------------------+-------------------------------------------------------------------------------------+