Add common alias spacing (-I) for specifying grid increments (#1288)

Used to specify the grid spacing. See also
https://github.com/GenericMappingTools/gmt/blob/6.2.0rc1/doc/rst/source/explain_-I.rst_.

* Use standardized spacing (I) docstring in blockmean, blockmedian, grdfilter and surface

Co-authored-by: Dongdong Tian <[email protected]>

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/blockm.py

@@ -92,10 +92,7 @@ def blockmean(table, outfile=None, **kwargs):
         providing a file name to an ASCII data table, a 2D
         {table-classes}.
 
-    spacing : str
-        *xinc*\[\ *unit*\][**+e**\|\ **n**]
-        [/*yinc*\ [*unit*][**+e**\|\ **n**]].
-        *xinc* [and optionally *yinc*] is the grid spacing.
+    {I}
 
     region : str or list
         *xmin/xmax/ymin/ymax*\[\ **+r**\][**+u**\ *unit*].
@@ -152,10 +149,7 @@ def blockmedian(table, outfile=None, **kwargs):
         providing a file name to an ASCII data table, a 2D
         {table-classes}.
 
-    spacing : str
-        *xinc*\[\ *unit*\][**+e**\|\ **n**]
-        [/*yinc*\ [*unit*][**+e**\|\ **n**]].
-        *xinc* [and optionally *yinc*] is the grid spacing.
+    {I}
 
     region : str or list
         *xmin/xmax/ymin/ymax*\[\ **+r**\][**+u**\ *unit*].

pygmt/src/grdfilter.py

@@ -97,10 +97,7 @@ def grdfilter(grid, **kwargs):
         5: grid (x,y) in Mercator ``projection='m1'`` img units, *width* in km,
         Spherical distance calculation.
 
-    spacing : str
-        *xinc*\[\ *unit*\][**+e**\|\ **n**]
-        [/*yinc*\ [*unit*][**+e**\|\ **n**]].
-        *xinc* [and optionally *yinc*] is the grid spacing.
+    {I}
     nans : str or float
         **i**\|\ **p**\|\ **r**.
         Determine how NaN-values in the input grid affects the filtered output.

pygmt/src/surface.py

@@ -54,10 +54,7 @@ def surface(x=None, y=None, z=None, data=None, **kwargs):
     data : str or 2d array
         Either a data file name or a 2d numpy array with the tabular data.
 
-    spacing : str
-        *xinc*\[\ *unit*\][**+e**\|\ **n**]\
-        [/*yinc*\ [*unit*][**+e**\|\ **n**]].
-        *xinc* [and optionally *yinc*] is the grid spacing.
+    {I}
 
     region : str or list
         *xmin/xmax/ymin/ymax*\[**+r**][**+u**\ *unit*].