Merge branch 'master' into columns-plot3d

Author: willschlitzer

.github/ISSUE_TEMPLATE/release_checklist.md

@@ -29,7 +29,7 @@ assignees: ''
   - [ ] Edit the draft release notes with the finalized changelog
   - [ ] Set the tag version and release title to vX.Y.Z
   - [ ] Make a release by clicking the 'Publish Release' button, this will automatically create a tag too
-- [ ] Manually upload the pygmt-vX.Y.Z.zip file to https://zenodo.org/deposit, ensure that it is filed under the correct reserved DOI
+- [ ] Manually upload the pygmt-vX.Y.Z.zip and baseline-images.zip files to https://zenodo.org/deposit, ensure that it is filed under the correct reserved DOI
 
 **After release**:
 - [ ] Update conda-forge [pygmt-feedstock](https://github.com/conda-forge/pygmt-feedstock) [Usually done automatically by conda-forge's bot]

.github/workflows/cache_data.yaml

@@ -17,34 +17,36 @@ jobs:
         shell: bash -l {0}
 
     steps:
+      # Checkout current git repository
+      - name: Checkout
+        uses: actions/checkout@v2.3.4
+        with:
+          # fecth all history so that setuptools-scm works
+          fetch-depth: 0
+
       # Setup Miniconda
       - name: Setup Miniconda
         uses: conda-incubator/setup-miniconda@v2.1.1
         with:
           channels: conda-forge
           miniconda-version: "latest"
 
-      # Install GMT
-      - name: Install GMT
-        run: conda install -c conda-forge gmt=6.1.1
+      # Install GMT and other required dependencies from conda-forge
+      - name: Install dependencies
+        run: |
+          conda install gmt=6.2.0 \
+                        numpy pandas xarray netCDF4 packaging matplotlib
+
+      # Install the package that we want to test
+      - name: Install the package
+        run: |
+          python setup.py sdist --formats=zip
+          pip install dist/*
 
       # Download remote files
       - name: Download remote data
         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.
-          gmt which -Ga @N35E135.earth_relief_03s_g.nc
-          # @srtm_tiles.nc is needed for 03s and 01s relief data
-          gmt which -Ga @srtm_tiles.nc
-          gmt which -Ga @ridge.txt @Table_5_11.txt @test.dat.nc \
-                        @tut_bathy.nc @tut_quakes.ngdc @tut_ship.xyz \
-                        @usgs_quakes_22.txt @fractures_06.txt
+          python -c "from pygmt.helpers.testing import download_test_data; download_test_data()"
 
       # Upload the downloaded files as artifacts to GitHub
       - name: Upload artifacts to GitHub

.github/workflows/ci_docs.yml

@@ -66,8 +66,7 @@ jobs:
       # Install GMT and other required dependencies from conda-forge
       - name: Install dependencies
         run: |
-          conda install -c conda-forge/label/dev gmt=6.2.0rc1
-          conda install numpy pandas xarray netCDF4 packaging \
+          conda install gmt=6.2.0 numpy pandas xarray netCDF4 packaging \
                         ipython make myst-parser \
                         sphinx sphinx-copybutton sphinx-gallery sphinx_rtd_theme
 

.github/workflows/ci_tests.yaml

@@ -45,11 +45,14 @@ jobs:
           #   python-version: 3.7
           #   isDraft: true
         # Pair Python 3.7 with NumPy 1.17 and Python 3.9 with NumPy 1.20
+        # Only install optional packages on Python 3.9/NumPy 1.20
         include:
           - python-version: 3.7
             numpy-version: '1.17'
+            optional-packages: ''
           - python-version: 3.9
             numpy-version: '1.20'
+            optional-packages: ''  # 'geopandas'
     defaults:
       run:
         shell: bash -l {0}
@@ -86,9 +89,9 @@ jobs:
       # Install GMT and other required dependencies from conda-forge
       - name: Install dependencies
         run: |
-          conda install -c conda-forge/label/dev gmt=6.2.0rc1
-          conda install numpy=${{ matrix.numpy-version }} \
+          conda install gmt=6.2.0 numpy=${{ matrix.numpy-version }} \
                         pandas xarray netCDF4 packaging \
+                        ${{ matrix.optional-packages }} \
                         codecov coverage[toml] dvc ipython make \
                         pytest-cov pytest-mpl pytest>=6.0 \
                         sphinx-gallery

.github/workflows/ci_tests_dev.yaml

@@ -83,7 +83,7 @@ jobs:
       # Install dependencies from conda-forge
       - name: Install dependencies
         run: |
-          conda install ninja cmake libblas libcblas liblapack fftw gdal \
+          conda install ninja cmake libblas libcblas liblapack fftw gdal=3.2 geopandas \
                         ghostscript libnetcdf hdf5 zlib curl pcre make dvc
           pip install --pre numpy pandas xarray netCDF4 packaging \
                             ipython pytest-cov pytest-mpl pytest>=6.0 sphinx-gallery

.github/workflows/dvc-diff.yml

@@ -19,7 +19,7 @@ jobs:
         fetch-depth: 0
 
     - name: Setup data version control (DVC)
-      uses: iterative/setup-dvc@v1.0.2
+      uses: iterative/setup-dvc@v1.0.3
 
     - name: Setup continuous machine learning (CML)
       uses: iterative/setup-cml@v1.0.0

.github/workflows/release-baseline-images.yml

@@ -0,0 +1,40 @@
+# Upload the ZIP archive of baseline images as a release asset
+
+name: Upload baseline images
+
+# Only run for releases
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  upload-baseline:
+    name: Upload baseline images
+    runs-on: ubuntu-latest
+    if: github.repository == 'GenericMappingTools/pygmt'
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2.3.4
+
+    - name: Setup data version control (DVC)
+      uses: iterative/setup-dvc@v1.0.3
+
+    - name: Pull baseline image data from dvc remote
+      run: |
+        dvc pull
+        ls -lhR pygmt/tests/baseline/
+
+    - name: Create the baseline image asset in zip format
+      run: |
+        mkdir baseline-images
+        mv pygmt/tests/baseline/*.png baseline-images/
+        zip -r baseline-images.zip baseline-images
+        shasum -a 256 baseline-images.zip
+
+    - name: Upload baseline image as a release asset
+      uses: shogo82148/actions-upload-release-asset@v1.3.0
+      with:
+        upload_url: ${{ github.event.release.upload_url }}
+        asset_path: baseline-images.zip

CONTRIBUTING.md

@@ -49,7 +49,6 @@ read it carefully.
   - [Testing your code](#testing-your-code)
   - [Testing plots](#testing-plots)
   - [Documentation](#documentation)
-  - [Code Review](#code-review)
 
 
 ## What Can I Do?
@@ -205,36 +204,73 @@ hesitate to [ask questions](#how-can-i-talk-to-you)):
 
 ### General guidelines
 
-We follow the [git pull request workflow](http://www.asmeurer.com/git-workflow/) to
-make changes to our codebase.
+We follow the [git pull request workflow](http://www.asmeurer.com/git-workflow)
+to make changes to our codebase.
 Every change made goes through a pull request, even our own, so that our
-[continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) services
-have a change to check that the code is up to standards and passes all our tests.
+[continuous integration](https://en.wikipedia.org/wiki/Continuous_integration)
+services have a chance to check that the code is up to standards and passes all
+our tests.
 This way, the *master* branch is always stable.
 
-General guidelines for pull requests (PRs):
-
-* **Open an issue first** describing what you want to do. If there is already an issue
-  that matches your PR, leave a comment there instead to let us know what you plan to
-  do.
-* Each pull request should consist of a **small** and logical collection of changes.
-* Larger changes should be broken down into smaller components and integrated
-  separately. For example, break the wrapping of aliases into multiple pull requests.
-* Bug fixes should be submitted in separate PRs.
-* Use underscores for all Python (*.py) files as per [PEP8](https://www.python.org/dev/peps/pep-0008/),
-  not hyphens. Directory names should also use underscores instead of hyphens.
-* Describe what your PR changes and *why* this is a good thing. Be as specific as you
-  can. The PR description is how we keep track of the changes made to the project over
-  time.
-* Do not commit changes to files that are irrelevant to your feature or bugfix (eg:
-  `.gitignore`, IDE project files, etc).
-* Write descriptive commit messages. Chris Beams has written a
-  [guide](https://chris.beams.io/posts/git-commit/) on how to write good commit
-  messages.
-* Be willing to accept criticism and work on improving your code; we don't want to break
-  other users' code, so care must be taken not to introduce bugs.
-* Be aware that the pull request review process is not immediate, and is generally
-  proportional to the size of the pull request.
+General guidelines for making a Pull Request (PR):
+
+* What should be included in a PR
+  - Have a quick look at the titles of all the existing issues first. If there
+    is already an issue that matches your PR, leave a comment there to let us
+    know what you plan to do. Otherwise, **open an issue** describing what you
+    want to do.
+  - Each pull request should consist of a **small** and logical collection of
+    changes; larger changes should be broken down into smaller parts and
+    integrated separately.
+  - Bug fixes should be submitted in separate PRs.
+* How to write and submit a PR
+  - Use underscores for all Python (*.py) files as per
+    [PEP8](https://www.python.org/dev/peps/pep-0008/), not hyphens. Directory
+    names should also use underscores instead of hyphens.
+  - Describe what your PR changes and *why* this is a good thing. Be as
+    specific as you can. The PR description is how we keep track of the changes
+    made to the project over time.
+  - Do not commit changes to files that are irrelevant to your feature or
+    bugfix (e.g.: `.gitignore`, IDE project files, etc).
+  - Write descriptive commit messages. Chris Beams has written a
+    [guide](https://chris.beams.io/posts/git-commit/) on how to write good
+    commit messages.
+* PR review
+  - Be willing to accept criticism and work on improving your code; we don't
+    want to break other users' code, so care must be taken not to introduce
+    bugs.
+  - Be aware that the pull request review process is not immediate, and is
+    generally proportional to the size of the pull request.
+
+#### Code Review
+
+After you've submitted a pull request, you should expect to hear at least a
+comment within a couple of days. We may suggest some changes, improvements or
+alternative implementation details.
+
+To increase the chances of getting your pull request accepted quickly, try to:
+
+* Submit a friendly PR
+  - Write a good and detailed description of what the PR does.
+  - Write some documentation for your code (docstrings) and leave comments
+    explaining the *reason* behind non-obvious things.
+  - Write tests for the code you wrote/modified if needed.
+    Please refer to [Testing your code](#testing-your-code) or
+    [Testing plots](#testing-plots).
+  - Include an example of new features in the gallery or tutorials.
+    Please refer to [Gallery plots](#gallery-plots) or [Tutorials](#tutorials).
+* Have a good coding style
+  - Use readable code, as it is better than clever code (even with comments).
+  - Follow the [PEP8](http://pep8.org) style guide for code and the
+    [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)
+    for docstrings. Please refer to [Code style](#code-style).
+
+Pull requests will automatically have tests run by GitHub Actions.
+This includes running both the unit tests as well as code linters.
+GitHub will show the status of these checks on the pull request.
+Try to get them all passing (green).
+If you have any trouble, leave a comment in the PR or
+[get in touch](#how-can-i-talk-to-you).
 
 ### Setting up your environment
 
@@ -510,11 +546,17 @@ def test_my_plotting_case():
 
 ### Documentation
 
+Most documentation sources are in Python `*.py` files under the `examples/`
+folder, and the code docstrings can be found e.g. under the `pygmt/src/` and
+`pygmt/datasets/` folders. The documentation are written in
+[reStructuredText](https://docutils.sourceforge.io/rst.html) and
+built by [Sphinx](http://www.sphinx-doc.org/). Please refer to
+[reStructuredText Cheatsheet](https://docs.generic-mapping-tools.org/latest/rst-cheatsheet.html)
+if you are new to reStructuredText.
+
 #### Building the documentation
 
-Most documentation sources are in the `doc` folder.
-We use [sphinx](http://www.sphinx-doc.org/) to build the web pages from these sources.
-To build the HTML files:
+To build the HTML files from sources:
 
 ```bash
 cd doc
@@ -560,33 +602,3 @@ https://docs.generic-mapping-tools.org/latest/gmt.conf.html#term-COLOR_FOREGROUN
 
 Sphinx will create a link to the automatically generated page for that
 function/class/module.
-
-**All docstrings** should follow the
-[numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html).
-All functions/classes/methods should have docstrings with a full description of all
-arguments and return values.
-
-### Code Review
-
-After you've submitted a pull request, you should expect to hear at least a comment
-within a couple of days.
-We may suggest some changes or improvements or alternatives.
-
-Some things that will increase the chance that your pull request is accepted quickly:
-
-* Write a good and detailed description of what the PR does.
-* Write tests for the code you wrote/modified.
-* Readable code is better than clever code (even with comments).
-* Write documentation for your code (docstrings) and leave comments explaining the
-  *reason* behind non-obvious things.
-* Include an example of new features in the gallery or tutorials.
-* Follow the [PEP8](http://pep8.org) style guide for code and the
-  [numpy guide](https://numpydoc.readthedocs.io/en/latest/format.html)
-  for documentation.
-
-Pull requests will automatically have tests run by GitHub Actions.
-This includes running both the unit tests as well as code linters.
-GitHub will show the status of these checks on the pull request.
-Try to get them all passing (green).
-If you have any trouble, leave a comment in the PR or
-[get in touch](#how-can-i-talk-to-you).

doc/api/index.rst

@@ -88,8 +88,12 @@ Operations on grids:
 .. autosummary::
     :toctree: generated
 
+    grdclip
     grdcut
+    grdfill
     grdfilter
+    grdlandmask
+    grdgradient
     grdtrack
 
 Crossover analysis with x2sys:

doc/conf.py

@@ -48,6 +48,7 @@
 # intersphinx configuration
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
+    "geopandas": ("https://geopandas.org/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "xarray": ("https://xarray.pydata.org/en/stable/", None),