Further fixes to the docs, particularly the table of contents

docs/Makefile

@@ -11,7 +11,7 @@ BUILDDIR      = _build
 # Build into a versioned subdirectory
 versioned-html:
 	@echo "Building version: $(DOCS_VERSION)"
-	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html/$(DOCS_VERSION)"
+	$(SPHINXBUILD) -b html -nW --keep-going "$(SOURCEDIR)" "$(BUILDDIR)/html/$(DOCS_VERSION)"
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(DOCS_VERSION)."
 	@echo "Setting up shared version switcher for local preview..."
 	mkdir -p _build/html/shared

docs/conf.py

@@ -42,8 +42,6 @@
     "sphinx.ext.napoleon",
 ]
 
-autosummary_generate = ['developers_guide/api.md']
-
 # Otherwise, the Return parameter list looks different from the Parameters list
 napoleon_use_rtype = False
 # Otherwise, the Attributes parameter list looks different from the Parameters

docs/index.md

@@ -1,12 +1,11 @@
 ```{toctree}
 :hidden:
-:maxdepth: 3
+:maxdepth: 1
 
 introduction
 quickstart
 using-tools
-testing-release-candidates
-releasing/release-workflow
+releasing/index
 packages
 troubleshooting
 contributing

docs/packages.md

@@ -1,4 +1,4 @@
-# 📦 E3SM-Unified Package Catalog
+# Package Catalog
 
 This page provides a complete inventory of packages included in the latest
 E3SM-Unified release (`1.11.1`), along with their versions. These packages
@@ -9,6 +9,12 @@ for what is installed in the environment.
 
 ## Main Packages and Dependencies
 
+Empty cells under "Version Constraint" indicate that there is no constraint
+on that package.  Blank cells under "Package Name" indicate the same package
+as above.  Some package are forced to have different versions for different
+python versions (typically when the dependency has dropped support for a python
+version that we wish to support).
+
 | Package Name         | Version Constraint          |
 |----------------------|-----------------------------|
 | blas                 |                             |
@@ -23,7 +29,8 @@ for what is installed in the environment.
 | cime_gen_domain      | 6.1.59                      |
 | cmocean              |                             |
 | cython               |                             |
-| dask                 | 2024.8.0 (py<3.10), 2024.11.2 (py>=3.10) |
+| dask                 | 2024.8.0 (py<3.10)          |
+|                      | 2024.11.2 (py>=3.10)        |
 | dogpile.cache        |                             |
 | e3sm_diags           | 3.0.0                       |
 | e3sm-tools           | 3.0.2                       |
@@ -74,7 +81,8 @@ for what is installed in the environment.
 | progessbar2          |                             |
 | proj                 | 9.5.1                       |
 | psutil               |                             |
-| pyproj               | 3.6.1 (py<3.10), 3.7.0 (py>=3.10) |
+| pyproj               | 3.6.1 (py<3.10)             |
+|                      | 3.7.0 (py>=3.10)            |
 | pyevtk               |                             |
 | pyremap              |                             |
 | pytest               |                             |
@@ -91,9 +99,11 @@ for what is installed in the environment.
 | tabulate             |                             |
 | tempest-extremes     | 2.2.3                       |
 | tempest-remap        | 2.2.0                       |
-| uxarray              | 2024.11.1 (py<3.10), >=2024.12.0 (py>=3.10) |
+| uxarray              | 2024.11.1 (py<3.10)         |
+|                      | >=2024.12.0 (py>=3.10)      |
 | windspharm           |                             |
-| xarray               | 2024.7.0 (py<3.10), 2025.1.1 (py>=3.10) |
+| xarray               | 2024.7.0 (py<3.10)          |
+|                      | 2025.1.1 (py>=3.10)         |
 | xcdat                | 0.8.0                       |
 | xesmf                | 0.8.8                       |
 | zppy                 | 3.0.0                       |

docs/releasing/adding-new-machines.md

@@ -44,15 +44,15 @@ After updating `mache`, you'll need to:
 2. **Update Spack if needed**
 
    * If new versions of external tools are required, update the
-     [`spack_for_mache_<version>`](spack-updates.md) branch of the
+     [`spack_for_mache_<version>`](testing/spack-updates.md) branch of the
      [E3SM Spack fork](https://github.com/E3SM-Project/spack)
 
 ---
 
 ## ✅ Testing Your Changes
 
 Use the standard test deployment approach from
-[Deploying on HPCs](deploying-on-hpcs.md):
+[Deploying on HPCs](testing/deploying-on-hpcs.md):
 
 ```bash
 cd e3sm_supported_machines
@@ -88,4 +88,4 @@ During testing, focus on:
 
 ---
 
-➡ Next: [Publishing the Final Release](publishing-final-release.md)
+➡ Next: [Publishing the Final Release](finalizing-release.md)

