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.

[willschlitzer]

Looking through the examples in the GMT documentation and PyGMT tests, a few of them call remote datasets without using a PyGMT function (e.g. @Table_5_11_mean.xyz for surface). Should the example just call the remote dataset as is (with the "@" in front calling the file), or should load_sample_data() be updated to include the remote datasets for the in-line example?

[maxrjones]

Looking through the examples in the GMT documentation and PyGMT tests, a few of them call remote datasets without using a PyGMT function (e.g. @Table_5_11_mean.xyz for surface). Should the example just call the remote dataset as is (with the "@" in front calling the file), or should load_sample_data() be updated to include the remote datasets for the in-line example?

For tests, IMO it doesn't matter much. For user-facing examples I think it would be better to update load_sample_data.

[willschlitzer]

Are there any gridded datasets with holes in them to use for an example for grdfill? I can use the code from one of the tests, but it seems counterproductive to demo removing data from a grd file only to add it back in with grdfill.

[maxrjones]

Are there any gridded datasets with holes in them to use for an example for grdfill? I can use the code from one of the tests, but it seems counterproductive to demo removing data from a grd file only to add it back in with grdfill.

Looking through https://oceania.generic-mapping-tools.org/cache/, data_w_nans.nc seems like one option. Below is a picture from the gmt tests that uses that file.

[willschlitzer]

Are there any gridded datasets with holes in them to use for an example for grdfill? I can use the code from one of the tests, but it seems counterproductive to demo removing data from a grd file only to add it back in with grdfill.

Looking through https://oceania.generic-mapping-tools.org/cache/, data_w_nans.nc seems like one option. Below is a picture from the gmt tests that uses that file.

Thanks @meghanrjones!

[maxrjones]

Are there any gridded datasets with holes in them to use for an example for grdfill? I can use the code from one of the tests, but it seems counterproductive to demo removing data from a grd file only to add it back in with grdfill.

There's now a better file to use - earth_relief_20m_holes.grd, see GenericMappingTools/gmt#6678 and GenericMappingTools/gmtserver-admin#155 for background.