Add inline example for grdclip (#1711)

Example to create a new grid from an input grid using
pygmt.grdclip. Shows how users can set values that
are above/below a given value to a new value.

Co-authored-by: Meghan Jones <[email protected]>

Author: willschlitzer

pygmt/src/grdclip.py

@@ -77,6 +77,26 @@ def grdclip(grid, **kwargs):
         - :class:`xarray.DataArray` if ``outgrid`` is not set
         - None if ``outgrid`` is set (grid output will be stored in file set by
           ``outgrid``)
+
+    Examples
+    --------
+    >>> import pygmt  # doctest: +SKIP
+    >>> # Load a grid of @earth_relief_30m data, with an x-range of 10 to 30,
+    >>> # and a y-range of 15 to 25
+    >>> grid = pygmt.datasets.load_earth_relief(
+    ...     resolution="30m", region=[10, 30, 15, 25]
+    ... )  # doctest: +SKIP
+    >>> # Report the minimum and maximum data values
+    >>> [grid.data.min(), grid.data.max()]  # doctest: +SKIP
+    [179.0, 2103.0]
+    >>> # Create a new grid from an input grid. Set all values below 1,000 to
+    >>> # 0 and all values above 1,500 to 10,000
+    >>> new_grid = pygmt.grdclip(
+    ...     grid=grid, below=[1000, 0], above=[1500, 10000]
+    ... )  # doctest: +SKIP
+    >>> # Report the minimum and maximum data values
+    >>> [new_grid.data.min(), new_grid.data.max()]  # doctest: +SKIP
+    [0.0, 10000.0]
     """
     with GMTTempFile(suffix=".nc") as tmpfile:
         with Session() as lib: