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

[weiji14]

Description of proposed changes

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

Preview at https://pygmt-git-common-aliases-spacing-gmt.vercel.app/api/generated/pygmt.surface.html

This PR expands and standardizes the spacing (-I) parameter's docstring in blockmean, blockmedian, grdfilter and surface. The {I} common option will also be useful for many future PyGMT modules according to https://github.com/GenericMappingTools/pygmt/pull/1273/files#r637586300:

• blockmean
• blockmedian
• blockmode (Wrap blockmode #1456)
• gmtbinstats
• grdblend
• grdfilter (Wrap grdfilter #616)
• grdlandmask (Wrap grdlandmask #1273)
• grdmask
• grdmath
• grdsample (Wrap grdsample #1380)
• mask_common_
• nearneighbor (Wrap nearneighbor #1379)
• sph2grd
• sphdistance (Wrap sphdistance #1383)
• sphinterpolate (Wrap sphinterpolate #1418)
• supplements/geodesy/earthtide
• supplements/geodesy/gpsgridder
• supplements/potential/grdgravmag3d
• supplements/potential/grdseamount
• supplements/potential/talwani3d
• supplements/spotter/grdspotter
• supplements/spotter/hotspotter
• supplements/spotter/polespotter
• surface
• triangulate (Wrap triangulate #731)
• xyz2grd (Wrap xyz2grd #636)

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[willschlitzer]

One thing I've been meaning to ask about at the gmt repo is why their are a limited number of options listed for units next to xinc and yinc. Rather than **-I**\ *xinc*\ [**+e**\|\ **n**][/\ *yinc*\ [**+e**\|\ **n**]] wouldn't it make more sense for it to be **-I**\ *xinc*\ [**+e**\|\ **f**\|\ **k**\|\ **M**\|\ **n**\|\ **u**][/\ *yinc*\ [**+e**\|\ **f**\|\ **k**\|\ **M**\|\ **n**]]?

[maxrjones]

One thing I've been meaning to ask about at the gmt repo is why their are a limited number of options listed for units next to xinc and yinc. Rather than **-I**\ *xinc*\ [**+e**\|\ **n**][/\ *yinc*\ [**+e**\|\ **n**]] wouldn't it make more sense for it to be **-I**\ *xinc*\ [**+e**\|\ **f**\|\ **k**\|\ **M**\|\ **n**\|\ **u**][/\ *yinc*\ [**+e**\|\ **f**\|\ **k**\|\ **M**\|\ **n**]]?

The +e|n are modifiers that can be appended in addition to the units. For example:
spacing='0.5e+e' indicates a 0.5 m grid spacing in which the region argument is adjusted to match the grid spacing (0.5m), rather than the default of the grid spacing being adjusted to match the region. So the full description would be:
-Ixinc[e|f|k|M|n|u][+e|n][/yinc[e|f|k|M|n|u][+e|n]]. The gmt docs are not consistent for whether [e|f|k|M|n|u] is included in the synopsis (e.g., basemap -L+w), summarized as something like unit (e.g., grd2xyz -W+u), or just mentioned in the full description (e.g., -I descriptions). I guess for pygmt we should pick which version seems the most clear to use throughout.

[seisman]

So the full description would be:
-Ixinc[e|f|k|M|n|u][+e|n][/yinc[e|f|k|M|n|u][+e|n]]. The gmt docs are not consistent for whether [e|f|k|M|n|u] is included in the synopsis (e.g., basemap -L+w), summarized as something like unit (e.g., grd2xyz -W+u), or just mentioned in the full description (e.g., -I descriptions). I guess for pygmt we should pick which version seems the most clear to use throughout.

I can't find the original discussions in the GMT repository, but I believe the GMT developers agree with omitting units in the synopsis to make it shorter.

[seisman]

Looks good to me.

[maxrjones]

The preview looks odd, like this is somehow splitting up the parameters sections.

[weiji14]

The preview looks odd, like this is somehow splitting up the parameters sections.

Ok, fixed with cab6ac1 (thanks @seisman)! Preview now looks ok, though not sure why it's starting on a different line still:

One thing I've been meaning to ask about at the gmt repo is why their are a limited number of options listed for units next to xinc and yinc. Rather than **-I**\ *xinc*\ [**+e**\|\ **n**][/\ *yinc*\ [**+e**\|\ **n**]] wouldn't it make more sense for it to be **-I**\ *xinc*\ [**+e**\|\ **f**\|\ **k**\|\ **M**\|\ **n**\|\ **u**][/\ *yinc*\ [**+e**\|\ **f**\|\ **k**\|\ **M**\|\ **n**]]?

The +e|n are modifiers that can be appended in addition to the units. For example:
spacing='0.5e+e' indicates a 0.5 m grid spacing in which the region argument is adjusted to match the grid spacing (0.5m), rather than the default of the grid spacing being adjusted to match the region. So the full description would be:
-Ixinc[e|f|k|M|n|u][+e|n][/yinc[e|f|k|M|n|u][+e|n]]. The gmt docs are not consistent for whether [e|f|k|M|n|u] is included in the synopsis (e.g., basemap -L+w), summarized as something like unit (e.g., grd2xyz -W+u), or just mentioned in the full description (e.g., -I descriptions). I guess for pygmt we should pick which version seems the most clear to use throughout.

I've followed the format in https://github.com/GenericMappingTools/gmt/blob/6.2.0rc1/doc/rst/source/explain_-I.rst_ which is used in most of upstream GMT, though you're right that there is some inconsistency throughout the documentation pages. Personally, the e|f|k|m|n block looks confusing, and most people probably won't need to declare the units (especially the imperial ones 😛). But I'm biased as a Cartesian map maker using only +e|n so will defer to what Geographical users prefer.