Add inline code examples in data processing module docstrings

[willschlitzer]

As first discussed in this comment, module docstrings should contain inline code examples to show a working example of the module with the correct syntax without needing to find an example page.

To prevent example functions from being run in tests, add _doctest_skip__ = [MODULE NAME] under the import statements.

• binstats
• blockmean Add inline example for blockmean #1729
• blockmedian Add inline example for blockmedian #1730
• blockmode Add inline example for blockmode #1731
• dimfilter Add inline example to dimfilter #1956
• filter1d
• nearneighbor Add inline example for nearneighbor #1919
• project
• select Add inline example for select #1756
• sph2grd Add inline example for sph2grd #1718
• sphdistance Add inline example for sphdistance #1916
• sphinterpolate Add inline example for sphinterpolate #1917
• surface Add inline example to surface #1953
• xyz2grd Add inline example for xyz2grd #1719
• grd2xyz Add inline example for grd2xyz #1713
• grdclip Add inline example for grdclip #1711
• grdcut Add inline example for grdcut #1689
• grdfill Add inline example for grdfill #1954
• grdfilter
• grdgradient Add inline example for grdgradient #1720
• grdlandmask Add inline example for grdlandmask #1721
• grdproject Add inline example for grdproject #1722
• grdsample Add inline example for grdsample #1724
• grdtrack Add inline example for grdtrack #1725
• grdvolume Add inline example for grdvolume #1726

Are you willing to help implement and maintain this feature? Yes

[maxrjones]

Regarding the CI issue raised in #1666 (comment), here are two options:

1. Use the doctest skip directive to skip particular examples all the time.
2. Add a new target to the Makefile to invoke pytest without doctest, such that the tests without docstring examples can be run on every PR and doctests could be run occasionally.

[willschlitzer]

@GenericMappingTools/pygmt-maintainers Should this only be for data processing modules that can't be as easily demonstrated as a plotting function, or should there be in-line examples for all of our modules?

My vote is for all of them.

[maxrjones]

Should this only be for data processing modules that can't be as easily demonstrated as a plotting function, or should there be in-line examples for all of our modules?

My vote is for all of them.

Sounds good to me.

[weiji14]

Should this only be for data processing modules that can't be as easily demonstrated as a plotting function, or should there be in-line examples for all of our modules?

My vote is for all of them.

Sounds good to me.

Ok with doing inline examples for all, but maybe prioritize those that don't already have a gallery example first. E.g. don't do grdgradient until much later.