Merge branch 'master' into wrap-grd2xyz

Author: willschlitzer

.github/workflows/cache_data.yaml

@@ -26,7 +26,7 @@ jobs:
 
       # Install GMT
       - name: Install GMT
-        run: conda install -c conda-forge gmt=6.1.1
+        run: conda install -c conda-forge/label/dev gmt=6.2.0rc2
 
       # Download remote files
       - name: Download remote data

.github/workflows/ci_docs.yml

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

.github/workflows/ci_tests.yaml

@@ -52,7 +52,7 @@ jobs:
             optional-packages: ''
           - python-version: 3.9
             numpy-version: '1.20'
-            optional-packages: 'geopandas'
+            optional-packages: ''  # 'geopandas'
     defaults:
       run:
         shell: bash -l {0}
@@ -89,7 +89,7 @@ jobs:
       # Install GMT and other required dependencies from conda-forge
       - name: Install dependencies
         run: |
-          conda install conda-forge/label/dev::gmt=6.2.0rc1 \
+          conda install conda-forge/label/dev::gmt=6.2.0rc2 \
                         numpy=${{ matrix.numpy-version }} \
                         pandas xarray netCDF4 packaging \
                         ${{ matrix.optional-packages }} \

.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

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

@@ -93,6 +93,7 @@ Operations on grids:
     grdcut
     grdfill
     grdfilter
+    grdgradient
     grdtrack
 
 Crossover analysis with x2sys:

environment.yml

@@ -6,7 +6,7 @@ channels:
 dependencies:
     # Required dependencies
     - pip
-    - gmt=6.2.0rc1
+    - gmt=6.2.0rc2
     - numpy>=1.17
     - pandas
     - xarray

pygmt/__init__.py

@@ -38,6 +38,7 @@
     grdcut,
     grdfill,
     grdfilter,
+    grdgradient,
     grdinfo,
     grdtrack,
     info,

pygmt/helpers/decorators.py

@@ -40,6 +40,37 @@
         color : str or 1d array
             Select color or pattern for filling of symbols or polygons. Default
             is no fill.""",
+    "I": r"""
+        spacing : str
+            *xinc*\ [**+e**\|\ **n**][/\ *yinc*\ [**+e**\|\ **n**]].
+            *x_inc* [and optionally *y_inc*] is the grid spacing.
+
+            - **Geographical (degrees) coordinates**: Optionally, append an
+              increment unit. Choose among **m** to indicate arc minutes or
+              **s** to indicate arc seconds. If one of the units **e**, **f**,
+              **k**, **M**, **n** or **u** is appended instead, the increment
+              is assumed to be given in meter, foot, km, mile, nautical mile or
+              US survey foot, respectively, and will be converted to the
+              equivalent degrees longitude at the middle latitude of the region
+              (the conversion depends on :gmt-term:`PROJ_ELLIPSOID`). If
+              *y_inc* is given but set to 0 it will be reset equal to *x_inc*;
+              otherwise it will be converted to degrees latitude.
+
+            - **All coordinates**: If **+e** is appended then the corresponding
+              max *x* (*east*) or *y* (*north*) may be slightly adjusted to fit
+              exactly the given increment [by default the increment may be
+              adjusted slightly to fit the given domain]. Finally, instead of
+              giving an increment you may specify the *number of nodes* desired
+              by appending **+n** to the supplied integer argument; the
+              increment is then recalculated from the number of nodes, the
+              *registration*, and the domain. The resulting increment value
+              depends on whether you have selected a gridline-registered or
+              pixel-registered grid; see :gmt-docs:`GMT File Formats
+              <cookbook/file-formats.html#gmt-file-formats>` for details.
+
+            **Note**: If ``region=grdfile`` is used then the grid spacing and
+            the registration have already been initialized; use ``spacing`` and
+            ``registration`` to override these values.""",
     "V": """\
         verbose : bool or str
             Select verbosity level [Default is **w**], which modulates the messages

pygmt/src/__init__.py

@@ -16,6 +16,7 @@
 from pygmt.src.grdcut import grdcut
 from pygmt.src.grdfill import grdfill
 from pygmt.src.grdfilter import grdfilter
+from pygmt.src.grdgradient import grdgradient
 from pygmt.src.grdimage import grdimage
 from pygmt.src.grdinfo import grdinfo
 from pygmt.src.grdtrack import grdtrack