OlgaSergienko · OlgaSergienko · Apr 28, 2026 · Feb 28, 2026 · Mar 5, 2026 · Apr 8, 2026
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -8,6 +8,10 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  jobs:
+    build:
+      html:
+        - sphinx-build -M html docs $READTHEDOCS_OUTPUT -j auto
 
 # Extra formats
 # PDF generation is failing for now; disabled on 2020-12-02

diff --git a/ac/makedep b/ac/makedep
@@ -389,7 +389,9 @@ def scan_fortran_file(src_file, defines=None):
 
     cpp_defines = defines if defines is not None else []
 
-    cpp_macros = dict([t.split('=') for t in cpp_defines])
+    cpp_macros = dict(
+        [t.split('=') if '=' in t else (t, None) for t in cpp_defines]
+    )
     cpp_group_stack = []
 
     with io.open(src_file, 'r', errors='replace') as file:
@@ -454,13 +456,14 @@ def scan_fortran_file(src_file, defines=None):
             # Activate a new macro (ignoring the value)
             match = re_cpp_define.match(line)
             if match:
+                # TODO: Tokenize this, don't hunt for `(` in `macro`.
                 tokens = line.strip()[1:].split(maxsplit=2)
                 macro = tokens[1]
                 value = tokens[2] if tokens[2:] else None
                 if '(' in macro:
                     # TODO: Actual handling of function macros
                     macro, arg = macro.split('(', maxsplit=1)
-                    value = '(' + arg + value
+                    value = '(' + arg + value if value else '(' + arg
                 cpp_macros[macro] = value
 
             # Deactivate a macro

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -16,3 +16,8 @@ xml
 # Citation output
 bib*.aux
 citelist.doc*
+
+
+# Python bytecode cache from the vendored _ext/autodoc_doxygen extension
+__pycache__
+*.pyc
diff --git a/docs/Doxyfile_rtd b/docs/Doxyfile_rtd
@@ -872,7 +872,8 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = ../src/equation_of_state/TEOS10
+EXCLUDE                = ../src/equation_of_state/TEOS10 \
+                         ../src/parameterizations/CVmix
 
 # 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
@@ -1954,7 +1955,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

diff --git a/docs/Makefile b/docs/Makefile
@@ -25,7 +25,7 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -65,38 +65,45 @@ $(BUILDDIR):
 	mkdir -p $@
 
 html: $(DOXYGENBIN) $(BUILDDIR)
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -M html . $(BUILDDIR) $(ALLSPHINXOPTS) -j auto
+# Optional equation post-processing (was a patch in jr3cermak/sphinx@v3.2.1mom6.4
+# applied to sphinx/cmd/build.py); now invoked from the Makefile so we can run
+# against stock upstream Sphinx. The nortd target below has the same hook.
+ifeq ($(UPDATEHTMLEQS), Y)
+	@echo "Post processing equations."
+	@python3 ./postProcessEquations.py -d $(BUILDDIR) -p html -b sphinx -s index.html $(UPDATEHTMLEQSVERBOSE)
+endif
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	$(SPHINXBUILD) -M dirhtml . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	$(SPHINXBUILD) -M singlehtml . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	$(SPHINXBUILD) -M pickle . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	$(SPHINXBUILD) -M json . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	$(SPHINXBUILD) -M htmlhelp . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
 qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	$(SPHINXBUILD) -M qthelp . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@@ -105,7 +112,7 @@ qthelp:
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MOM6.qhc"
 
 devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	$(SPHINXBUILD) -M devhelp . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
@@ -114,48 +121,48 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	$(SPHINXBUILD) -M epub . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 latex: $(DOXYGENBIN) $(BUILDDIR)
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD) -M latex . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf: $(DOXYGENBIN) $(BUILDDIR)
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD) -M latex . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex LATEXMKOPTS="-f -silent" all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD) -M latex . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	$(SPHINXBUILD) -M text . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
 man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	$(SPHINXBUILD) -M man . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
 texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	$(SPHINXBUILD) -M texinfo . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
 info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	$(SPHINXBUILD) -M texinfo . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
@@ -166,28 +173,28 @@ gettext:
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
 changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	$(SPHINXBUILD) -M changes . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	$(SPHINXBUILD) -M linkcheck . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
 doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	$(SPHINXBUILD) -M doctest . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
 xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	$(SPHINXBUILD) -M xml . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
 
 pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	$(SPHINXBUILD) -M pseudoxml . $(BUILDDIR) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
 

diff --git a/docs/README.md b/docs/README.md
@@ -249,9 +249,11 @@ added to the RTD administrative interface if you want to trigger post processing
 
 If `UPDATEHTMLEQSVERBOSE` is set to `-v` this will turn on verbose printing for the post processor.
 
-NOTE: These options affect solo doxygen html processing only for the `make nortd` option.  For sphinx, they are
-utilized in the sphinx python module to handle post processing and are not part of the Makefile.  This was done
-as RTD runs sphinx processing directly using `sphinx-build` and not the Makefile.
+The post-processing hook is invoked from the `Makefile` for both the
+`make nortd` (doxygen html) and `make html` (sphinx html) targets. RTD,
+which runs `sphinx-build` directly without using this Makefile, will not
+trigger the hook automatically; if equation post-processing is desired
+on RTD it must be run as a separate step from the RTD build configuration.
 
 ##### PAPER
 
@@ -316,18 +318,27 @@ pip install -r requirements.txt
 
 You may need to use `pip3` to install requirements for python3.
 
-Requirements:
-- sphinx
-- sphinx-rtd-theme
-- sphinx-bibtex
-- sphinx-fortran
-- sphinxcontrib\_autodox-doxygen
-- flint
-- lxml
-- numpy
-- future
-
-For machines that need to build future, numpy or lxml, these packages are required:
+The full pinned set lives in `requirements.txt`. The current toolchain
+uses stock upstream Sphinx 8.x from PyPI:
+
+- `sphinx>=8,<9`
+- `sphinx-rtd-theme`
+- `sphinxcontrib-bibtex`
+- `lxml` (used by the vendored `_ext/autodoc_doxygen` extension to
+  parse the Doxygen XML output)
+- `numpy`
+- `sphinx-fortran` from the upstream `VACUMM/sphinx-fortran` repository,
+  pinned to a specific commit (upstream has not cut a PyPI release past
+  1.1.1 but the master branch has continued fixes)
+- `six`, still required at module load time by the pinned `sphinx-fortran`
+  commit
+
+The `sphinxcontrib-autodoc_doxygen` Sphinx extension that was previously
+pulled in as a separate fork is now vendored in-tree under
+`docs/_ext/autodoc_doxygen/`; nothing extra needs to be installed for it.
+
+For machines that need to build numpy or lxml from source, these packages
+are required:
 - Cython
 - wheel
 
@@ -342,8 +353,8 @@ PDF generation requires the following packages
 ### doxygen
 
 You may choose to download the [source](https://www.doxygen.nl/download.html).
-
-Latest is `doxygen-1.8.20.src.tar.gz`.
+The example below uses `1.8.20` but you can substitute any compatible
+release tarball.
 
 ```bash
 tar xzf doxygen-1.8.20.src.tar.gz
@@ -356,15 +367,17 @@ sudo make install
 ```
 
 The makefile for doxygen attempts to install the compiled version into /usr/local/bin.
-You can link to a specific executable within the virtual environment.   At this point we
-also recommend renaming `doxygen` to `doxygen-1.8.20` within `/usr/local/bin`.
+You can link to a specific executable within the virtual environment.
 
-NOTE: The makefile for the documentation framework will attempt to compile a local doxygen
-binary of version 1.8.13 if a binary cannot be found in the `$PATH`.
+NOTE: If a doxygen binary is not found in `$PATH`, the documentation Makefile
+will attempt to clone and compile its own copy of doxygen from source. The
+default release pulled in this fallback path is set by `DOXYGEN_RELEASE` in
+the Makefile (currently `Release_1_8_13`); pass a different value to override.
 
 #### Testing
 
-A lot of manual testing has been completed using the following versions:
+The toolchain is known to work with doxygen versions in the 1.8.x and 1.9.x
+series. Older manual testing was performed against:
 * 1.8.13
 * 1.8.14
 * 1.8.19
@@ -376,7 +389,9 @@ The [Read the Docs](https://readthedocs.org/) (RTD) site uses a virtual
 machine (VM) for processing documentation.  The VM architecture is type x86\_64.
 The default version for doxygen is 1.8.13 on the RTD VM.
 
-NOTE: Using modified python modules on RTD is possible through careful crafting of the requirements.txt file.  It is impossible to replace system binaries or compile code on RTD.  It is possible to ship replacement binaries that can be run from the repo.  For security reasons, a binary cannot be included in the MOM6 repository.
+NOTE: It is impossible to replace system binaries or compile code on RTD.
+It is possible to ship replacement binaries that can be run from the repo.
+For security reasons, a binary cannot be included in the MOM6 repository.
 
 #### Logfiles
 
@@ -387,19 +402,37 @@ Most websites force download of `*.log` files.
 
 # Credits
 
+## 2026
+The documentation toolchain was modernized to run against stock upstream
+Sphinx 8.x. The four-fork chain that the build had been carrying since
+2020 was reduced to:
+
+- A vendored copy of the Doxygen-to-Sphinx bridge under
+  `docs/_ext/autodoc_doxygen/`, originally derived from the `0.7.13`
+  release of `jr3cermak/sphinxcontrib-autodoc_doxygen`. The vendored
+  version is ported to the Sphinx 8 API and lives in-tree where it can
+  be debugged and edited like any other project source.
+- A pinned commit of upstream `VACUMM/sphinx-fortran` master.
+- A small monkey-patch in `conf.py` for `sphinx.util.math.wrap_displaymath`
+  that suppresses Sphinx's default outer wrapping when the source already
+  supplies its own LaTeX environment, replacing the only functional change
+  the previous Sphinx fork carried.
+- A small monkey-patch in `conf.py` for
+  `sphinxfortran.fortran_domain.FortranDomain.merge_domaindata` to fix a
+  parallel-build bug in upstream sphinx-fortran. To be removed when
+  upstream merges a fix.
+
+The `flint` dependency (formerly used to patch Doxygen's incomplete
+parsing of Fortran functions with `result()` clauses) was dropped after
+verifying empirically that nothing in the build pipeline references it.
+
 ## 2020
-The documentation pipeline was upgraded by [Rob Cermak](https://github.com/jr3cermak) and [Marshall Ward](https://github.com/marshallward).  Four modified python modules are required
-to process the MOM6 documentation.  The versions are tagged and placed into the production version of `requirements.txt`.  Development versions may be found in the respective `dev` branches.
-
-| Source | Modified | Version | Development |
-| ------ | -------- | ------- | ----------- |
-| [sphinx](https://github.com/sphinx-doc/sphinx) | [sphinx-3.2.1mom6.4](https://github.com/jr3cermak/sphinx) | B:3.2.1mom6.4 | B:dev |
-| [sphinxcontrib-autodoc-doxygen](https://github.com/rmcgibbo/sphinxcontrib-autodoc_doxygen) | [sphinxcontrib-autodoc-doxygen](https://github.com/jr3cermak/sphinxcontrib-autodoc_doxygen) | T:0.7.13 | B:dev |
-| [sphinx-fortran](https://github.com/VACUMM/sphinx-fortran) | [sphinx-fortran](https://github.com/jr3cermak/sphinx-fortran) | T:1.2.2 | B:dev |
-| [flint](https://github.com/marshallward/flint) | [flint](https://github.com/jr3cermak/flint) | T:0.0.1 | B:dev |
-| [MOM6](https://github.com/NOAA-GFDL/MOM6) | [esmg-docs](https://github.com/ESMG/MOM6/tree/esmg-docs) | [esmg-docs](https://github.com/ESMG/MOM6/tree/esmg-docs) | B:[esmg-test](https://github.com/jr3cermak/MOM6/tree/esmg-test) |
-
-T: tag B: branch
+The documentation pipeline was upgraded by [Rob Cermak](https://github.com/jr3cermak)
+and [Marshall Ward](https://github.com/marshallward). The pipeline at that time
+required four modified Python modules (`sphinx`, `sphinxcontrib-autodoc_doxygen`,
+`sphinx-fortran`, `flint`), all forked under the `jr3cermak` GitHub account.
+That toolchain was retired during the 2026 modernization above; this entry
+is retained as historical context.
 
 ## 2017
 The sphinx documentation of MOM6 is made possible by modifications by [Angus Gibson](https://github.com/angus-g) to two packages, [sphinx-fortran](https://github.com/angus-g/sphinx-fortran) and [autodoc\_doxygen](https://github.com/angus-g/sphinxcontrib-autodoc_doxygen).