docs/releasing/creating-rcs/index.md

@@ -0,0 +1,19 @@
+# Creating Release Candidates
+
+E3SM-Unified and its core dependencies follow a structured release process
+that relies on **release candidates (RCs)**. These pre-release versions are
+used for testing and validation before an official release is finalized and
+deployed.
+
+This section describes how to create RCs for both individual dependencies
+(like `e3sm_diags` or `mpas-analysis`) and for the `e3sm-unified` metapackage
+itself. It also includes tools and tips for troubleshooting build failures.
+
+```{toctree}
+:maxdepth: 1
+
+overview
+rc-dependencies
+rc-e3sm-unified
+rc-troubleshooting
+```

docs/releasing/creating-rcs/overview.md

@@ -1,15 +1,4 @@
-# Creating Release Candidates
-
-E3SM-Unified and its core dependencies follow a structured release process
-that relies on **release candidates (RCs)**. These pre-release versions are
-used for testing and validation before an official release is finalized and
-deployed.
-
-This section describes how to create RCs for both individual dependencies
-(like `e3sm_diags` or `mpas-analysis`) and for the `e3sm-unified` metapackage
-itself. It also includes tools and tips for troubleshooting build failures.
-
----
+# Overview of Release Candidate Workflows
 
 ## What Is a Release Candidate?
 

docs/releasing/index.md

@@ -0,0 +1,22 @@
+# Release Workflow
+
+Releasing a new version of E3SM-Unified is an iterative, collaborative process
+involving Conda, Spack, and coordinated deployment across HPC systems. This
+guide serves as a roadmap for each stage in the workflow.
+
+Whether you're updating packages, building release candidates, or testing on
+HPC platforms, this section documents the steps needed to bring a new version
+of E3SM-Unified from planning to full deployment.
+
+```{toctree}
+:maxdepth: 1
+
+release-workflow
+conda-vs-spack
+planning-updates
+creating-rcs/index
+testing/index
+adding-new-machines
+finalizing-release
+maintaining-past-versions
+```

docs/releasing/maintaining-past-versions.md

@@ -95,4 +95,4 @@ because of this.
 
 ---
 
-Back to: [Publishing the Final Release](publishing-final-release.md)
+Back to: [Publishing the Final Release](finalizing-release.md)

docs/releasing/planning-updates.md

@@ -69,7 +69,7 @@ The final list of packages is curated by the Infrastructure Team based on:
 * Community need and usage patterns
 
 Once the list is mostly settled, the team begins creating release candidates
-using the [Creating Release Candidates](creating-rcs.md) workflow.
+using the [Creating Release Candidates](creating-rcs/overview.md) workflow.
 
 ---
 

docs/releasing/release-workflow.md

@@ -1,24 +1,14 @@
-# The E3SM-Unified Release Workflow
-
-Releasing a new version of E3SM-Unified is an iterative, collaborative process
-involving Conda, Spack, and coordinated deployment across HPC systems. This
-guide serves as a roadmap for each stage in the workflow.
-
-Whether you're updating packages, building release candidates, or testing on
-HPC platforms, this section documents the steps needed to bring a new version
-of E3SM-Unified from planning to full deployment.
-
----
-
-## Overview of the Workflow
+# Overview of the Workflow
 
 The release process typically follows this progression:
 
 1. **[How Conda and Spack Work Together in E3SM-Unified](conda-vs-spack.md)**
 2. **[Planning Package Updates](planning-updates.md)**
 3. **[Creating Release Candidates](creating-rcs/overview.md)**
 4. **[Deployment and Testing](testing/overview.md)**
+5. **[Adding a New Machine](adding-new-machines.md)**
 6. **[Finalizing the Release](finalizing-release.md)**
+7. **[Maintaining Past Versionse](maintaining-past-versions.md)**
 
 Each of these steps is detailed in its own page. See below for a high-level
 summary.

docs/releasing/testing/index.md

@@ -0,0 +1,16 @@
+# Deployment and Testing
+
+Once a release candidate (RC) of E3SM-Unified has been successfully built, it
+must be thoroughly tested across supported HPC systems before a full release
+can occur. This phase ensures compatibility with system modules,
+performance-critical tools, and real-world analysis workflows.
+
+```{toctree}
+:maxdepth: 1
+
+overview
+spack-updates
+mache-updates
+deploying-on-hpcs
+troubleshooting-deploy
+```

docs/releasing/testing/overview.md

@@ -1,9 +1,4 @@
-# Deployment and Testing Overview
-
-Once a release candidate (RC) of E3SM-Unified has been successfully built, it
-must be thoroughly tested across supported HPC systems before a full release
-can occur. This phase ensures compatibility with system modules,
-performance-critical tools, and real-world analysis workflows.
+# Overview of Deployment and Testing
 
 This section documents the full testing and deployment process, including how
 to: