From 6eab4a6af073877cc17e93565b4ce33740aed56b Mon Sep 17 00:00:00 2001 From: zacharyburnett Date: Wed, 5 Jun 2024 11:10:59 -0400 Subject: [PATCH 1/6] set examples to default to mamba --- docs/source/developer_notes.rst | 13 +++-- docs/source/faq.rst | 24 +++++++-- docs/source/getting_started.rst | 88 ++++++++++++++++++++------------- 3 files changed, 82 insertions(+), 43 deletions(-) diff --git a/docs/source/developer_notes.rst b/docs/source/developer_notes.rst index 012e84b..a55bcf7 100644 --- a/docs/source/developer_notes.rst +++ b/docs/source/developer_notes.rst @@ -17,17 +17,24 @@ Developer Notes To build an environment from this unpinned environment definition, you may run the following: +.. tab:: mamba + + .. code-block:: shell + + mamba env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml + .. tab:: conda .. code-block:: shell - conda env create -n stenv -f https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml + conda env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba env create -n stenv -f https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml + curl -L https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml -o ~/Downloads/stenv.yaml + micromamba env create --name stenv --file ~/Downloads/stenv.yaml .. _adding_a_package_to_stenv: diff --git a/docs/source/faq.rst b/docs/source/faq.rst index b49f5d9..b82cdb7 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -8,17 +8,24 @@ Frequently Asked Questions You can use the environment definition YAML file (:ref:`environment_yaml`) in the root of the repository: +.. tab:: mamba + + .. code-block:: shell + + mamba env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml + .. tab:: conda .. code-block:: shell - conda env create -n stenv -f https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml + conda env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba env create -n stenv -f https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml + curl -L https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml -o ~/Downloads/stenv.yaml + micromamba env create --name stenv --file ~/Downloads/stenv.yaml This environment is unpinned, meaning it may take some time to resolve dependency versions. Additionally, the resulting package versions may not have been tested for your platform. @@ -35,6 +42,13 @@ some packages are not supported and / or deprecated, and some are deemed too nic To install a package in your local environment, you can use ``pip install`` while the environment is activated: +.. tab:: mamba + + .. code-block:: shell + + mamba activate stenv + pip install + .. tab:: conda .. code-block:: shell @@ -42,11 +56,11 @@ To install a package in your local environment, you can use ``pip install`` whil conda activate stenv pip install -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba activate stenv + micromamba activate stenv pip install To request that a new package be added to ``stenv`` (:ref:`environment_yaml`) for all users, see :ref:`adding_a_package_to_stenv`. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 1c8a3a6..19dd564 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -43,17 +43,23 @@ well as hundreds of useful tools, libraries, and utilities by default. Remember to run ``conda init`` when installing. This is required in order to set up your shell to ``activate`` and ``deactivate`` environments. + .. tab:: mamba + + .. code-block:: shell + + mamba init + .. tab:: conda .. code-block:: shell conda init - .. tab:: mamba + .. tab:: micromamba .. code-block:: shell - mamba init + micromamba init .. _choose_release: @@ -89,40 +95,28 @@ newest (highest-numbered) Python version available. Therefore, I recommend using a more descriptive name than ``stenv`` for your environment; for example, use something like ``stenv-py3.11-2023.01.01`` (changed as needed to match the version you chose). -.. tab:: create environment from URL - - Right-click (or control-click on macOS) on the link to the release file and choose ``Copy Link`` (or - ``Copy Link Address``). Then, run the following command in a terminal, replacing ```` with the URL you copied in the previous - step: - - .. tab:: conda - - .. code-block:: shell - - conda env create --name stenv --file - - .. tab:: mamba - - .. code-block:: shell +Right-click (or control-click on macOS) on the link to the release file and choose ``Copy Link`` (or +``Copy Link Address``). Then, run the following command in a terminal, replacing ```` with the URL you copied in the previous +step: - mamba env create --name stenv --file +.. tab:: mamba -.. tab:: create environment from downloaded file + .. code-block:: shell - Download the release file you chose. Then, run the following command in a terminal, replacing - ``~/Downloads/stenv-pyXX-YY.MM.DD.yaml`` with the path to the file you downloaded: + mamba env create --name stenv --file - .. tab:: conda +.. tab:: conda - .. code-block:: shell + .. code-block:: shell - conda env create --name stenv --file ~/Downloads/stenv-pyXX-YY.MM.DD.yaml + conda env create --name stenv --file - .. tab:: mamba +.. tab:: micromamba - .. code-block:: shell + .. code-block:: shell - mamba env create --name stenv --file ~/Downloads/stenv-pyXX-YY.MM.DD.yaml + curl -L -o ~/Downloads/stenv.yaml + micromamba env create --name stenv --file ~/Downloads/stenv.yaml .. note:: @@ -146,17 +140,23 @@ In order to access the packages in ``stenv``, you must first ``activate`` the en .. important:: If you chose another name when creating the environment, use that here instead. +.. tab:: mamba + + .. code-block:: shell + + mamba activate stenv + .. tab:: conda .. code-block:: shell conda activate stenv -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba activate stenv + micromamba activate stenv Activating a Conda environment changes which Python interpreter and packages are in use for that session (i.e. terminal window). Now, if you try to ``import jwst``: @@ -171,32 +171,44 @@ Every time you open a new terminal window, you will need to activate the environ .. note:: You can show installed packages available within a Conda environment with ``conda list``: + .. tab:: mamba + + .. code-block:: shell + + mamba list + .. tab:: conda .. code-block:: shell conda list - .. tab:: mamba + .. tab:: micromamba .. code-block:: shell - mamba list + micromamba list To ``deactivate`` an environment and return your shell to normal, close your terminal window or run ``conda deactivate``: +.. tab:: mamba + + .. code-block:: shell + + mamba deactivate + .. tab:: conda .. code-block:: shell conda deactivate -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba deactivate + micromamba deactivate Deleting an environment ======================= @@ -206,15 +218,21 @@ To delete an environment with all of its packages, run ``conda env remove --name .. important:: If you chose another name when creating the environment, use that here instead. +.. tab:: mamba + + .. code-block:: shell + + mamba env remove --name stenv + .. tab:: conda .. code-block:: shell conda env remove --name stenv -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba env remove --name stenv + micromamba env remove --name stenv From 680534afe67f837ad28f109bdf4fbad1a0d48ef4 Mon Sep 17 00:00:00 2001 From: zacharyburnett Date: Wed, 5 Jun 2024 11:42:31 -0400 Subject: [PATCH 2/6] set micromamba as default and recommended --- docs/source/developer_notes.rst | 16 ++-- docs/source/faq.rst | 26 +++---- docs/source/getting_started.rst | 129 ++++++++++++++++++-------------- 3 files changed, 95 insertions(+), 76 deletions(-) diff --git a/docs/source/developer_notes.rst b/docs/source/developer_notes.rst index a55bcf7..78f4e77 100644 --- a/docs/source/developer_notes.rst +++ b/docs/source/developer_notes.rst @@ -15,26 +15,26 @@ Developer Notes .. literalinclude:: ../../environment.yaml :language: yaml -To build an environment from this unpinned environment definition, you may run the following: +To build an environment from this unpinned environment definition, run the following: -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml + curl -L https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml -o ~/Downloads/stenv.yaml + micromamba env create --name stenv --file ~/Downloads/stenv.yaml -.. tab:: conda +.. tab:: mamba .. code-block:: shell - conda env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml + mamba env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml -.. tab:: micromamba +.. tab:: conda .. code-block:: shell - curl -L https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml -o ~/Downloads/stenv.yaml - micromamba env create --name stenv --file ~/Downloads/stenv.yaml + conda env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml .. _adding_a_package_to_stenv: diff --git a/docs/source/faq.rst b/docs/source/faq.rst index b82cdb7..4a505f5 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -8,24 +8,24 @@ Frequently Asked Questions You can use the environment definition YAML file (:ref:`environment_yaml`) in the root of the repository: -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml + curl -L https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml -o ~/Downloads/stenv.yaml + micromamba env create --name stenv --file ~/Downloads/stenv.yaml -.. tab:: conda +.. tab:: mamba .. code-block:: shell - conda env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml + mamba env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml -.. tab:: micromamba +.. tab:: conda .. code-block:: shell - curl -L https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml -o ~/Downloads/stenv.yaml - micromamba env create --name stenv --file ~/Downloads/stenv.yaml + conda env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml This environment is unpinned, meaning it may take some time to resolve dependency versions. Additionally, the resulting package versions may not have been tested for your platform. @@ -42,25 +42,25 @@ some packages are not supported and / or deprecated, and some are deemed too nic To install a package in your local environment, you can use ``pip install`` while the environment is activated: -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba activate stenv + micromamba activate stenv pip install -.. tab:: conda +.. tab:: mamba .. code-block:: shell - conda activate stenv + mamba activate stenv pip install -.. tab:: micromamba +.. tab:: conda .. code-block:: shell - micromamba activate stenv + conda activate stenv pip install To request that a new package be added to ``stenv`` (:ref:`environment_yaml`) for all users, see :ref:`adding_a_package_to_stenv`. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 19dd564..2204685 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -20,46 +20,66 @@ Installation Install Conda ------------- -A Conda distribution provides the ``conda`` command, which lets you create, manage, and activate new -environments. Try running the ``conda`` command in your terminal. If you get ``conda: command not found`` -(or similar), you will need to install a conda distribution. If you already have a ``conda`` command in -your terminal, you can skip to the next step. +A Conda distribution provides the ``micromamba`` / ``mamba`` / ``conda`` command, which lets you create, manage, and switch to +(activate) environments. Try running ``micromamba``, ``mamba``, or ``conda`` in your terminal. If you get ``command not found`` +(or similar), see below to install. -The easiest option is to install -`Miniconda `_, which is -full-featured but installs a minimal set of default packages initially. We will install more packages later -on. +``mamba`` is a rewrite of ``conda`` that is much faster at resolving dependencies with near-parity of commands. +``micromamba`` is ``mamba`` packaged into a single binary, which makes installation and maintenance much easier. +For these reasons, I recommended you use ``micromamba``. -Alternatives include `Miniforge `_, which includes the -``mamba`` command (a much faster drop-in replacement for ``conda`` with all the same functionality) and -`Anaconda `_ which provides a full-featured base environment as -well as hundreds of useful tools, libraries, and utilities by default. +.. tab:: micromamba -.. note:: - The below instructions will work for any of the distributions, though users with ``mamba`` installed - will notice a speedup if they substitute ``mamba`` for ``conda`` where it appears in commands. + Run the following in your terminal to install ``micromamba``: -.. important:: - Remember to run ``conda init`` when installing. This is required in order to set up your shell to - ``activate`` and ``deactivate`` environments. + .. code-block:: shell - .. tab:: mamba + "${SHELL}" <(curl -L micro.mamba.pm/install.sh) + + On macOS, you can alternatively install ``micromamba`` from `Homebrew `_: + + .. code-block:: shell + + brew install micromamba + + You may also follow `these installation instructions `_. + +.. tab:: mamba + + Follow + `these instructions to install Miniforge `_, + which includes the ``mamba`` command in its base environment. + + .. important:: + Remember to run ``mamba init`` after installing. This is required in order to set up your shell to + ``activate`` and ``deactivate`` environments. .. code-block:: shell mamba init - .. tab:: conda +.. tab:: conda - .. code-block:: shell + .. caution:: + The Anaconda organization has + `updated their terms of service `_ + to indicate that any usage of their services requires a paid license, if used by an organization of + more than 200 users. This includes pulling packages from the Anaconda ``defaults`` channels, as well as installing + ``conda`` itself. - conda init + We recommend that you use ``mamba`` and pull packages from the ``conda-forge`` channel, instead of using ``conda`` + and the ``defaults`` channels. - .. tab:: micromamba + Follow `these instructions to install Miniconda `_ + which includes the ``conda`` command in its base environment. + + .. important:: + Remember to run ``conda init`` after installing. This is required in order to set up your shell to + ``activate`` and ``deactivate`` environments. .. code-block:: shell - micromamba init + conda init .. _choose_release: @@ -99,25 +119,24 @@ Right-click (or control-click on macOS) on the link to the release file and choo ``Copy Link Address``). Then, run the following command in a terminal, replacing ```` with the URL you copied in the previous step: -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba env create --name stenv --file + curl -L -o ~/Downloads/stenv.yaml + micromamba env create --name stenv --file ~/Downloads/stenv.yaml -.. tab:: conda +.. tab:: mamba .. code-block:: shell - conda env create --name stenv --file + mamba env create --name stenv --file -.. tab:: micromamba +.. tab:: conda .. code-block:: shell - curl -L -o ~/Downloads/stenv.yaml - micromamba env create --name stenv --file ~/Downloads/stenv.yaml - + conda env create --name stenv --file .. note:: If the build does not succeed on your system, please refer to :ref:`build_fails` @@ -140,23 +159,23 @@ In order to access the packages in ``stenv``, you must first ``activate`` the en .. important:: If you chose another name when creating the environment, use that here instead. -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba activate stenv + micromamba activate stenv -.. tab:: conda +.. tab:: mamba .. code-block:: shell - conda activate stenv + mamba activate stenv -.. tab:: micromamba +.. tab:: conda .. code-block:: shell - micromamba activate stenv + conda activate stenv Activating a Conda environment changes which Python interpreter and packages are in use for that session (i.e. terminal window). Now, if you try to ``import jwst``: @@ -171,6 +190,12 @@ Every time you open a new terminal window, you will need to activate the environ .. note:: You can show installed packages available within a Conda environment with ``conda list``: + .. tab:: micromamba + + .. code-block:: shell + + micromamba list + .. tab:: mamba .. code-block:: shell @@ -183,14 +208,14 @@ Every time you open a new terminal window, you will need to activate the environ conda list - .. tab:: micromamba +To ``deactivate`` an environment and return your shell to normal, close your terminal window or run +``conda deactivate``: - .. code-block:: shell +.. tab:: micromamba - micromamba list + .. code-block:: shell -To ``deactivate`` an environment and return your shell to normal, close your terminal window or run -``conda deactivate``: + micromamba deactivate .. tab:: mamba @@ -204,12 +229,6 @@ To ``deactivate`` an environment and return your shell to normal, close your ter conda deactivate -.. tab:: micromamba - - .. code-block:: shell - - micromamba deactivate - Deleting an environment ======================= @@ -218,21 +237,21 @@ To delete an environment with all of its packages, run ``conda env remove --name .. important:: If you chose another name when creating the environment, use that here instead. -.. tab:: mamba +.. tab:: micromamba .. code-block:: shell - mamba env remove --name stenv + micromamba env remove --name stenv -.. tab:: conda +.. tab:: mamba .. code-block:: shell - conda env remove --name stenv + mamba env remove --name stenv -.. tab:: micromamba +.. tab:: conda .. code-block:: shell - micromamba env remove --name stenv + conda env remove --name stenv From 2ae7729e792fe43351b4faabbab46a9ee885b88a Mon Sep 17 00:00:00 2001 From: zacharyburnett Date: Wed, 5 Jun 2024 11:57:32 -0400 Subject: [PATCH 3/6] change instructions to download file --- docs/source/getting_started.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 2204685..11e8c49 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -115,28 +115,26 @@ newest (highest-numbered) Python version available. Therefore, I recommend using a more descriptive name than ``stenv`` for your environment; for example, use something like ``stenv-py3.11-2023.01.01`` (changed as needed to match the version you chose). -Right-click (or control-click on macOS) on the link to the release file and choose ``Copy Link`` (or -``Copy Link Address``). Then, run the following command in a terminal, replacing ```` with the URL you copied in the previous -step: +Download the file corresponding to your platform and desired Python version, then run the following command +in a terminal using the file you downloaded (in this example ``stenv-Linux-py3.10-2023.02.16.yaml``): .. tab:: micromamba .. code-block:: shell - curl -L -o ~/Downloads/stenv.yaml - micromamba env create --name stenv --file ~/Downloads/stenv.yaml + micromamba env create --name stenv --file ~/Downloads/stenv-Linux-py3.10-2023.02.16.yaml .. tab:: mamba .. code-block:: shell - mamba env create --name stenv --file + mamba env create --name stenv --file ~/Downloads/stenv-Linux-py3.10-2023.02.16.yaml .. tab:: conda .. code-block:: shell - conda env create --name stenv --file + conda env create --name stenv --file ~/Downloads/stenv-Linux-py3.10-2023.02.16.yaml .. note:: If the build does not succeed on your system, please refer to :ref:`build_fails` From e342d2a377ce2fd3221c3cee77bc8d0de5eec82c Mon Sep 17 00:00:00 2001 From: zacharyburnett Date: Wed, 5 Jun 2024 12:01:58 -0400 Subject: [PATCH 4/6] minor fix for homebrew line --- docs/source/getting_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 11e8c49..a7845ca 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -36,7 +36,7 @@ For these reasons, I recommended you use ``micromamba``. "${SHELL}" <(curl -L micro.mamba.pm/install.sh) - On macOS, you can alternatively install ``micromamba`` from `Homebrew `_: + On macOS, you can alternatively install ``micromamba`` using the `Homebrew package manager `_, if you have it installed: .. code-block:: shell From 62aff9642f41a027407029fd66e82b90abb1b252 Mon Sep 17 00:00:00 2001 From: zacharyburnett Date: Wed, 5 Jun 2024 12:05:22 -0400 Subject: [PATCH 5/6] update examples --- docs/source/getting_started.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index a7845ca..b9a63c9 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -181,9 +181,10 @@ Activating a Conda environment changes which Python interpreter and packages are .. code-block:: shell (stenv) $ python -c 'import jwst; print("ok")' + ok Every time you open a new terminal window, you will need to activate the environment before you can use -``stenv`` software. +software included in ``stenv``. .. note:: You can show installed packages available within a Conda environment with ``conda list``: From cb41c49690be13143e29a40c14d8e7e4b7855011 Mon Sep 17 00:00:00 2001 From: zacharyburnett Date: Fri, 28 Jun 2024 10:24:13 -0400 Subject: [PATCH 6/6] add micromamba shell init to installation instructions --- docs/source/getting_started.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index b9a63c9..3224c1d 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -41,6 +41,7 @@ For these reasons, I recommended you use ``micromamba``. .. code-block:: shell brew install micromamba + micromamba shell init You may also follow `these installation instructions `_.