Update documentation for v3.0.0 release #925

tomvothecoder · 2025-01-28T20:21:46Z

Description

This pull request includes several changes to the documentation and dependencies, along with updates to the installation and usage instructions. The most important changes include the addition of a new Sphinx extension, updates to the documentation to reflect the new version, and the removal of outdated references.

Documentation Updates:

Closes [Doc]: Update references to v2 with v3 #917
README.md: Added a section about the major refactor in version 3, highlighting the transition from CDAT to Xarray and xCDAT.
docs/source/index.rst: Updated the version number from v2 to v3 and removed outdated warnings and references. [1] [2]

Dependency Changes:

conda-env/ci.yml and conda-env/dev.yml: Added sphinx-copybutton to the list of dependencies. [1] [2]

Configuration Changes:

docs/source/conf.py: Added sphinx_copybutton to the list of Sphinx extensions.
docs/source/conf.py: Removed the html_theme_path setting.
Makefile: Add docs-versioned command to generate docs using sphinx-multiversion

Installation Instructions:

docs/source/install.rst: Updated instructions for downloading and installing Miniforge instead of Mambaforge. Removed references to the outdated acme1 machine and updated the conda environment creation commands. [1] [2] [3] [4]
- Closes [Doc]: Installation docs need to be updated #799
- Closes [Doc]: Revert mamba section back to conda since conda now uses libmamba as default solver #821

Removal of Outdated References:

docs/source/quickguides/generate_quick_guides.py: Removed references to acme1 machine. [1] [2]
docs/source/quickguides/index.rst: Removed the quick guide for acme1.
docs/source/quickguides/old/index.rst: Removed old quick guides for version 1.
/docs/source/examples.rst: Update salloc reference for perlmutter

TODO

Cori references to Perlmutter
Update E3SM Unified paths

Checklist

My code follows the style guidelines of this project
I have performed a self-review of my own code
My changes generate no new warnings
Any dependent changes have been merged and published in downstream modules

If applicable:

New and existing unit tests pass with my changes (locally and CI/CD build)
I have added tests that prove my fix is effective or that my feature works
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
I have noted that this is a breaking change for a major release (fix or feature that would cause existing functionality to not work as expected)

- Add `sphinx-copybutton` extension for markdown formatted as code - Add `docs-verisoned` command to `Makefile`

tomvothecoder

Hey @chengzhuzhang, this PR to update documentation is now ready for review. The description lists the summary of changes. Thank you!

tomvothecoder · 2025-01-28T22:38:59Z

docs/source/index.rst

+**ARM diags**, and **TC analysis** 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.


Added new section to Current State describing v3.

tomvothecoder · 2025-01-28T22:39:56Z

docs/source/install.rst

 (a) Latest Stable Release
 -------------------------

-1. Follow :ref:`"Others/Local" <conda_environment_others>` section for installing Conda.
-
-2. Get the yml file to create an environment.
-
-    ::
-
-        wget https://raw.githubusercontent.com/E3SM-Project/e3sm_diags/main/conda-env/prod.yml
-
-
-3. Change ``prefix`` in that file to be your conda prefix. Typically, this will be ``~/miniconda3/envs/e3sm_diags_env``.
+1. Follow :ref:`"Others/Local" <conda_environment_others>` section for installing conda.

-4. Remove any cached conda packages. This will ensure that you always get the latest packages
+Create a new conda environment with ``e3sm_diags`` installed and activate it:

    ::

-        mamba clean --all
-
-5. Use conda to create a new environment with E3SM Diags (``e3sm_diags``) included.
-These steps should not be necessary if you installed Mambaforge as suggested
-above but may be needed if you have previously installed Miniconda3 instead: ::
-
-   conda install -y -n base mamba
-   conda config --add channels conda-forge
-   conda config --set channel_priority strict
-
-Create a new conda environment with ``e3sm_diags`` installed and activate it: ::
-
-        mamba env create -f conda-env/prod.yml # Tip: Add the flag ``-n <name_of_env>`` to customize the name of the environment  
+        # Tip: Add the flag ``-n <name_of_env>`` to customize the name of the environment
+        conda create -n e3sm_diags_env e3sm_diags
        conda activate e3sm_diags_env

 .. _dev-env:


Replace the "a) Latest Stable Release" section with just creating a fresh conda env with latest stable e3sm_diags.

tomvothecoder · 2025-01-28T22:40:30Z

README.md

+### 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.
+


