Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update docs to indicate that micromamba and mamba are recommended over conda #153

Merged
merged 6 commits into from
Jul 1, 2024
Merged

update docs to indicate that micromamba and mamba are recommended over conda #153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6eab4a6
set examples to default to mamba
zacharyburnett Jun 5, 2024
680534a
set micromamba as default and recommended
zacharyburnett Jun 5, 2024
2ae7729
change instructions to download file
zacharyburnett Jun 5, 2024
e342d2a
minor fix for homebrew line
zacharyburnett Jun 5, 2024
62aff96
update examples
zacharyburnett Jun 5, 2024
cb41c49
add micromamba shell init to installation instructions
zacharyburnett Jun 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions docs/source/developer_notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +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:: conda
.. tab:: micromamba

.. code-block:: shell

conda 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

.. tab:: mamba

.. code-block:: shell

mamba env create -n stenv -f 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:: conda

.. code-block:: shell

conda env create --name stenv --file https://raw.githubusercontent.com/spacetelescope/stenv/main/environment.yaml

.. _adding_a_package_to_stenv:

Expand Down
24 changes: 19 additions & 5 deletions docs/source/faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:: conda
.. tab:: micromamba

.. code-block:: shell

conda 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

.. tab:: mamba

.. code-block:: shell

mamba env create -n stenv -f 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:: conda

.. code-block:: shell

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.
Expand All @@ -35,11 +42,11 @@ 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:: conda
.. tab:: micromamba

.. code-block:: shell

conda activate stenv
micromamba activate stenv
pip install <package_name>

.. tab:: mamba
Expand All @@ -49,6 +56,13 @@ To install a package in your local environment, you can use ``pip install`` whil
mamba activate stenv
pip install <package_name>

.. tab:: conda

.. code-block:: shell

conda activate stenv
pip install <package_name>

To request that a new package be added to ``stenv`` (:ref:`environment_yaml`) for all users, see :ref:`adding_a_package_to_stenv`.

What about Astroconda?
Expand Down
151 changes: 94 additions & 57 deletions docs/source/getting_started.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,41 +20,68 @@ 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 <https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>`_, 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 <https://github.com/conda-forge/miniforge#miniforge3>`_, which includes the
``mamba`` command (a much faster drop-in replacement for ``conda`` with all the same functionality) and
`Anaconda <https://www.anaconda.com/distribution/>`_ 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:: conda
"${SHELL}" <(curl -L micro.mamba.pm/install.sh)

.. code-block:: shell
On macOS, you can alternatively install ``micromamba`` using the `Homebrew package manager <https://brew.sh/>`_, if you have it installed:

conda init
.. code-block:: shell

.. tab:: mamba
brew install micromamba
micromamba shell init

You may also follow `these installation instructions <https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html>`_.

.. tab:: mamba

Follow
`these instructions to install Miniforge <https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html>`_,
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

.. caution::
The Anaconda organization has
`updated their terms of service <https://legal.anaconda.com/policies/en/#:~:text=2.1%20Organizational%20Use.%C2%A0>`_
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.

We recommend that you use ``mamba`` and pull packages from the ``conda-forge`` channel, instead of using ``conda``
and the ``defaults`` channels.

Follow `these instructions to install Miniconda <https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>`_
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

conda init

.. _choose_release:

Choose an ``stenv`` release
Expand Down Expand Up @@ -89,41 +116,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).

.. 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 ``<URL>`` with the URL you copied in the previous
step:

.. tab:: conda

.. code-block:: shell

conda env create --name stenv --file <URL>
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:: mamba

.. code-block:: shell

mamba env create --name stenv --file <URL>

.. tab:: create environment from downloaded file
.. tab:: micromamba

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:
.. code-block:: shell

.. tab:: conda
micromamba env create --name stenv --file ~/Downloads/stenv-Linux-py3.10-2023.02.16.yaml

.. code-block:: shell
.. tab:: mamba

conda env create --name stenv --file ~/Downloads/stenv-pyXX-YY.MM.DD.yaml
.. code-block:: shell

.. tab:: mamba
mamba env create --name stenv --file ~/Downloads/stenv-Linux-py3.10-2023.02.16.yaml

.. code-block:: shell
.. tab:: conda

mamba env create --name stenv --file ~/Downloads/stenv-pyXX-YY.MM.DD.yaml
.. code-block:: shell

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`
Expand All @@ -146,58 +158,77 @@ 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:: conda
.. tab:: micromamba

.. code-block:: shell

conda activate stenv
micromamba activate stenv

.. tab:: mamba

.. code-block:: shell

mamba activate stenv

.. tab:: conda

.. code-block:: shell

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``:

.. 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``:

.. tab:: conda
.. tab:: micromamba

.. code-block:: shell

conda list
micromamba list

.. tab:: mamba

.. code-block:: shell

mamba list

.. tab:: conda

.. code-block:: shell

conda list

To ``deactivate`` an environment and return your shell to normal, close your terminal window or run
``conda deactivate``:

.. tab:: conda
.. tab:: micromamba

.. code-block:: shell

conda deactivate
micromamba deactivate

.. tab:: mamba

.. code-block:: shell

mamba deactivate

.. tab:: conda

.. code-block:: shell

conda deactivate

Deleting an environment
=======================

Expand All @@ -206,15 +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:: conda
.. tab:: micromamba

.. code-block:: shell

conda env remove --name stenv
micromamba env remove --name stenv

.. tab:: mamba

.. code-block:: shell

mamba env remove --name stenv

.. tab:: conda

.. code-block:: shell

conda env remove --name stenv

Loading