Update documentation for v3.0.0 release (#925)

* Update mamba references to conda
- Add `sphinx-copybutton` extension for markdown formatted as code
- Add `docs-verisoned` command to `Makefile`

* Remove old v1 quickguides

* Remove acme1 references and warning about importing module

* Update v2 references to v3

* Add info about v3 in current state

* Update salloc command in examples

* doc update

* more doc changes

* update README

* fix markdown table format

---------

Co-authored-by: Jill Chengzhu Zhang <[email protected]>

Author: tomvothecoder

Makefile

@@ -88,6 +88,13 @@ docs: ## generate Sphinx HTML documentation, including API docs
 	$(MAKE) -C docs html
 	$(BROWSER) docs/_build/html/index.html
 
+docs-versioned: ## generate verisoned Sphinx HTML documentation, including API docs
+	rm -rf docs/generated
+	cd docs && sphinx-multiversion source _build/html
+	$(MAKE) -C docs clean
+	$(MAKE) -C docs html
+	$(BROWSER) docs/_build/html/index.html
+
 # Build
 # ----------------------
 install: clean ## install the package to the active Python's site-packages

README.md

@@ -46,10 +46,22 @@ This diagnostics package is constructed for supporting the diagnostics task of D
 
 E3SM Diags is modeled after the National Center for Atmospheric Research (NCAR) Atmosphere Model Working Group (AMWG) diagnostics package. In its version 1 release, E3SM Diags included a set of core essential diagnostics to evaluate the mean physical climate from model simulations. As of version 2, more process-oriented and phenomenon-based evaluation diagnostics have been implemented, as listed below:
 
+### Major refactor with v3 development
+
+v3.0.0 marks a major milestone after nearly two years of work by the core development
+team. This release introduces a completely new back-end, replacing CDAT with Xarray and
+xCDAT. Due to the significant scale of code changes, this has been incremented as a
+major release. The user-facing API for running E3SM Diagnostics remains backward-compatible between v2 and v3.
+
+The modernization improves performance, usability, and maintainability, paving the way
+for future enhancements to E3SM development. The refactored codebase is now more robust
+and extensively covered by unit tests, setting a solid foundation for ongoing testing and development.
+
 ### New Feature added during v2 development
 
 | Feature name <br />(set name)                                       | Brief Introduction                                                                                                                                                                                     | Developers Contributors\*                                                                                                                                             | Released version |
 | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| Added Qbo wavelet analysis (qbo)               		      | The spectrum analysis in the QBO dataset was enhanced with an additional wavelet-based analysis                     		                                                       		       | Justine richling , Walter Hannah, Jim Benedict                                                                                                                        | 2.12.1           |
 | Wavenumber frequency analysis (tropical_subseasonal)                | The wavenumber frequency analysis (Wheeler-Kiladis Diagram) for Tropical subseasonal analysis                                                                                                          | Jim Benedict, Brian Medeiros, Jill Zhang, Tom Vo                                                                                                                      | 2.12.0           |
 | T5050 diagnostic /Mixed phase partition (mp_partition)              | Temperature at which cloud top is 50% ice, 50% liquid, following McCoy et al. (2015).                                                                                                                  | Yuying Zhang, Jill Zhang, Jiwen Fan, Yunpeng Shan                                                                                                                     | 2.9.0            |
 | ARM diagnostics v3 (arm_diags)                                      | Enhanced ARM diagnostics with new aerosol-cloud-interaction and aerosol activation metrics                                                                                                             | Xiaojian Zheng, Jill Zhang, Cheng Tao, Shaocheng Xie                                                                                                                  | 2.9.0            |

conda-env/ci.yml

@@ -36,3 +36,4 @@ dependencies:
   - sphinx
   - sphinx_rtd_theme
   - sphinx-multiversion
+  - sphinx-copybutton

conda-env/dev.yml

@@ -33,6 +33,7 @@ dependencies:
   - sphinx
   - sphinx_rtd_theme
   - sphinx-multiversion
+  - sphinx-copybutton
   # Quality Assurance Tools
   # =======================
   # Run `pre-commit autoupdate` to get the latest pinned versions of 'rev' in

docs/source/conf.py

@@ -33,6 +33,7 @@
 extensions = [
     "sphinx_rtd_theme",
     "sphinx_multiversion",
+    "sphinx_copybutton"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -88,7 +89,6 @@
 #
 
 html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 html_sidebars = {
     "**": [
         "versions.html",

docs/source/examples.rst

@@ -5,7 +5,7 @@ Examples
 Introduction
 ============
 
-The model and observation data are located at NERSC, so you can run the examples on Cori.
+The model and observation data are located at NERSC, so you can run the examples on Perlmutter CPU.
 
 Make sure you're using version 2.0.0 or greater of e3sm_diags.
 
@@ -131,9 +131,9 @@ Use the code below to run the diagnostics.
     .. code::
 
         # Allocate a node to run an interactive session on. You can also use a batch job.
-        salloc --nodes=1 --partition=regular --time=01:00:00 -C haswell
-        # Enter the E3SM Unified environment. For Cori, the command to do this is:
-        source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_cori-haswell.sh
+        salloc --nodes 1 --qos interactive --time 01:00:00 --constraint cpu --account=e3sm
+        # Enter the E3SM Unified environment. For Perlmutter CPU, the command to do this is:
+        source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_pm-cpu.sh
         # Running Ex.1. For examples 4,5,7 append ``-d diags.cfg``.
         python ex1.py --multiprocessing --num_workers=32
         # You may need to change permissions on your web directory to see the example output.
@@ -175,7 +175,7 @@ These were generated with the following script:
        # emacs ex6-model-vs-obs-custom/ex6.py
        # emacs ex7-obs-vs-obs/ex7.py
 
-       source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_cori-haswell.sh
+       source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_pm-cpu.sh
        cd ex1-model_ts-vs-model_ts
        python ex1.py --multiprocessing --num_workers=32
        cd ../ex2-model_ts-vs-model_ts-cmip

docs/source/index.rst

@@ -6,18 +6,13 @@
 .. _index-label:
 
 ***************************
-E3SM Diagnostics Package v2
+E3SM Diagnostics Package v3
 ***************************
 Welcome to the E3SM Diagnostics Package documentation hub.
 
 To change the documentation version, use the version selector in the bottom left-hand corner.
 Please note, documentation for versions ``v2.5.0`` are not available in the version selector.
 
-.. warning::
-    As of ``v2.6.0``, ``e3sm_diags`` should be used as the module name instead of
-    ``acme_diags``. Instances of ``acme_diags`` in the Python import statements should
-    be replaced accordingly.
-
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
@@ -53,14 +48,21 @@ that:
 -  is flexible for user-specified diagnostics and configuration for
    use by other earth system models.
 
-Current State (v2 release)
---------------------------
+Current State
+-------------
 
 Algorithm and visualization codes for **latitude-longitude contour maps**,
-**polar contour maps**, the accompanying **summarizing table** and **Taylor diagram plots**,  **pressure-latitude zonal mean contour plots**,
-**zonal mean line plots**, **pressure-longitude meridional mean contour plots**, **area mean time series plots**, and **Cloud Top Height-Tau** joint histograms
-from COSP cloud simulator output. Plots can be created for annual
-and seasonal climatologies, and monthly mean time series. In additional to the core sets being released in v1, **ENSO diags**, **QBO diags**, **Diurnal cycle phase plot**, **Streamflow evaluation**, **ARM diags**, and **TC analysis** are implemented in v2 release.
+**polar contour maps**, the accompanying **summarizing table** and
+**Taylor diagram plots**,  **pressure-latitude zonal mean contour plots**,
+**zonal mean line plots**, **pressure-longitude meridional mean contour plots**,
+**area mean time series plots**, and **Cloud Top Height-Tau** joint histograms from
+COSP cloud simulator output. Plots can be created for annual and seasonal climatologies,
+and monthly mean time series. In additional to the core sets being released in v1,
+**ENSO diags**, **QBO diags**, **Diurnal cycle phase plot**, **Streamflow evaluation**,
+**ARM diags**, and **TC analysis**, **Mixed Phase Partition**, and **Wheeler-Kiladis Diagram** are implemented in v2 release. v3 introduces a
+completely new back-end, replacing CDAT with Xarray and xCDAT. Due to the significant
+scale of code changes, this has been incremented as a major release. The user-facing
+API for running E3SM Diagnostics remains backward-compatible between v2 and v3.
 
 The package also supports custom user diagnostics, by specifying
 plot type, desired region (global, ocean, land, etc.),
@@ -149,7 +151,7 @@ Additional back-ends could be implemented if the need arose.
 +--------------------------------------------------------+------------------------------------------------------+
 
 The above plots and more can be found
-`here <https://portal.nersc.gov/cfs/e3sm/zhang40/tutorials/run_v230_allsets/viewer/>`_.
+`here <https://portal.nersc.gov/cfs/e3sm/chengzhu/tutorial2024/e3sm_diags_extended/viewer/>`_.
 
 Feature availability for each backend
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^