Merge branch 'master' into data_version_control

.github/workflows/cache_data.yaml

@@ -12,6 +12,9 @@ jobs:
   gmt_cache:
     name: Cache GMT artifacts
     runs-on: macOS-latest
+    defaults:
+      run:
+        shell: bash -l {0}
 
     steps:
       # Setup Miniconda
@@ -23,21 +26,19 @@ jobs:
 
       # Install GMT
       - name: Install GMT
-        shell: bash -l {0}
         run: conda install -c conda-forge gmt=6.1.1
 
       # Download remote files
       - name: Download remote data
-        shell: bash -l {0}
         run: |
           gmt which -Ga @earth_relief_10m_p @earth_relief_10m_g \
                         @earth_relief_30m_p @earth_relief_30m_g \
                         @earth_relief_01d_p @earth_relief_01d_g \
                         @earth_relief_05m_p @earth_relief_05m_g
           # Download one tile of the 03s srtm data.
           # @N35E135.earth_relief_03s_g.nc is for internal use only.
-          # The naming scheme may change. 
-          # DO NOT USE IT IN SCRIPTS.         
+          # The naming scheme may change.
+          # DO NOT USE IT IN SCRIPTS.
           gmt which -Ga @N35E135.earth_relief_03s_g.nc
           gmt which -Ga @ridge.txt @Table_5_11.txt @test.dat.nc \
                         @tut_bathy.nc @tut_quakes.ngdc @tut_ship.xyz \

.github/workflows/ci_tests.yaml

@@ -45,6 +45,9 @@ jobs:
           - os: ubuntu-latest
             python-version: 3.8
             isDraft: true
+    defaults:
+      run:
+        shell: bash -l {0}
 
     # environmental variables used in coverage
     env:
@@ -76,12 +79,10 @@ jobs:
 
       # Install GMT and other required dependencies from conda-forge
       - name: Install dependencies
-        shell: bash -l {0}
         run: conda env update --file environment.yml
 
       # Show installed pkg information for postmortem diagnostic
       - name: List installed packages
-        shell: bash -l {0}
         run: conda list
 
       # Download cached remote files (artifacts) from GitHub
@@ -95,7 +96,6 @@ jobs:
 
       # Move downloaded files to ~/.gmt directory and list them
       - name: Move and list downloaded remote files
