Convert rules document to an automated ReadTheDocs build

.gitignore

@@ -1 +1,3 @@
 *.pyc
+docs/_build/
+docs/html/

.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 `cd docs && make 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/Makefile

@@ -0,0 +1,21 @@
+# Makefile for building the ESM Standard Names Sphinx documentation locally.
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = html
+
+.PHONY: help html clean
+
+help:
+	@echo "Targets:"
+	@echo "  html   - build the HTML docs into $(BUILDDIR)/"
+	@echo "  clean  - remove the built docs"
+
+html:
+	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/."
+
+clean:
+	rm -rf "$(BUILDDIR)"

docs/chapters/technical_specifications.rst

@@ -0,0 +1,45 @@
+.. _tech_specs:
+
+Technical specifications
+========================
+
+#. The standard name dictionary consists of a number of individual XML elements:
+   one ``standard_name`` element for each entry. A standard name entry consist of a ``name`` attribute
+   that represents the variable name, and (optionally) a ``description`` attribute that gives
+   a detailed description of what that name represents. Note that the ``description`` field is only
+   provided for information and disambiguation only (though it should be unique), and does not need to be included for
+   individual implementations of the standard names. This is not necessarily the same as the ``long_name`` entry as described
+   in the `CCPP Technical Documentation <https://ccpp-techdoc.readthedocs.io/en/latest/CompliantPhysicsParams.html#ccpp-arg-table>`_,
+   but it can be used to inform the contents of that field. The ``standard_name`` XML entry also contains a nested
+   ``type`` entry, indicating the data type that a ``standard_name`` should represent, and as an attribute the
+   physical units of that variable quantity (see the :ref:`section on Units <units_section>`). For example, the element
+   for the variable name ``exner_function`` may look similar to this::
+
+    <standard_name name="exner_function"
+                   description="exner function, (p/p0)^(Rd/cp), where p0 is 1000 hPa">
+      <type units="1">real</type>
+    </standard_name>
+
+   This XML element indicates that the variable ``exner_function`` represents the quantity described by the ``description``
+   attribute. It is a real variable with units of "1", meaning it is non-dimensional and
+   does not correspond to a more descriptive non-dimensional type such as "fraction"; see the :ref:`section on Units <units_section>`
+   for more details.
+
+   The standard_name elements are grouped into sections by "section" elements. These are parsed out into human-readable sections
+   in the generated markdown file (``Metadata-standard-names.md``). Sections can contain nested sections for further categorization.
+   Standard Names should be sorted alphabetically by name within a given section. A python tool ``tools/sort_standard_names.py`` is
+   provided to sort the names automatically.
+
+#. Only alphanumeric, punctuation, and whitespace characters from the ASCII character set may be used in the standard_names dictionary.
+   The "name" attributes of ``standard_name`` entries (i.e. the standard names themselves) are further restricted to the character set of capital/lowercase letters, numerals, and ``_`` (underscore).
+
+#. The `<type>` element should include a value that is one of the following valid Fortran types:
+
+   - ``integer``
+   - ``real``
+   - ``logical``
+   - ``character``
+   - ``complex``
+   - ``ddt`` (derived data type)
+
+#. The standard name dictionary XML file should validate according to the schema file ``standard_names.xsd`` All of the above specifications should be coded into this schema file as is appropriate.