Update documentation for v3.0.0 release #925
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add `sphinx-copybutton` extension for markdown formatted as code - Add `docs-verisoned` command to `Makefile`
tomvothecoder
commented
Jan 28, 2025
There was a problem hiding this comment.
Hey @chengzhuzhang, this PR to update documentation is now ready for review. The description lists the summary of changes. Thank you!
Comment on lines
+63
to
+66
| **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. |
There was a problem hiding this comment.
Added new section to Current State describing v3.
Comment on lines
109
to
122
| (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: |
There was a problem hiding this comment.
Replace the "a) Latest Stable Release" section with just creating a fresh conda env with latest stable e3sm_diags.
Comment on lines
+49
to
+59
| ### 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. | ||
|
|
There was a problem hiding this comment.
Added new section to Current State describing v3.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
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.ymlandconda-env/dev.yml: Addedsphinx-copybuttonto the list of dependencies. [1] [2]Configuration Changes:
docs/source/conf.py: Addedsphinx_copybuttonto the list of Sphinx extensions.docs/source/conf.py: Removed thehtml_theme_pathsetting.Makefile: Adddocs-versionedcommand to generate docs usingsphinx-multiversionInstallation Instructions:
docs/source/install.rst: Updated instructions for downloading and installing Miniforge instead of Mambaforge. Removed references to the outdatedacme1machine and updated the conda environment creation commands. [1] [2] [3] [4]mambasection back tocondasince conda now useslibmambaas default solver #821Removal of Outdated References:
docs/source/quickguides/generate_quick_guides.py: Removed references toacme1machine. [1] [2]docs/source/quickguides/index.rst: Removed the quick guide foracme1.docs/source/quickguides/old/index.rst: Removed old quick guides for version 1./docs/source/examples.rst: Updatesallocreference for perlmutterChecklist
If applicable: