diff --git a/.github/workflows/style_checks.yaml b/.github/workflows/style_checks.yaml index 178bd1fc200..ce204d6a537 100644 --- a/.github/workflows/style_checks.yaml +++ b/.github/workflows/style_checks.yaml @@ -76,3 +76,14 @@ jobs: rm output.txt exit $nfiles fi + + - name: Ensure "Examples" instead of "Example" is used as the docstring heading + run: | + git ls-files '*.py' | xargs grep --line-number -E '^\s*Example\s*$' > output.txt || true + nlines=$(wc --lines output.txt | awk '{print $1}') + if [[ $nlines > 0 ]]; then + echo "Use 'Examples' instead of 'Example' as the docstring heading in following lines:" + cat output.txt + rm output.txt + exit $nlines + fi diff --git a/pygmt/src/blockm.py b/pygmt/src/blockm.py index 4e74a8826db..746d5422a49 100644 --- a/pygmt/src/blockm.py +++ b/pygmt/src/blockm.py @@ -167,8 +167,8 @@ def blockmean( - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set (depends on ``output_type``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a table of ship observations of bathymetry off Baja California >>> data = pygmt.datasets.load_sample_data(name="bathymetry") @@ -281,8 +281,8 @@ def blockmedian( - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set (depends on ``output_type``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a table of ship observations of bathymetry off Baja California >>> data = pygmt.datasets.load_sample_data(name="bathymetry") @@ -404,8 +404,8 @@ def blockmode( - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set (depends on ``output_type``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a table of ship observations of bathymetry off Baja California >>> data = pygmt.datasets.load_sample_data(name="bathymetry") diff --git a/pygmt/src/coast.py b/pygmt/src/coast.py index 4190cb5f707..3c030ceaf9f 100644 --- a/pygmt/src/coast.py +++ b/pygmt/src/coast.py @@ -24,8 +24,8 @@ def _alias_option_C(lakes=None, river_lakes=None): # ruff: ignore[invalid-funct """ Helper function to create the alias list for the -C option. - Example - ------- + Examples + -------- >>> def parse(**kwargs): ... return AliasSystem(C=_alias_option_C(**kwargs)).get("C") >>> parse() @@ -274,8 +274,8 @@ def coast( pygmt.Figure.scalebar Add a scale bar. - Example - ------- + Examples + -------- >>> import pygmt >>> from pygmt.params import Axis >>> # Create a new plot with pygmt.Figure() diff --git a/pygmt/src/colorbar.py b/pygmt/src/colorbar.py index 9d264e42787..facb712157f 100644 --- a/pygmt/src/colorbar.py +++ b/pygmt/src/colorbar.py @@ -470,8 +470,8 @@ def colorbar( $perspective $transparency - Example - ------- + Examples + -------- >>> import pygmt >>> # Create a new figure instance with pygmt.Figure() >>> fig = pygmt.Figure() diff --git a/pygmt/src/dimfilter.py b/pygmt/src/dimfilter.py index 2797b550beb..22532629871 100644 --- a/pygmt/src/dimfilter.py +++ b/pygmt/src/dimfilter.py @@ -128,8 +128,8 @@ def dimfilter( - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a grid of Earth relief data >>> grid = pygmt.datasets.load_earth_relief() diff --git a/pygmt/src/grd2cpt.py b/pygmt/src/grd2cpt.py index f7ad10fc258..8f1a8b80fcb 100644 --- a/pygmt/src/grd2cpt.py +++ b/pygmt/src/grd2cpt.py @@ -186,8 +186,8 @@ def grd2cpt( $region $verbose - Example - ------- + Examples + -------- >>> import pygmt >>> # load the 30 arc-minutes grid with "gridline" registration >>> grid = pygmt.datasets.load_earth_relief("30m", registration="gridline") diff --git a/pygmt/src/grd2xyz.py b/pygmt/src/grd2xyz.py index 64cc92d0fc3..3f9e1ce2f2a 100644 --- a/pygmt/src/grd2xyz.py +++ b/pygmt/src/grd2xyz.py @@ -132,8 +132,8 @@ def grd2xyz( - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set (depends on ``output_type``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a grid of @earth_relief_30m data, with a longitude range of >>> # 10° E to 30° E, and a latitude range of 15° N to 25° N diff --git a/pygmt/src/grdclip.py b/pygmt/src/grdclip.py index 19c4c6d2c8d..bf81c1c1127 100644 --- a/pygmt/src/grdclip.py +++ b/pygmt/src/grdclip.py @@ -91,8 +91,8 @@ def grdclip( - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load the 30 arc-minutes Earth relief grid, with a longitude range of 10° E to >>> # 30° E, and a latitude range of 15° N to 25° N diff --git a/pygmt/src/grdcontour.py b/pygmt/src/grdcontour.py index 954f75b658c..5fdca25528a 100644 --- a/pygmt/src/grdcontour.py +++ b/pygmt/src/grdcontour.py @@ -126,8 +126,8 @@ def grdcontour( $perspective $transparency - Example - ------- + Examples + -------- >>> import pygmt >>> from pygmt.params import Axis >>> # Load the 15 arc-minutes grid with "gridline" registration in the diff --git a/pygmt/src/grdcut.py b/pygmt/src/grdcut.py index 5f789916734..5521873ed26 100644 --- a/pygmt/src/grdcut.py +++ b/pygmt/src/grdcut.py @@ -101,8 +101,8 @@ def grdcut( - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a grid of @earth_relief_30m data, with a longitude range of >>> # 10° E to 30° E, and a latitude range of 15° N to 25° N diff --git a/pygmt/src/grdfill.py b/pygmt/src/grdfill.py index 3bb2bbd0f80..e4ce7ed565e 100644 --- a/pygmt/src/grdfill.py +++ b/pygmt/src/grdfill.py @@ -101,8 +101,8 @@ def grdfill( - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by ``outgrid``) - Example - ------- + Examples + -------- Fill holes in a bathymetric grid with a constant value of 20. >>> import pygmt diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py index eb0633a148c..319ce31a2e7 100644 --- a/pygmt/src/grdgradient.py +++ b/pygmt/src/grdgradient.py @@ -218,8 +218,8 @@ def grdgradient( - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a grid of @earth_relief_30m data, with a longitude range of >>> # 10° E to 30° E, and a latitude range of 15° N to 25° N diff --git a/pygmt/src/grdhisteq.py b/pygmt/src/grdhisteq.py index b471e5808b0..b7c9e6ff981 100644 --- a/pygmt/src/grdhisteq.py +++ b/pygmt/src/grdhisteq.py @@ -106,8 +106,8 @@ def equalize_grid( - :class:`xarray.DataArray` if ``outgrid`` is ``None`` - ``None`` if ``outgrid`` is a str (grid output is stored in ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a grid of @earth_relief_30m data, with a longitude range >>> # of 10°E to 30°E, and a latitude range of 15°N to 25°N @@ -203,8 +203,8 @@ def compute_bins( - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set (depends on ``output_type``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a grid of @earth_relief_30m data, with a longitude range of >>> # 10° E to 30° E, and a latitude range of 15° N to 25° N diff --git a/pygmt/src/grdimage.py b/pygmt/src/grdimage.py index 4ae502ef157..1b37ff33968 100644 --- a/pygmt/src/grdimage.py +++ b/pygmt/src/grdimage.py @@ -158,8 +158,8 @@ def grdimage( $transparency $cores - Example - ------- + Examples + -------- >>> import pygmt >>> from pygmt.params import Axis >>> # load the 30 arc-minutes grid with "gridline" registration diff --git a/pygmt/src/grdlandmask.py b/pygmt/src/grdlandmask.py index 4300d00ef17..63e479a42d9 100644 --- a/pygmt/src/grdlandmask.py +++ b/pygmt/src/grdlandmask.py @@ -111,8 +111,8 @@ def grdlandmask( - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Create a landmask grid with a longitude range of 125° E to 130° E, a >>> # latitude range of 30° N to 35° N, and a grid spacing of 1 arc-degree diff --git a/pygmt/src/grdmask.py b/pygmt/src/grdmask.py index 4c23e82c955..08a2e065254 100644 --- a/pygmt/src/grdmask.py +++ b/pygmt/src/grdmask.py @@ -191,8 +191,8 @@ def grdmask( - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> import numpy as np >>> # Create a simple polygon as a triangle diff --git a/pygmt/src/grdproject.py b/pygmt/src/grdproject.py index f4643e1cbc8..44dab646255 100644 --- a/pygmt/src/grdproject.py +++ b/pygmt/src/grdproject.py @@ -107,8 +107,8 @@ def grdproject( - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a grid of @earth_relief_30m data, with a longitude range of >>> # 10° E to 30° E, and a latitude range of 15° N to 25° N diff --git a/pygmt/src/grdsample.py b/pygmt/src/grdsample.py index 3d53f6d6542..ac9aa2bb043 100644 --- a/pygmt/src/grdsample.py +++ b/pygmt/src/grdsample.py @@ -96,8 +96,8 @@ def grdsample( - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a grid of @earth_relief_30m data, with a longitude range of >>> # 10° E to 30° E, and a latitude range of 15° N to 25° N diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index da92a32d829..578779ba72c 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -282,8 +282,8 @@ def grdtrack( - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set (depends on ``output_type``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a grid of @earth_relief_30m data, with a longitude range of >>> # -118° E to -107° E, and a latitude range of -49° N to -42° N diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py index e1df76a1674..a98f5682a40 100644 --- a/pygmt/src/grdview.py +++ b/pygmt/src/grdview.py @@ -253,8 +253,8 @@ def grdview( $perspective $transparency - Example - ------- + Examples + -------- >>> import pygmt >>> from pygmt.params import Axis, Frame >>> # Load the 30 arc-minutes grid with "gridline" registration in a given region diff --git a/pygmt/src/grdvolume.py b/pygmt/src/grdvolume.py index c8470297b57..5e96ccbedd6 100644 --- a/pygmt/src/grdvolume.py +++ b/pygmt/src/grdvolume.py @@ -81,8 +81,8 @@ def grdvolume( - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set (depends on ``output_type``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a grid of @earth_relief_30m data, with a longitude range of >>> # 10° E to 30° E, and a latitude range of 15° N to 25° N diff --git a/pygmt/src/nearneighbor.py b/pygmt/src/nearneighbor.py index e5e46802d62..94ef2af0480 100644 --- a/pygmt/src/nearneighbor.py +++ b/pygmt/src/nearneighbor.py @@ -140,8 +140,9 @@ def nearneighbor( - :class:`xarray.DataArray`: if ``outgrid`` is not set - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by ``outgrid``) - Example - ------- + + Examples + -------- >>> import pygmt >>> # Load a sample dataset of bathymetric x, y, and z values >>> data = pygmt.datasets.load_sample_data(name="bathymetry") diff --git a/pygmt/src/select.py b/pygmt/src/select.py index 44676ca2a68..db9c32cd9aa 100644 --- a/pygmt/src/select.py +++ b/pygmt/src/select.py @@ -207,8 +207,8 @@ def select( - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set (depends on ``output_type``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a table of ship observations of bathymetry off Baja California >>> ship_data = pygmt.datasets.load_sample_data(name="bathymetry") diff --git a/pygmt/src/solar.py b/pygmt/src/solar.py index 4064c7b6aef..37bdee5157e 100644 --- a/pygmt/src/solar.py +++ b/pygmt/src/solar.py @@ -86,8 +86,8 @@ def solar( $perspective $transparency - Example - ------- + Examples + -------- Plot the day-night terminator at the current UTC date and time. diff --git a/pygmt/src/sph2grd.py b/pygmt/src/sph2grd.py index 72b3c3769b0..4bd768853a8 100644 --- a/pygmt/src/sph2grd.py +++ b/pygmt/src/sph2grd.py @@ -71,8 +71,8 @@ def sph2grd( - None if ``outgrid`` is set (grid output will be stored in file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Create a new grid from the remote file "EGM96_to_36.txt", >>> # set the grid spacing to 1 arc-degree, and the region to global ("g") diff --git a/pygmt/src/sphdistance.py b/pygmt/src/sphdistance.py index 336df63055c..7ba6e027b15 100644 --- a/pygmt/src/sphdistance.py +++ b/pygmt/src/sphdistance.py @@ -109,8 +109,8 @@ def sphdistance( - None if ``outgrid`` is set (grid output will be stored in file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import numpy as np >>> import pygmt >>> # Create an array of longitude/latitude coordinates diff --git a/pygmt/src/sphinterpolate.py b/pygmt/src/sphinterpolate.py index 124642c034a..8278bc00299 100644 --- a/pygmt/src/sphinterpolate.py +++ b/pygmt/src/sphinterpolate.py @@ -65,8 +65,8 @@ def sphinterpolate( - None if ``outgrid`` is set (grid output will be stored in file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a table of Mars with longitude/latitude/radius columns >>> mars_shape = pygmt.datasets.load_sample_data(name="mars_shape") diff --git a/pygmt/src/surface.py b/pygmt/src/surface.py index 26d71875278..742061b25ea 100644 --- a/pygmt/src/surface.py +++ b/pygmt/src/surface.py @@ -162,8 +162,8 @@ def surface( - None if ``outgrid`` is set (grid output will be stored in file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import pygmt >>> # Load a sample table of topography >>> topography = pygmt.datasets.load_sample_data(name="notre_dame_topography") diff --git a/pygmt/src/xyz2grd.py b/pygmt/src/xyz2grd.py index 8d8e1efb450..040d2d88ae7 100644 --- a/pygmt/src/xyz2grd.py +++ b/pygmt/src/xyz2grd.py @@ -146,8 +146,8 @@ def xyz2grd( - None if ``outgrid`` is set (grid output will be stored in file set by ``outgrid``) - Example - ------- + Examples + -------- >>> import numpy as np >>> import pygmt >>> # generate a grid for z=x**2+y**2, with an x-range of 0 to 3,