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

Recommend Mambaforge and mamba in the installation and contributing guides #2385

Merged
merged 3 commits into from
Mar 3, 2023
Merged

Recommend Mambaforge and mamba in the installation and contributing guides #2385

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ec72e65
Put mamba as the default option
seisman Feb 27, 2023
394ada3
Recommend mambaforge
seisman Feb 27, 2023
a36275d
Recommend mambaforge and mamba in the contributing guides
seisman Feb 27, 2023
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
8 changes: 4 additions & 4 deletions doc/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,8 +186,8 @@ These steps for setting up your environment are necessary for
[contributing code](contributing.md#contributing-code). A local PyGMT development environment
is not needed for [editing the documentation on GitHub](contributing.md#editing-the-documentation-on-github).

We highly recommend using [Anaconda](https://www.anaconda.com/download/) and the `conda`
package manager to install and manage your Python packages.
We highly recommend using [Mambaforge](https://github.com/conda-forge/miniforge#mambaforge/)
and the `mamba` package manager to install and manage your Python packages.
It will make your life a lot easier!

The repository includes a conda environment file `environment.yml` with the
Expand All @@ -208,14 +208,14 @@ Run the following on the base of the repository to create a new conda
environment from the `environment.yml` file:

```bash
conda env create --file environment.yml
mamba env create --file environment.yml
```

Before building and testing the project, you have to activate the environment
(you'll need to do this every time you start a new terminal):

```bash
conda activate pygmt
mamba activate pygmt
```

We have a [`Makefile`](https://github.com/GenericMappingTools/pygmt/blob/main/Makefile)
Expand Down
86 changes: 43 additions & 43 deletions doc/install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,37 +7,30 @@ Quickstart
----------

The fastest way to install PyGMT is with the
`mamba <https://mamba.readthedocs.io/en/latest/>`__ or
`conda <https://docs.conda.io/projects/conda/en/latest/user-guide/index.html>`__
or `mamba <https://mamba.readthedocs.io/en/latest/>`__
package manager which takes care of setting up a virtual environment, as well
as the installation of GMT and all the dependencies PyGMT depends on:

.. tab-set::

.. tab-item:: conda
:sync: conda

::

conda create --name pygmt --channel conda-forge pygmt

.. tab-item:: mamba
:sync: mamba

::

mamba create --name pygmt --channel conda-forge pygmt

To activate the virtual environment, you can do:

.. tab-set::

.. tab-item:: conda
:sync: conda

::

conda activate pygmt
conda create --name pygmt --channel conda-forge pygmt

To activate the virtual environment, you can do:

.. tab-set::

.. tab-item:: mamba
:sync: mamba
Expand All @@ -46,6 +39,13 @@ To activate the virtual environment, you can do:

mamba activate pygmt

.. tab-item:: conda
:sync: conda

::

conda activate pygmt

After this, check that everything works by running the following in a Python
interpreter (e.g., in a Jupyter notebook)::

Expand All @@ -66,11 +66,11 @@ Which Python?

PyGMT is tested to run on **Python 3.8 or greater**.

We recommend using the `Anaconda <https://www.anaconda.com/distribution>`__
We recommend using the `Mambaforge <https://github.com/conda-forge/miniforge#mambaforge>`__
Python distribution to ensure you have all dependencies installed and the
`conda <https://docs.conda.io/projects/conda/en/latest/>`__
package manager is available. Installing Anaconda does not require administrative
rights to your computer and doesn't interfere with any other Python
`mamba <https://mamba.readthedocs.io/en/stable/user_guide/mamba.html>`__
package manager in the base environment. Installing Mambaforge does not require
administrative rights to your computer and doesn't interfere with any other Python
installations on your system.


Expand Down Expand Up @@ -112,7 +112,7 @@ Installing GMT and other dependencies
-------------------------------------

Before installing PyGMT, we must install GMT itself along with the other
dependencies. The easiest way to do this is via the ``conda`` package manager.
dependencies. The easiest way to do this is via the ``mamba`` or ``conda`` package manager.
We recommend working in an isolated
`conda environment <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`__
to avoid issues with conflicting versions of dependencies.
Expand All @@ -128,30 +128,23 @@ want):

.. tab-set::
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At line 120, we have:

First, we must configure conda to get packages from the conda-forge channel

conda config --prepend channels conda-forge

This line is not necessary if users use Mambaforge + mamba, but are required if users use conda or install mamba in other ways.

I'm unsure if we should remove these lines and always add the --channel conda-forge option to conda/mamba commands.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe mention that this step is not needed if Mambaforge is used? Or we could just leave it, since running this command under Mambaforge doesn't hurt actually.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or we could just leave it, since running this command under Mambaforge doesn't hurt actually.

Sounds good to me.


.. tab-item:: conda
:sync: conda

::

conda create --name pygmt python=3.9 numpy pandas xarray netcdf4 packaging gmt

.. tab-item:: mamba
:sync: mamba

::

mamba create --name pygmt python=3.9 numpy pandas xarray netcdf4 packaging gmt

Activate the environment by running the following (**do not forget this step!**):

.. tab-set::

.. tab-item:: conda
:sync: conda

::

conda activate pygmt
conda create --name pygmt python=3.9 numpy pandas xarray netcdf4 packaging gmt

Activate the environment by running the following (**do not forget this step!**):

.. tab-set::

.. tab-item:: mamba
:sync: mamba
Expand All @@ -160,6 +153,13 @@ Activate the environment by running the following (**do not forget this step!**)

mamba activate pygmt

.. tab-item:: conda
:sync: conda

::

conda activate pygmt

From now on, all commands will take place inside the conda virtual environment
called ``pygmt`` and won't affect your default ``base`` installation.

Expand All @@ -178,30 +178,23 @@ This installs the latest stable release of PyGMT from

.. tab-set::

.. tab-item:: conda
:sync: conda

::

conda install pygmt

.. tab-item:: mamba
:sync: mamba

::

mamba install pygmt

This upgrades the installed PyGMT version to be the latest stable release:

.. tab-set::

.. tab-item:: conda
:sync: conda

::

conda update pygmt
conda install pygmt

This upgrades the installed PyGMT version to be the latest stable release:

.. tab-set::

.. tab-item:: mamba
:sync: mamba
Expand All @@ -210,6 +203,13 @@ This upgrades the installed PyGMT version to be the latest stable release:

mamba update pygmt

.. tab-item:: conda
:sync: conda

::

conda update pygmt

Using pip
~~~~~~~~~

Expand Down Expand Up @@ -272,7 +272,7 @@ For Windows, add the ``GMT_LIBRARY_PATH`` environment variable following these
`instructions <https://www.wikihow.com/Create-an-Environment-Variable-in-Windows-10>`__
and set its value to a path like::

C:\Users\USERNAME\Anaconda3\envs\pygmt\Library\bin\
C:\Users\USERNAME\Mambaforge\envs\pygmt\Library\bin\

Notes for Jupyter users
-----------------------
Expand Down