diff --git a/doc/install.rst b/doc/install.rst index 0b8c32f3e82..86bc520810c 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -14,15 +14,44 @@ Installing `__. +Quickstart +---------- + +The fastest way to install PyGMT is with the +`conda `__ +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:: + + conda create --name pygmt --channel conda-forge pygmt + +To activate the virtual environment, you can do:: + + conda activate pygmt + +After this, check that everything works by running the following in a Python +interpreter (e.g. in a Jupyter notebook):: + + import pygmt + pygmt.show_versions() + +You are now ready to make you first figure! +Start by looking at the tutorials on our sidebar, good luck! + +.. note:: + + The sections below provide more detailed, step by step instructions to + installing and testing PyGMT for those who may have a slightly different + setup. + Which Python? ------------- -You'll need **Python 3.7 or greater** to run PyGMT. Old Python versions may -work, but there is no guarantee that PyGMT will work as expected with old versions. +PyGMT is tested to run on **Python 3.7 or greater**. Older Python versions may +work, but there is no guarantee that PyGMT will behave as expected. -We recommend using the `Anaconda `__ Python -distribution to ensure you have all dependencies installed and the ``conda`` -package manager available. +We recommend using the `Anaconda `__ +Python distribution to ensure you have all dependencies installed and the +``conda`` package manager available. Installing Anaconda does not require administrative rights to your computer and doesn't interfere with any other Python installations in your system. @@ -30,18 +59,19 @@ doesn't interfere with any other Python installations in your system. Which GMT? ---------- -PyGMT requires Generic Mapping Tools (GMT) version 6 as a minimum, which is the latest -released version that can be found at +PyGMT requires Generic Mapping Tools (GMT) version 6 as a minimum, which is the +latest released version that can be found at the `GMT official site `__. -We need the latest GMT (>=6.1.1) since there are many changes being made to GMT itself in -response to the development of PyGMT, mainly the new +We need the latest GMT (>=6.1.1) since there are many changes being made to GMT +itself in response to the development of PyGMT, mainly the new `modern execution mode `__. -Compiled conda packages of GMT for Linux, macOS and Windows are provided through -`conda-forge `__. +Compiled conda packages of GMT for Linux, macOS and Windows are provided +through `conda-forge `__. Advanced users can also `build GMT from source `__ -instead, which is not so recommended but we would love to get feedback from anyone who tries. +instead, which is not so recommended but we would love to get feedback from +anyone who tries. We recommend following the instructions further on to install GMT 6. @@ -58,61 +88,97 @@ PyGMT requires the following libraries: The following are optional (but recommended) dependencies: -* `IPython `__: For embedding the figures in Jupyter notebooks. +* `IPython `__: For embedding the figures in Jupyter +notebooks. 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 using the ``conda`` package manager. +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. We recommend working in an isolated `conda environment `__ -to avoid issues with competing versions of its dependencies. +to avoid issues with conflicting versions of dependencies. First, we must configure conda to get packages from the `conda-forge channel `__:: conda config --prepend channels conda-forge -Now we can create a new conda environment with Python and all our dependencies installed -(we'll call it ``pygmt`` but you can change it to whatever you want):: +Now we can create a new conda environment with Python and all our dependencies +installed (we'll call it ``pygmt`` but feel free to change it to whatever you +want):: conda create --name pygmt python=3.9 pip numpy pandas xarray netcdf4 packaging gmt -Activate the environment by running:: +Activate the environment by running the following (**do not forget this step!**):: conda activate pygmt -From now on, all commands will take place inside the conda virtual environment and won't -affect your default installation. +From now on, all commands will take place inside the conda virtual environment +called 'pygmt' and won't affect your default 'base' installation. Installing PyGMT ---------------- -Now that you have GMT installed and your conda environment activated, you can -use ``conda`` to install the latest release of PyGMT from `conda-forge `__:: +Now that you have GMT installed and your conda virtual environment activated, +you can install PyGMT using any of the following methods: + +Using conda (recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This installs the latest stable release of PyGMT from +`conda-forge `__:: conda install pygmt -or use ``pip`` to install from `PyPI `__:: +Using pip +~~~~~~~~~ + +This installs the latest stable release from +`PyPI `__:: pip install pygmt -Alternatively, you can install the development version from the GitHub repository:: +Alternatively, you can install the latest development version from +`TestPyPI `__:: + + pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt - pip install https://github.com/GenericMappingTools/pygmt/archive/master.zip +or from PyGMT's `GitHub repository `__ +(slower as it downloads the whole archive):: -This will allow you to use the ``pygmt`` library from Python. + pip install git+https://github.com/GenericMappingTools/pygmt.git#egg=pygmt + +Any of the above methods (conda/pip) should allow you to use the ``pygmt`` +library from Python. Testing your install -------------------- +Quick check +~~~~~~~~~~~ + +To ensure that PyGMT and its depedencies are installed correctly, run the +following in your Python interpreter:: + + import pygmt + pygmt.show_versions() + +Or run this in the command line:: + + python -c "import pygmt; pygmt.show_versions()" + + +Full test (optional) +~~~~~~~~~~~~~~~~~~~~ + PyGMT ships with a full test suite. -You can run our tests after you install it but you will need a few extra dependencies as -well (be sure to have your conda env activated):: +You can run our tests after you install it but you will need a few extra +dependencies as well (be sure to have your conda environment activated):: conda install pytest pytest-mpl ipython @@ -132,9 +198,9 @@ This can happen if you have multiple versions of GMT installed. You can tell PyGMT exactly where to look for ``libgmt`` by setting the ``GMT_LIBRARY_PATH`` environment variable. -This should be set to the directory where ``libgmt.so``, ``libgmt.dylib`` or ``gmt.dll`` -can be found for Linux, macOS and Windows respectively. -e.g. in a terminal run:: +This should be set to the directory where ``libgmt.so``, ``libgmt.dylib`` or +``gmt.dll`` can be found for Linux, macOS and Windows respectively. +e.g. on a command line, run:: # Linux/macOS export GMT_LIBRARY_PATH=$HOME/anaconda3/envs/pygmt/lib diff --git a/setup.py b/setup.py index cfac8b7fadb..45685e36ada 100644 --- a/setup.py +++ b/setup.py @@ -36,7 +36,7 @@ INSTALL_REQUIRES = ["numpy", "pandas", "xarray", "netCDF4", "packaging"] # Configuration for setuptools-scm SETUP_REQUIRES = ["setuptools_scm"] -USE_SCM_VERSION = {"local_scheme": "node-and-date"} +USE_SCM_VERSION = {"local_scheme": "node-and-date", "fallback_version": "unknown"} if __name__ == "__main__": setup(