seisman · Oct 4, 2026 · Oct 4, 2026 · seisman · Oct 4, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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,