From 620bed27282d5e5ac27a4e3175abe39601d370f8 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sun, 4 Oct 2026 15:24:23 +0800
Subject: [PATCH 1/3] Improve comments/descriptions of doctest examples for
 plotting methods

---
 pygmt/src/basemap.py          |  2 ++
 pygmt/src/choropleth.py       |  2 ++
 pygmt/src/coast.py            | 21 ++++++---------------
 pygmt/src/colorbar.py         |  6 ++----
 pygmt/src/contour.py          |  4 ++--
 pygmt/src/directional_rose.py |  2 ++
 pygmt/src/fill_between.py     |  3 +++
 pygmt/src/grdcontour.py       | 17 ++++-------------
 pygmt/src/grdimage.py         | 12 +++++-------
 pygmt/src/grdview.py          | 15 ++++-----------
 pygmt/src/histogram.py        |  1 +
 pygmt/src/hlines.py           |  3 +++
 pygmt/src/image.py            |  4 ++--
 pygmt/src/magnetic_rose.py    |  2 ++
 pygmt/src/paragraph.py        |  2 ++
 pygmt/src/plot.py             |  8 ++++----
 pygmt/src/scalebar.py         |  2 ++
 pygmt/src/solar.py            |  1 -
 pygmt/src/tilemap.py          |  4 ++--
 pygmt/src/vlines.py           |  3 +++
 pygmt/src/wiggle.py           |  2 ++
 21 files changed, 55 insertions(+), 61 deletions(-)

diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py
index aa9163a2713..8bdc05f4757 100644
--- a/pygmt/src/basemap.py
+++ b/pygmt/src/basemap.py
@@ -142,6 +142,8 @@ def basemap(
 
     Examples
     --------
+    Plot a basic map with a specified region, projection, and frame settings.
+
     >>> import pygmt
     >>> fig = pygmt.Figure()
     >>> fig.basemap(region="g", projection="H15c", frame=True)
diff --git a/pygmt/src/choropleth.py b/pygmt/src/choropleth.py
index 812271dc51f..a28d524acfe 100644
--- a/pygmt/src/choropleth.py
+++ b/pygmt/src/choropleth.py
@@ -87,6 +87,8 @@ def choropleth(
 
     Examples
     --------
+    Plot a choropleth map of the world based on population estimates.
+
     >>> import geopandas
     >>> import pygmt
     >>> world = geopandas.read_file(
diff --git a/pygmt/src/coast.py b/pygmt/src/coast.py
index 4190cb5f707..5d77252dbe1 100644
--- a/pygmt/src/coast.py
+++ b/pygmt/src/coast.py
@@ -278,24 +278,15 @@ def coast(
     -------
     >>> import pygmt
     >>> from pygmt.params import Axis
-    >>> # Create a new plot with pygmt.Figure()
     >>> fig = pygmt.Figure()
-    >>> # Call the coast method for the plot
-    >>> fig.coast(
-    ...     # Set the projection to Mercator, and the plot width to 10 centimeters
-    ...     projection="M10c",
-    ...     # Set the region of the plot
-    ...     region=[-10, 30, 30, 60],
-    ...     # Set the frame of the plot, here annotations and major ticks
+    >>> fig.coast()
+    ...     projection="M10c",  # Set the Mercator projection and width to 10 cm
+    ...     region=[-10, 30, 30, 60],  # Set the map region
     ...     frame=Axis(annot=True),
-    ...     # Set the color of the land to "darkgreen"
-    ...     land="darkgreen",
-    ...     # Set the color of the water to "lightblue"
-    ...     water="lightblue",
-    ...     # Draw national borders with a 1-point black line
-    ...     borders="1/1p,black",
+    ...     land="darkgreen",  # Set the color of the land area
+    ...     water="lightblue",  # Set the color of the water area
+    ...     borders="1/1p,black",  # Draw national borders with a 1-point black line
     ... )
-    >>> # Show the plot
     >>> fig.show()
     """
     if (
diff --git a/pygmt/src/colorbar.py b/pygmt/src/colorbar.py
index 9d264e42787..b78bc51a0ff 100644
--- a/pygmt/src/colorbar.py
+++ b/pygmt/src/colorbar.py
@@ -472,14 +472,12 @@ def colorbar(
 
     Example
     -------
+    Add a colorbar with a specified colormap, label, and unit on a plot.
+
     >>> import pygmt
-    >>> # Create a new figure instance with pygmt.Figure()
     >>> fig = pygmt.Figure()
-    >>> # Create a basemap
     >>> fig.basemap(region=[0, 10, 0, 3], projection="X10c/3c", frame=True)
-    >>> # Call the colorbar method for the plot
     >>> fig.colorbar(cmap="SCM/roma", label="Velocity", unit="m/s")
-    >>> # Show the plot
     >>> fig.show()
     """
     position = _parse_position(
diff --git a/pygmt/src/contour.py b/pygmt/src/contour.py
index 0493c56eb90..add8529d9cb 100644
--- a/pygmt/src/contour.py
+++ b/pygmt/src/contour.py
@@ -156,8 +156,8 @@ def contour(
 
     Examples
     --------
-    Plot contours every 20 units and annotate every other contour (i.e., every 40
-    units) from data points given as three 1-D arrays:
+    Plot contours every 20 units and annotate every other contour (i.e., every 40 units)
+    from data points given as three 1-D arrays:
 
     >>> import numpy as np
     >>> import pygmt
diff --git a/pygmt/src/directional_rose.py b/pygmt/src/directional_rose.py
index 9407e22c5a4..b0271bca5b2 100644
--- a/pygmt/src/directional_rose.py
+++ b/pygmt/src/directional_rose.py
@@ -81,6 +81,8 @@ def directional_rose(
 
     Examples
     --------
+    Add a directional rose to a map with default settings on a map.
+
     >>> import pygmt
     >>> fig = pygmt.Figure()
     >>> fig.basemap(region=[0, 80, 0, 30], projection="M10c", frame=True)
diff --git a/pygmt/src/fill_between.py b/pygmt/src/fill_between.py
index 48c89c91cdc..d74d2cb7bcd 100644
--- a/pygmt/src/fill_between.py
+++ b/pygmt/src/fill_between.py
@@ -97,6 +97,9 @@ def fill_between(
 
     Examples
     --------
+    Fill between two curves with specified colors and draw the curves with custom pen
+    styles.
+
     >>> import numpy as np
     >>> import pygmt
     >>> x = np.linspace(0, 2 * np.pi, 200)
diff --git a/pygmt/src/grdcontour.py b/pygmt/src/grdcontour.py
index 954f75b658c..317dac28cee 100644
--- a/pygmt/src/grdcontour.py
+++ b/pygmt/src/grdcontour.py
@@ -130,29 +130,20 @@ def grdcontour(
     -------
     >>> import pygmt
     >>> from pygmt.params import Axis
-    >>> # Load the 15 arc-minutes grid with "gridline" registration in the
-    >>> # specified region
+    >>> # Load the 15 arc-minutes grid with "gridline" registration in a given region
     >>> grid = pygmt.datasets.load_earth_relief(
     ...     resolution="15m",
     ...     region=[-92.5, -82.5, -3, 7],
     ...     registration="gridline",
     ... )
-    >>> # Create a new plot with pygmt.Figure()
     >>> fig = pygmt.Figure()
-    >>> # Create the contour plot
     >>> fig.grdcontour(
-    ...     # Pass in the grid downloaded above
-    ...     grid=grid,
-    ...     # Set the interval for contour lines at 250 meters
-    ...     levels=250,
-    ...     # Set the interval for annotated contour lines at 1,000 meters
-    ...     annotation=1000,
-    ...     # Add a frame for the plot
+    ...     grid=grid,s
+    ...     levels=250,  # Set the interval for contour lines
+    ...     annotation=1000,  # Set the interval for annotated contour lines
     ...     frame=Axis(annot=True),
-    ...     # Set the projection to Mercator, and the plot width to 10 centimeters
     ...     projection="M10c",
     ... )
-    >>> # Show the plot
     >>> fig.show()
     """
     # Specify levels for the annotation and levels parameters.
diff --git a/pygmt/src/grdimage.py b/pygmt/src/grdimage.py
index 4ae502ef157..4187f3e6b94 100644
--- a/pygmt/src/grdimage.py
+++ b/pygmt/src/grdimage.py
@@ -160,21 +160,19 @@ def grdimage(
 
     Example
     -------
+    Plot the global Earth relief using a Mollweide projection.
+
     >>> import pygmt
     >>> from pygmt.params import Axis
-    >>> # load the 30 arc-minutes grid with "gridline" registration
+    >>> # Load the 30 arc-minutes grid with "gridline" registration
     >>> grid = pygmt.datasets.load_earth_relief("30m", registration="gridline")
-    >>> # create a new plot with pygmt.Figure()
     >>> fig = pygmt.Figure()
-    >>> # pass in the grid and set the CPT to "geo"
-    >>> # set the projection to Mollweide and the size to 10 cm
     >>> fig.grdimage(
     ...     grid=grid,
-    ...     cmap="gmt/geo",
-    ...     projection="W10c",
+    ...     cmap="gmt/geo",  # Use the built-in "gmt/geo" CPT
+    ...     projection="W10c",  # Set the Mollweide projection and width of 10 cm
     ...     frame=Axis(annot=True, grid=True),
     ... )
-    >>> # show the plot
     >>> fig.show()
     """
     # Do not support -A option
diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py
index e1df76a1674..5997d5e3be6 100644
--- a/pygmt/src/grdview.py
+++ b/pygmt/src/grdview.py
@@ -263,27 +263,20 @@ def grdview(
     ...     region=[-92.5, -82.5, -3, 7],
     ...     registration="gridline",
     ... )
-    >>> # Create a new figure instance with pygmt.Figure()
     >>> fig = pygmt.Figure()
-    >>> # Create the contour plot
     >>> fig.grdview(
-    ...     # Pass in the grid downloaded above
     ...     grid=grid,
     ...     # Set the perspective to an azimuth of 130° and an elevation of 30°
-    ...     perspective=[130, 30],
+    ...     perspective=(130, 30),
     ...     # Add a frame to the x- and y-axes
     ...     # Specify annotations on the south and east borders of the plot
     ...     frame=Frame(axes="wSnE", xaxis=Axis(annot=True), yaxis=Axis(annot=True)),
     ...     # Set the projection of the 2-D map to Mercator with a 10 cm width
     ...     projection="M10c",
-    ...     # Set the vertical scale (z-axis) to 2 cm
-    ...     zsize="2c",
-    ...     # Set "surface plot" to color the surface via a CPT
-    ...     surftype="surface",
-    ...     # Specify CPT to "geo"
-    ...     cmap="gmt/geo",
+    ...     zsize="2c",  # Set the vertical scale (z-axis) to 2 cm
+    ...     surftype="surface",  # Set "surface plot" to color the surface via a CPT
+    ...     cmap="gmt/geo",  # Specify CPT to "geo"
     ... )
-    >>> # Show the plot
     >>> fig.show()
     """
     # Enable 'plane' if 'facade_fill' or 'facade_pen' are set
diff --git a/pygmt/src/histogram.py b/pygmt/src/histogram.py
index b73880777d5..265185dc491 100644
--- a/pygmt/src/histogram.py
+++ b/pygmt/src/histogram.py
@@ -236,6 +236,7 @@ def histogram(
 
     Examples
     --------
+    Plot a histogram of randomly generated data with custom fill color and pen style.
 
     >>> import numpy as np
     >>> import pygmt
diff --git a/pygmt/src/hlines.py b/pygmt/src/hlines.py
index cc563dc2073..50f53e21b59 100644
--- a/pygmt/src/hlines.py
+++ b/pygmt/src/hlines.py
@@ -71,6 +71,9 @@ def hlines(
 
     Examples
     --------
+    Plot several horizontal lines at different y-coordinates with varying x-limits and
+    pen styles. Lines are labeled and a legend is displayed.
+
     >>> import pygmt
     >>> fig = pygmt.Figure()
     >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True)
diff --git a/pygmt/src/image.py b/pygmt/src/image.py
index 297d7eee675..d291b155609 100644
--- a/pygmt/src/image.py
+++ b/pygmt/src/image.py
@@ -166,8 +166,8 @@ def image(
     >>> fig.image("@circuit.png")
     >>> fig.show()
 
-    Place the image at the Top Right corner of an existing basemap, scale it to a
-    width of 3 centimeters, and draw a box around it:
+    Place the image at the Top Right corner of an existing basemap, scale it to a width
+    of 3 centimeters, and draw a box around it:
 
     >>> fig = pygmt.Figure()
     >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c", frame=True)
diff --git a/pygmt/src/magnetic_rose.py b/pygmt/src/magnetic_rose.py
index b670d6d013a..4bfc0790908 100644
--- a/pygmt/src/magnetic_rose.py
+++ b/pygmt/src/magnetic_rose.py
@@ -90,6 +90,8 @@ def magnetic_rose(
 
     Examples
     --------
+    Plot a magnetic rose with custom position, width, labels, intervals, and pen styles.
+
     >>> import pygmt
     >>> from pygmt.params import Position
     >>> fig = pygmt.Figure()
diff --git a/pygmt/src/paragraph.py b/pygmt/src/paragraph.py
index 82c87a0cc0d..30ef8953b28 100644
--- a/pygmt/src/paragraph.py
+++ b/pygmt/src/paragraph.py
@@ -101,6 +101,8 @@ def paragraph(
 
     Examples
     --------
+    Typeset a paragraph of text within a specified width and line spacing on a plot.
+
     >>> import pygmt
     >>>
     >>> fig = pygmt.Figure()
diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py
index 136887531cc..952e43b7ada 100644
--- a/pygmt/src/plot.py
+++ b/pygmt/src/plot.py
@@ -254,16 +254,16 @@ def plot(  # ruff: ignore[too-many-branches]
 
     Examples
     --------
-    Plot a blue line connecting the data points and then plot the data points as
-    red circles on top:
+    Plot a blue line connecting the data points and then plot the data points as red
+    circles on top:
 
     >>> import pygmt
     >>> x = [1, 3, 5, 7, 9]
     >>> y = [2, 6, 4, 8, 5]
     >>> fig = pygmt.Figure()
     >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c", frame=True)
-    >>> fig.plot(x=x, y=y, pen="1p,blue")
-    >>> fig.plot(x=x, y=y, style="c0.3c", fill="cyan", pen="0.5p,black")
+    >>> fig.plot(x=x, y=y, pen="1p,blue")  # Line
+    >>> fig.plot(x=x, y=y, style="c0.3c", fill="cyan", pen="0.5p,black")  # Circle
     >>> fig.show()
     """
     # TODO(GMT>6.5.0): Remove the note for the upstream bug of the "straight_line"
diff --git a/pygmt/src/scalebar.py b/pygmt/src/scalebar.py
index 2b552cfbfeb..6e5dce8e975 100644
--- a/pygmt/src/scalebar.py
+++ b/pygmt/src/scalebar.py
@@ -97,6 +97,8 @@ def scalebar(
 
     Examples
     --------
+    Add a scale bar to a map with specified length, position, and styling options.
+
     >>> import pygmt
     >>> from pygmt.params import Position
     >>> fig = pygmt.Figure()
diff --git a/pygmt/src/solar.py b/pygmt/src/solar.py
index 68592f914b1..62ba199bfba 100644
--- a/pygmt/src/solar.py
+++ b/pygmt/src/solar.py
@@ -88,7 +88,6 @@ def solar(
 
     Example
     -------
-
     Plot the day-night terminator at the current UTC date and time.
 
     >>> import datetime
diff --git a/pygmt/src/tilemap.py b/pygmt/src/tilemap.py
index bc5236e5c41..5577cdbdbe8 100644
--- a/pygmt/src/tilemap.py
+++ b/pygmt/src/tilemap.py
@@ -127,8 +127,8 @@ def tilemap(
     >>> import contextily
     >>> import pygmt
 
-    Plot a tile map of Honolulu, Hawaii using the default OpenStreetMap Humanitarian
-    web tiles:
+    Plot a tile map of Honolulu, Hawaii using the default OpenStreetMap Humanitarian web
+    tiles:
 
     >>> fig = pygmt.Figure()
     >>> fig.tilemap(
diff --git a/pygmt/src/vlines.py b/pygmt/src/vlines.py
index f6633651396..a255bd9fb50 100644
--- a/pygmt/src/vlines.py
+++ b/pygmt/src/vlines.py
@@ -71,6 +71,9 @@ def vlines(
 
     Examples
     --------
+    Plot several vertical lines at different x-coordinates with varying y-limits and
+    pen styles. Lines are labeled and a legend is displayed.
+
     >>> import pygmt
     >>> fig = pygmt.Figure()
     >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True)
diff --git a/pygmt/src/wiggle.py b/pygmt/src/wiggle.py
index 9bee4b56a7d..791f3e8b723 100644
--- a/pygmt/src/wiggle.py
+++ b/pygmt/src/wiggle.py
@@ -134,6 +134,8 @@ def wiggle(
 
     Examples
     --------
+    Draw a wiggle plot with positive and negative fills, a track, and a vertical scale.
+
     >>> import numpy as np
     >>> import pygmt
     >>>

From 7c31a48f231d8c32d3bdb9630124348098666b7a Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sun, 4 Oct 2026 15:42:12 +0800
Subject: [PATCH 2/3] Fix two more plotting methods

---
 pygmt/src/coast.py   | 2 ++
 pygmt/src/grdview.py | 6 ++++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/pygmt/src/coast.py b/pygmt/src/coast.py
index 5d77252dbe1..3c9c835ca0c 100644
--- a/pygmt/src/coast.py
+++ b/pygmt/src/coast.py
@@ -276,6 +276,8 @@ def coast(
 
     Example
     -------
+    Plot a map with coastlines, land, water, and other features.
+
     >>> import pygmt
     >>> from pygmt.params import Axis
     >>> fig = pygmt.Figure()
diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py
index 5997d5e3be6..e046b3565c4 100644
--- a/pygmt/src/grdview.py
+++ b/pygmt/src/grdview.py
@@ -253,8 +253,10 @@ def grdview(
     $perspective
     $transparency
 
-    Example
-    -------
+    Examples
+    --------
+    Create a 3-D surface plot of the Earth's relief.
+
     >>> import pygmt
     >>> from pygmt.params import Axis, Frame
     >>> # Load the 30 arc-minutes grid with "gridline" registration in a given region

From 15b1ef6651f68af6522e8b9f0cdc5ea552f7972a Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sun, 4 Oct 2026 15:44:00 +0800
Subject: [PATCH 3/3] Remove one unneeded blank line from Figure.shift_origin

---
 pygmt/src/shift_origin.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py
index 97429dd5776..242040df24b 100644
--- a/pygmt/src/shift_origin.py
+++ b/pygmt/src/shift_origin.py
@@ -67,7 +67,6 @@ def shift_origin(
 
     Examples
     --------
-
     Shifting the plot origin permanently:
 
     >>> import pygmt