Added new section to Current State describing v3.

great write up.

tomvothecoder · 2025-03-19T20:47:24Z

@chengzhuzhang I think we just have this PR and PR #953 (soon to be merged) before we can release v3.0.0. Let me know if you need additional help here. I think this PR covers most of the changes already.

chengzhuzhang · 2025-03-21T18:58:48Z

README.md

 ### 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           |


added v2.12.1 feature change

chengzhuzhang · 2025-03-21T18:59:22Z

docs/source/index.rst

@@ -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/>`_.


update to use the 2024 tutorial example.

chengzhuzhang · 2025-03-21T19:00:05Z

docs/source/install.rst


 1. Follow :ref:`"Others/Local" <conda_environment_others>` section for installing conda.

-2. Clone your fork and keep it in sync with the main repo's ``main``
+2. Create a new fork of e3sm_diags:


simplify this session.

chengzhuzhang

I added some more updates.

tomvothecoder added 6 commits January 28, 2025 14:21

Update mamba references to conda

0aed4f4

- Add `sphinx-copybutton` extension for markdown formatted as code - Add `docs-verisoned` command to `Makefile`

Remove old v1 quickguides

74cdef3

Remove acme1 references and warning about importing module

4186348

Update v2 references to v3

3aab4b6

Add info about v3 in current state

1cb57f2

Update salloc command in examples

f2572e0

tomvothecoder marked this pull request as ready for review January 28, 2025 21:44

tomvothecoder commented Jan 28, 2025

View reviewed changes

tomvothecoder self-assigned this Jan 28, 2025

tomvothecoder added the documentation Files in `docs` modified label Jan 28, 2025

tomvothecoder added this to the FY25 Q2 (01/01/25 - 03/31/25) milestone Jan 28, 2025

tomvothecoder requested a review from chengzhuzhang January 28, 2025 22:43

tomvothecoder mentioned this pull request Mar 19, 2025

Bump to v3.0.0 #956

Merged

13 tasks

chengzhuzhang added 5 commits March 20, 2025 10:46

Merge branch 'main' into docs/917-v3-updates

99f609a

doc update

4a81aab

more doc changes

4b925ac

update README

30335a8

fix markdown table format

d92bcd8

chengzhuzhang reviewed Mar 21, 2025

View reviewed changes

chengzhuzhang approved these changes Mar 21, 2025

View reviewed changes

chengzhuzhang self-assigned this Mar 21, 2025

chengzhuzhang approved these changes Mar 21, 2025

View reviewed changes

Merge branch 'main' into docs/917-v3-updates

0d88a10

chengzhuzhang merged commit eec450a into main Mar 21, 2025
6 checks passed

chengzhuzhang deleted the docs/917-v3-updates branch March 21, 2025 21:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update documentation for v3.0.0 release #925

Update documentation for v3.0.0 release #925

tomvothecoder commented Jan 28, 2025 •

edited

Loading

tomvothecoder left a comment

tomvothecoder Jan 28, 2025

tomvothecoder Jan 28, 2025

tomvothecoder Jan 28, 2025

chengzhuzhang Jan 31, 2025

tomvothecoder commented Mar 19, 2025

chengzhuzhang Mar 21, 2025

chengzhuzhang Mar 21, 2025

chengzhuzhang Mar 21, 2025

chengzhuzhang left a comment

Update documentation for v3.0.0 release #925

Update documentation for v3.0.0 release #925

Conversation

tomvothecoder commented Jan 28, 2025 • edited Loading

Description

Documentation Updates:

Dependency Changes:

Configuration Changes:

Installation Instructions:

Removal of Outdated References:

TODO

Checklist

tomvothecoder left a comment

Choose a reason for hiding this comment

tomvothecoder Jan 28, 2025

Choose a reason for hiding this comment

tomvothecoder Jan 28, 2025

Choose a reason for hiding this comment

tomvothecoder Jan 28, 2025

Choose a reason for hiding this comment

chengzhuzhang Jan 31, 2025

Choose a reason for hiding this comment

tomvothecoder commented Mar 19, 2025

chengzhuzhang Mar 21, 2025

Choose a reason for hiding this comment

chengzhuzhang Mar 21, 2025

Choose a reason for hiding this comment

chengzhuzhang Mar 21, 2025

Choose a reason for hiding this comment

chengzhuzhang left a comment

Choose a reason for hiding this comment

tomvothecoder commented Jan 28, 2025 •

edited

Loading