Skip to content

Commit 54b84f1

Browse files
xylarxylar
committed
Fix table of contents and simplify package catalog
This merge adds `index.md` files in each subdirectory of the docs to help ensure that the table of contents is laid out intuitively. The table providing the package catalog has been updated so that different versions of dependencies for different python versions are split into multiple rows for readability.
1 parent 785a944 commit 54b84f1

File tree

8 files changed

+79
-54
lines changed

8 files changed

+79
-54
lines changed

‎docs/index.md‎

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,11 @@
11
```{toctree}
22
:hidden:
3-
:maxdepth: 3
3+
:maxdepth: 1
44
55
introduction
66
quickstart
77
using-tools
8-
9-
releasing/release-workflow
10-
releasing/conda-vs-spack
11-
releasing/planning-updates
12-
releasing/creating-rcs/overview
13-
releasing/creating-rcs/rc-dependencies
14-
releasing/creating-rcs/rc-e3sm-unified
15-
releasing/creating-rcs/rc-troubleshooting
16-
releasing/testing/overview
17-
releasing/testing/spack-updates
18-
releasing/testing/mache-updates
19-
releasing/testing/deploying-on-hpcs
20-
releasing/testing/troubleshooting-deploy
21-
releasing/adding-new-machines
22-
releasing/finalizing-release
23-
releasing/maintaining-past-versions
24-
8+
releasing/index
259
packages
2610
troubleshooting
2711
contributing

‎docs/packages.md‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# 📦 E3SM-Unified Package Catalog
1+
# Package Catalog
22

33
This page provides a complete inventory of packages included in the latest
44
E3SM-Unified release (`1.11.1`), along with their versions. These packages
@@ -9,6 +9,12 @@ for what is installed in the environment.
99

1010
## Main Packages and Dependencies
1111

12+
Empty cells under "Version Constraint" indicate that there is no constraint
13+
on that package. Blank cells under "Package Name" indicate the same package
14+
as above. Some package are forced to have different versions for different
15+
python versions (typically when the dependency has dropped support for a python
16+
version that we wish to support).
17+
1218
| Package Name | Version Constraint |
1319
|----------------------|-----------------------------|
1420
| blas | |
@@ -23,7 +29,8 @@ for what is installed in the environment.
2329
| cime_gen_domain | 6.1.59 |
2430
| cmocean | |
2531
| cython | |
26-
| dask | 2024.8.0 (py<3.10), 2024.11.2 (py>=3.10) |
32+
| dask | 2024.8.0 (py<3.10) |
33+
| | 2024.11.2 (py>=3.10) |
2734
| dogpile.cache | |
2835
| e3sm_diags | 3.0.0 |
2936
| e3sm-tools | 3.0.2 |
@@ -74,7 +81,8 @@ for what is installed in the environment.
7481
| progessbar2 | |
7582
| proj | 9.5.1 |
7683
| psutil | |
77-
| pyproj | 3.6.1 (py<3.10), 3.7.0 (py>=3.10) |
84+
| pyproj | 3.6.1 (py<3.10) |
85+
| | 3.7.0 (py>=3.10) |
7886
| pyevtk | |
7987
| pyremap | |
8088
| pytest | |
@@ -91,9 +99,11 @@ for what is installed in the environment.
9199
| tabulate | |
92100
| tempest-extremes | 2.2.3 |
93101
| tempest-remap | 2.2.0 |
94-
| uxarray | 2024.11.1 (py<3.10), >=2024.12.0 (py>=3.10) |
102+
| uxarray | 2024.11.1 (py<3.10) |
103+
| | >=2024.12.0 (py>=3.10) |
95104
| windspharm | |
96-
| xarray | 2024.7.0 (py<3.10), 2025.1.1 (py>=3.10) |
105+
| xarray | 2024.7.0 (py<3.10) |
106+
| | 2025.1.1 (py>=3.10) |
97107
| xcdat | 0.8.0 |
98108
| xesmf | 0.8.8 |
99109
| zppy | 3.0.0 |

‎docs/releasing/creating-rcs/index.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Creating Release Candidates
2+
3+
E3SM-Unified and its core dependencies follow a structured release process
4+
that relies on **release candidates (RCs)**. These pre-release versions are
5+
used for testing and validation before an official release is finalized and
6+
deployed.
7+
8+
This section describes how to create RCs for both individual dependencies
9+
(like `e3sm_diags` or `mpas-analysis`) and for the `e3sm-unified` metapackage
10+
itself. It also includes tools and tips for troubleshooting build failures.
11+
12+
```{toctree}
13+
:maxdepth: 1
14+
15+
overview
16+
rc-dependencies
17+
rc-e3sm-unified
18+
rc-troubleshooting
19+
```

‎docs/releasing/creating-rcs/overview.md‎

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,4 @@
1-
# Creating Release Candidates
2-
3-
E3SM-Unified and its core dependencies follow a structured release process
4-
that relies on **release candidates (RCs)**. These pre-release versions are
5-
used for testing and validation before an official release is finalized and
6-
deployed.
7-
8-
This section describes how to create RCs for both individual dependencies
9-
(like `e3sm_diags` or `mpas-analysis`) and for the `e3sm-unified` metapackage
10-
itself. It also includes tools and tips for troubleshooting build failures.
11-
12-
---
1+
# Overview of Release Candidate Workflows
132

143
## What Is a Release Candidate?
154

‎docs/releasing/index.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Release Workflow
2+
3+
Releasing a new version of E3SM-Unified is an iterative, collaborative process
4+
involving Conda, Spack, and coordinated deployment across HPC systems. This
5+
guide serves as a roadmap for each stage in the workflow.
6+
7+
Whether you're updating packages, building release candidates, or testing on
8+
HPC platforms, this section documents the steps needed to bring a new version
9+
of E3SM-Unified from planning to full deployment.
10+
11+
```{toctree}
12+
:maxdepth: 1
13+
14+
release-workflow
15+
conda-vs-spack
16+
planning-updates
17+
creating-rcs/index
18+
testing/index
19+
adding-new-machines
20+
finalizing-release
21+
maintaining-past-versions
22+
```

‎docs/releasing/release-workflow.md‎

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,14 @@
1-
# The E3SM-Unified Release Workflow
2-
3-
Releasing a new version of E3SM-Unified is an iterative, collaborative process
4-
involving Conda, Spack, and coordinated deployment across HPC systems. This
5-
guide serves as a roadmap for each stage in the workflow.
6-
7-
Whether you're updating packages, building release candidates, or testing on
8-
HPC platforms, this section documents the steps needed to bring a new version
9-
of E3SM-Unified from planning to full deployment.
10-
11-
---
12-
13-
## Overview of the Workflow
1+
# Overview of the Workflow
142

153
The release process typically follows this progression:
164

175
1. **[How Conda and Spack Work Together in E3SM-Unified](conda-vs-spack.md)**
186
2. **[Planning Package Updates](planning-updates.md)**
197
3. **[Creating Release Candidates](creating-rcs/overview.md)**
208
4. **[Deployment and Testing](testing/overview.md)**
9+
5. **[Adding a New Machine](adding-new-machines.md)**
2110
6. **[Finalizing the Release](finalizing-release.md)**
11+
7. **[Maintaining Past Versionse](maintaining-past-versions.md)**
2212

2313
Each of these steps is detailed in its own page. See below for a high-level
2414
summary.

‎docs/releasing/testing/index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Deployment and Testing
2+
3+
Once a release candidate (RC) of E3SM-Unified has been successfully built, it
4+
must be thoroughly tested across supported HPC systems before a full release
5+
can occur. This phase ensures compatibility with system modules,
6+
performance-critical tools, and real-world analysis workflows.
7+
8+
```{toctree}
9+
:maxdepth: 1
10+
11+
overview
12+
spack-updates
13+
mache-updates
14+
deploying-on-hpcs
15+
troubleshooting-deploy
16+
```

‎docs/releasing/testing/overview.md‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,4 @@
1-
# Deployment and Testing Overview
2-
3-
Once a release candidate (RC) of E3SM-Unified has been successfully built, it
4-
must be thoroughly tested across supported HPC systems before a full release
5-
can occur. This phase ensures compatibility with system modules,
6-
performance-critical tools, and real-world analysis workflows.
1+
# Overview of Deployment and Testing
72

83
This section documents the full testing and deployment process, including how
94
to:

0 commit comments

Comments
 (0)