Update existing inline examples to the new doctest style (#1793)

Author: seisman

pygmt/src/blockm.py

@@ -12,6 +12,8 @@
     use_alias,
 )
 
+__doctest_skip__ = ["blockmean", "blockmedian", "blockmode"]
+
 
 def _blockm(block_method, data, x, y, z, outfile, **kwargs):
     r"""
@@ -150,15 +152,13 @@ def blockmean(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # Load a table of ship observations of bathymetry off Baja California
-    >>> data = pygmt.datasets.load_sample_data(
-    ...     name="bathymetry"
-    ... )  # doctest: +SKIP
+    >>> data = pygmt.datasets.load_sample_data(name="bathymetry")
     >>> # Calculate block mean values within 5 by 5 minute bins
     >>> data_bmean = pygmt.blockmean(
     ...     data=data, region=[245, 255, 20, 30], spacing="5m"
-    ... )  # doctest: +SKIP
+    ... )
     """
     return _blockm(
         block_method="blockmean", data=data, x=x, y=y, z=z, outfile=outfile, **kwargs
@@ -240,15 +240,13 @@ def blockmedian(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # Load a table of ship observations of bathymetry off Baja California
-    >>> data = pygmt.datasets.load_sample_data(
-    ...     name="bathymetry"
-    ... )  # doctest: +SKIP
+    >>> data = pygmt.datasets.load_sample_data(name="bathymetry")
     >>> # Calculate block median values within 5 by 5 minute bins
     >>> data_bmedian = pygmt.blockmedian(
     ...     data=data, region=[245, 255, 20, 30], spacing="5m"
-    ... )  # doctest: +SKIP
+    ... )
     """
     return _blockm(
         block_method="blockmedian", data=data, x=x, y=y, z=z, outfile=outfile, **kwargs
@@ -330,15 +328,13 @@ def blockmode(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # Load a table of ship observations of bathymetry off Baja California
-    >>> data = pygmt.datasets.load_sample_data(
-    ...     name="bathymetry"
-    ... )  # doctest: +SKIP
+    >>> data = pygmt.datasets.load_sample_data(name="bathymetry")
     >>> # Calculate block mode values within 5 by 5 minute bins
     >>> data_bmode = pygmt.blockmode(
     ...     data=data, region=[245, 255, 20, 30], spacing="5m"
-    ... )  # doctest: +SKIP
+    ... )
     """
     return _blockm(
         block_method="blockmode", data=data, x=x, y=y, z=z, outfile=outfile, **kwargs

pygmt/src/grd2xyz.py

@@ -15,6 +15,8 @@
     use_alias,
 )
 
+__doctest_skip__ = ["grd2xyz"]
+
 
 @fmt_docstring
 @use_alias(
@@ -128,17 +130,15 @@ def grd2xyz(grid, output_type="pandas", outfile=None, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # 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
+    ... )
     >>> # Create a pandas DataFrame with the xyz data from an input grid
-    >>> xyz_dataframe = pygmt.grd2xyz(
-    ...     grid=grid, output_type="pandas"
-    ... )  # doctest: +SKIP
-    >>> xyz_dataframe.head(n=2)  # doctest: +SKIP
+    >>> xyz_dataframe = pygmt.grd2xyz(grid=grid, output_type="pandas")
+    >>> xyz_dataframe.head(n=2)
          lon    lat  elevation
     0  10.25  24.75      903.5
     1  10.75  24.75      820.0

pygmt/src/grdclip.py

@@ -12,6 +12,8 @@
 )
 from pygmt.io import load_dataarray
 
+__doctest_skip__ = ["grdclip"]
+
 
 @fmt_docstring
 @use_alias(
@@ -80,22 +82,22 @@ def grdclip(grid, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # 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
+    >>> [grid.data.min(), grid.data.max()]
     [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
+    >>> [new_grid.data.min(), new_grid.data.max()]
     [0.0, 10000.0]
     """
     with GMTTempFile(suffix=".nc") as tmpfile:

pygmt/src/grdcut.py

@@ -12,6 +12,8 @@
 )
 from pygmt.io import load_dataarray
 
+__doctest_skip__ = ["grdcut"]
+
 
 @fmt_docstring
 @use_alias(
@@ -90,17 +92,15 @@ def grdcut(grid, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # 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
+    ... )
     >>> # Create a new grid from an input grid, with an x-range of 12 to 15,
     >>> # and a y-range of 21 to 24
-    >>> new_grid = pygmt.grdcut(
-    ...     grid=grid, region=[12, 15, 21, 24]
-    ... )  # doctest: +SKIP
+    >>> new_grid = pygmt.grdcut(grid=grid, region=[12, 15, 21, 24])
     """
     with GMTTempFile(suffix=".nc") as tmpfile:
         with Session() as lib:

pygmt/src/grdgradient.py

@@ -14,6 +14,8 @@
 )
 from pygmt.io import load_dataarray
 
+__doctest_skip__ = ["grdgradient"]
+
 
 @fmt_docstring
 @use_alias(
@@ -152,17 +154,14 @@ def grdgradient(grid, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # 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
+    ... )
     >>> # Create a new grid from an input grid, set the azimuth to 10 degrees,
-    >>> # and the direction to "c" for Cartesian coordinates
-    >>> new_grid = pygmt.grdgradient(
-    ...     grid=grid, azimuth=10, direction="c"
-    ... )  # doctest: +SKIP
+    >>> new_grid = pygmt.grdgradient(grid=grid, azimuth=10)
     """
     with GMTTempFile(suffix=".nc") as tmpfile:
         if "Q" in kwargs and "N" not in kwargs:

pygmt/src/grdproject.py

@@ -1,7 +1,6 @@
 """
 grdproject - Forward and inverse map transformation of grids.
 """
-
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
@@ -13,6 +12,8 @@
 )
 from pygmt.io import load_dataarray
 
+__doctest_skip__ = ["grdproject"]
+
 
 @fmt_docstring
 @use_alias(
@@ -98,18 +99,16 @@ def grdproject(grid, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # 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
+    ... )
     >>> # Create a new grid from the input grid, set the projection to
     >>> # Mercator, and set inverse to "True" to change from "geographic"
     >>> # to "rectangular"
-    >>> new_grid = pygmt.grdproject(
-    ...     grid=grid, projection="M10c", inverse=True
-    ... )  # doctest: +SKIP
+    >>> new_grid = pygmt.grdproject(grid=grid, projection="M10c", inverse=True)
     """
     if "J" not in kwargs:
         raise GMTInvalidInput("The projection must be specified.")

pygmt/src/grdsample.py

@@ -12,6 +12,8 @@
 )
 from pygmt.io import load_dataarray
 
+__doctest_skip__ = ["grdsample"]
+
 
 @fmt_docstring
 @use_alias(
@@ -76,17 +78,17 @@ def grdsample(grid, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # 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
+    ... )
     >>> # Create a new grid from an input grid, change the registration,
     >>> # and set both x- and y-spacing to 0.5 degrees
     >>> new_grid = pygmt.grdsample(
     ...     grid=grid, translate=True, spacing=[0.5, 0.5]
-    ... )  # doctest: +SKIP
+    ... )
     """
     with GMTTempFile(suffix=".nc") as tmpfile:
         with Session() as lib:

pygmt/src/inset.py

@@ -6,6 +6,8 @@
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_string, fmt_docstring, kwargs_to_strings, use_alias
 
+__doctest_skip__ = ["inset"]
+
 
 @fmt_docstring
 @contextlib.contextmanager

pygmt/src/select.py

@@ -11,6 +11,8 @@
     use_alias,
 )
 
+__doctest_skip__ = ["select"]
+
 
 @fmt_docstring
 @use_alias(
@@ -150,16 +152,12 @@ def select(data=None, outfile=None, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # Load a table of ship observations of bathymetry off Baja California
-    >>> data = pygmt.datasets.load_sample_data(
-    ...     name="bathymetry"
-    ... )  # doctest: +SKIP
+    >>> ship_data = pygmt.datasets.load_sample_data(name="bathymetry")
     >>> # Only return the data points that lie within the region between
     >>> # longitudes 246 and 247 and latitudes 20 and 21
-    >>> pygmt.select(
-    ...     data=ship_data, region=[246, 247, 20, 21]
-    ... )  # doctest: +SKIP
+    >>> out = pygmt.select(data=ship_data, region=[246, 247, 20, 21])
     """
 
     with GMTTempFile(suffix=".csv") as tmpfile:

pygmt/src/sph2grd.py

@@ -11,6 +11,8 @@
 )
 from pygmt.io import load_dataarray
 
+__doctest_skip__ = ["sph2grd"]
+
 
 @fmt_docstring
 @use_alias(
@@ -66,12 +68,12 @@ def sph2grd(data, **kwargs):
 
     Example
     -------
-    >>> import pygmt  # doctest: +SKIP
+    >>> import pygmt
     >>> # Create a new grid from the remote file "EGM96_to_36.txt",
     >>> # set the grid spacing to 1, and the region to "g"
     >>> new_grid = pygmt.sph2grd(
     ...     data="@EGM96_to_36.txt", spacing=1, region="g"
-    ... )  # doctest: +SKIP
+    ... )
     """
     with GMTTempFile(suffix=".nc") as tmpfile:
         with Session() as lib: