From 22aec36f331e0230b77eca775374bccfa2eba0b2 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Mon, 22 May 2023 17:23:35 -0600 Subject: [PATCH 1/3] Switch docs to mamba and Mambaforge --- docs/source/getting_started.rst | 80 ++++++++++++++++++++------------- 1 file changed, 49 insertions(+), 31 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 149be02f..fb16d704 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -1,5 +1,5 @@ .. _getting-started: - + *************** Getting started *************** @@ -77,32 +77,38 @@ Others/Local If the system doesn't come with conda pre-installed, follow these instructions: -1. Download Conda +1. Download Mambaforge Linux :: - wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh + wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-x86_64.sh - MacOS (note that ``zppy`` is not supported on MacOS, but it may be useful to contribute to the documentation on MacOS) + MacOS x86_64 (note that ``zppy`` is not supported on MacOS, but it may be useful to contribute to the documentation on MacOS) :: - wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh + wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-MacOSX-x86_64.sh -2. Install Conda +2. Install Mambaforge Linux :: - bash ./Miniconda3-latest-Linux-x86_64.sh + bash ./Mambaforge-Linux-x86_64.sh - MacOS + MacOS x86_64 :: - bash ./Miniconda3-latest-MacOSX-x86_64.sh + bash ./Mambaforge-MacOSX-x86_64.sh + + When you see: :: - - ``Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no] yes`` + by running conda init? [yes|no] + [no] >>> yes + + respond with ``yes`` so ``conda`` and ``mamba`` commands are available on + initializing a new bash terminal. 3. If you are working on a machine/network that intercepts SSL communications (such as acme1), you will get an SSL error unless you disable the SSL verification: @@ -112,45 +118,57 @@ acme1), you will get an SSL error unless you disable the SSL verification: conda config --set ssl_verify false binstar config --set ssl_verify False -4. Set the following: - - :: - - conda config --add channels conda-forge - conda config --set channel_priority strict - -5. Once conda is properly working, you can install the **(a) Latest Stable Release** or +4. Once conda and mamba are properly working, you can install the **(a) Latest Stable Release** or create a **(b) Development Environment**. (a) Latest Stable Release ========================= -Installation using conda +Installation using mamba ------------------------ First, make sure that you're using ``bash``. :: - $ bash + bash -You must have Anaconda installed as well. +You must have a conda base enviornment installed as well. See :ref:`"Installation in a Conda Environment" ` section above for installing conda. -Create a new Anaconda environment with ``zppy`` installed and activate it: :: - $ conda create -n zppy_env -c e3sm -c conda-forge zppy - $ source activate zppy_env +Create a new conda environment with ``zppy`` installed and activate it: :: -Or you can install ``zppy`` in an existing environment. :: + mamba create -n zppy_env zppy + conda activate zppy_env - $ conda install zppy -c e3sm -c conda-forge +Or (less recommended because of potential conflicts) you can install ``zppy`` +in an existing environment. :: + + mamba install zppy Updating -------- -If you **installed via Anaconda** (e.g., not through the unified environment), -you can update ``zppy`` by doing the following: :: +If you **installed into your own conda environment** (e.g., not through the +unified environment), you can update ``zppy`` by doing the following: :: + + mamba update zppy + +Troubleshooting +--------------- + +If you do not seem to have the ``mamba`` command, install ``mamba`` into your +conda ``base`` environment: :: + + conda install -y -n base mamba + +If you get errors that the ``zppy`` package cannot be found, it could be +that you have not added the conda-forge channel to your conda environment: :: + + conda config --add channels conda-forge + conda config --set channel_priority strict - conda update zppy -c e3sm -c conda-forge +If you installed Mambaforge as recommended above, neither of these issues +should arise. .. _dev-env: @@ -217,7 +235,7 @@ Furthermore, the dev environment includes quality assurance (QA) tools such as c :: - conda clean --all + mamba clean --all 4. Enter the fork's clone. @@ -232,7 +250,7 @@ Furthermore, the dev environment includes quality assurance (QA) tools such as c :: - conda env create -f conda/dev.yml + mamba env create -f conda/dev.yml conda activate zppy_dev 6. Install ``pre-commit``. From 6923d7cb5c914ec952515dc6c9033b5ab43637a7 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Mon, 22 May 2023 18:18:15 -0600 Subject: [PATCH 2/3] Point to Troubleshooting section on error --- docs/source/getting_started.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index fb16d704..ff76e683 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -127,6 +127,9 @@ create a **(b) Development Environment**. Installation using mamba ------------------------ +If you see error messages when running the following, see the +**Troubleshooting** section below. + First, make sure that you're using ``bash``. :: bash From 45aa26ea1ced651d41721bb94c5ec5fe7d7916f2 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Mon, 22 May 2023 18:33:31 -0600 Subject: [PATCH 3/3] Remove troubleshooting and instead include in install --- docs/source/getting_started.rst | 27 +++++++-------------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index ff76e683..5f854521 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -127,9 +127,6 @@ create a **(b) Development Environment**. Installation using mamba ------------------------ -If you see error messages when running the following, see the -**Troubleshooting** section below. - First, make sure that you're using ``bash``. :: bash @@ -138,6 +135,13 @@ You must have a conda base enviornment installed as well. See :ref:`"Installation in a Conda Environment" ` section above for installing conda. +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 ``zppy`` installed and activate it: :: mamba create -n zppy_env zppy @@ -156,23 +160,6 @@ unified environment), you can update ``zppy`` by doing the following: :: mamba update zppy -Troubleshooting ---------------- - -If you do not seem to have the ``mamba`` command, install ``mamba`` into your -conda ``base`` environment: :: - - conda install -y -n base mamba - -If you get errors that the ``zppy`` package cannot be found, it could be -that you have not added the conda-forge channel to your conda environment: :: - - conda config --add channels conda-forge - conda config --set channel_priority strict - -If you installed Mambaforge as recommended above, neither of these issues -should arise. - .. _dev-env: (b) Development Environment