-        shell: bash -l {0}
         run: |
           mkdir -p ~/.gmt
           mv .gmt/* ~/.gmt
@@ -105,21 +105,18 @@ jobs:
 
       # Install the package that we want to test
       - name: Install the package
-        shell: bash -l {0}
         run: |
           python setup.py sdist --formats=zip
           pip install dist/*
 
       # Install data version control (dvc) and pull data from dvc remote
       - name: Install dvc and pull data from dvc remote
-        shell: bash -l {0}
         run: |
           pip install dvc
           dvc pull
 
       # Run the tests
       - name: Test with pytest
-        shell: bash -l {0}
         run: make test PYTEST_EXTRA="-r P"
 
       # Upload diff images on test failure
@@ -132,7 +129,6 @@ jobs:
 
       # Build the documentation
       - name: Build the documentation
-        shell: bash -l {0}
         run: make -C doc clean all
 
       # Upload coverage to Codecov

.github/workflows/ci_tests_dev.yaml

@@ -106,7 +106,6 @@ jobs:
 
       # Move downloaded files to ~/.gmt directory and list them
       - name: Move and list downloaded remote files
-        shell: bash -l {0}
         run: |
           mkdir -p ~/.gmt
           mv .gmt/* ~/.gmt

doc/conf.py

@@ -9,7 +9,7 @@
 # isort: off
 from sphinx_gallery.sorting import (  # pylint: disable=no-name-in-module
     ExplicitOrder,
-    FileNameSortKey,
+    ExampleTitleSortKey,
 )
 from pygmt import __commit__, __version__
 from pygmt.sphinx_gallery import PyGMTScraper
@@ -71,10 +71,13 @@
     "gallery_dirs": ["gallery", "tutorials", "projections"],
     "subsection_order": ExplicitOrder(
         [
-            "../examples/gallery/line",
-            "../examples/gallery/coast",
-            "../examples/gallery/plot",
-            "../examples/gallery/grid",
+            "../examples/gallery/maps",
+            "../examples/gallery/lines",
+            "../examples/gallery/symbols",
+            "../examples/gallery/images",
+            "../examples/gallery/3d_plots",
+            "../examples/gallery/seismology",
+            "../examples/gallery/embellishments",
             "../examples/projections/azim",
             "../examples/projections/conic",
             "../examples/projections/cyl",
@@ -88,7 +91,7 @@
     # Remove the "Download all examples" button from the top level gallery
     "download_all_examples": False,
     # Sort gallery example by file name instead of number of lines (default)
-    "within_subsection_order": FileNameSortKey,
+    "within_subsection_order": ExampleTitleSortKey,
     # directory where function granular galleries are stored
     "backreferences_dir": "api/generated/backreferences",
     # Modules for which function level galleries are created.  In

doc/index.rst

@@ -38,7 +38,7 @@
     tutorials/contour-map.rst
     tutorials/earth-relief.rst
     tutorials/3d-perspective-image.rst
-    tutorials/inset.rst
+    tutorials/insets.rst
     tutorials/subplots.rst
     tutorials/configuration.rst
 

doc/install.rst

@@ -29,7 +29,7 @@ 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)::
+interpreter (e.g., in a Jupyter notebook)::
 
     import pygmt
     pygmt.show_versions()
@@ -40,8 +40,8 @@ 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.
+    install and test PyGMT for those who may have a slightly different setup or
+    want to install the latest development version.
 
 Which Python?
 -------------
@@ -51,9 +51,10 @@ work, but there is no guarantee that PyGMT will behave as expected.
 
 We recommend using the `Anaconda <https://www.anaconda.com/distribution>`__
 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.
+`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
+installations on your system.
 
 
 Which GMT?
@@ -110,14 +111,14 @@ 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
+    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!**)::
 
     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.
+called ``pygmt`` and won't affect your default ``base`` installation.
 
 
 Installing PyGMT
@@ -134,6 +135,10 @@ This installs the latest stable release of PyGMT from
 
     conda install pygmt
 
+This upgrades the installed PyGMT version to be the latest stable release::
+
+    conda update pygmt
+
 Using pip
 ~~~~~~~~~
 
@@ -147,13 +152,11 @@ Alternatively, you can install the latest development version from
 
     pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt
 
-or from PyGMT's `GitHub repository <https://github.com/GenericMappingTools/pygmt>`__ 
-(slower as it downloads the whole archive)::
-
-    pip install git+https://github.com/GenericMappingTools/pygmt.git#egg=pygmt
+To upgrade the installed stable release or development version to be the latest
+one, just add ``--upgrade`` to the corresponding command above.
 
-Any of the above methods (conda/pip) should allow you to use the ``pygmt``
-library from Python.
+Any of the above methods (conda/pip) should allow you to use the PyGMT package
+from Python.
 
 
 Testing your install
@@ -182,7 +185,8 @@ dependencies as well (be sure to have your conda environment activated)::
 
     conda install pytest pytest-mpl ipython
 
-Test your installation by running the following inside a Python interpreter::
+Test your installation by running the following inside a Python interpreter
+(note that it may take a few minutes)::
 
     import pygmt
     pygmt.show_versions()
@@ -193,14 +197,14 @@ Finding the GMT shared library
 ------------------------------
 
 Sometimes, PyGMT will be unable to find the correct version of the GMT shared
-library.
+library (``libgmt``).
 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. on a command line, run::
+``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

examples/gallery/3d_plots/README.txt

@@ -0,0 +1,2 @@
+3D Plots
+--------

examples/gallery/embellishments/README.txt

@@ -0,0 +1,2 @@
+Plot embellishments
+-------------------

examples/gallery/images/README.txt

@@ -0,0 +1,2 @@
+Images, contours, and fields
+----------------------------

examples/gallery/lines/README.txt

@@ -0,0 +1,2 @@
+Lines and vectors
+-----------------

examples/gallery/line/vector-heads-tails.py → examples/gallery/lines/vector_heads_tails.py

@@ -26,7 +26,7 @@
 In the following we use the :meth:`pygmt.Figure.plot` method to plot vectors
 with individual heads and tails. We must specify the modifiers (together with
 the vector type, here ``v``, see also
-:doc:`Vector types documentation </gallery/line/vectors>`) 
+:doc:`Vector types documentation </gallery/lines/vectors>`)
 by passing the corresponding shortcuts to the ``style`` parameter.
 
 """

examples/gallery/line/vectors.py → examples/gallery/lines/vectors.py

@@ -4,7 +4,7 @@
 
 The :meth:`pygmt.Figure.plot` method can plot Cartesian, circular, and geographic vectors.
 The ``style`` parameter controls vector attributes. See also
-:doc:`Vector attributes documentation </gallery/line/vector-heads-tails>`.
+:doc:`Vector attributes documentation </gallery/lines/vector_heads_tails>`.
 
 """
 import numpy as np

examples/gallery/maps/README.txt

@@ -0,0 +1,2 @@
+Maps and map elements
+---------------------

examples/gallery/seismology/README.txt

@@ -0,0 +1,2 @@
+Seismology and geodesy
+----------------------

examples/gallery/symbols/README.txt

@@ -0,0 +1,2 @@
+Symbols and markers
+-------------------

examples/tutorials/lines.py

@@ -125,7 +125,7 @@
 # example below, the line width is set to ``7p``, the color is set to ``green``, and the
 # line style is ``-.-`` (*dash dot dash*).
 #
-# For a gallery showing other ``pen`` settings, see :doc:`/gallery/line/linestyles`.
+# For a gallery showing other ``pen`` settings, see :doc:`/gallery/lines/linestyles`.
 
 fig = pygmt.Figure()
 fig.plot(