Improve comments/descriptions of inline examples for plotting methods

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)

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(

pygmt/src/coast.py

@@ -276,26 +276,19 @@ def coast(
 
     Examples
     --------
+    Plot a map with coastlines, land, water, and other features.
+
     >>> 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 (

pygmt/src/colorbar.py

@@ -472,14 +472,12 @@ def colorbar(
 
     Examples
     --------
+    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(

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

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)

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)

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.

pygmt/src/grdimage.py

@@ -160,21 +160,19 @@ def grdimage(
 
     Examples
     --------
+    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

pygmt/src/grdview.py

@@ -255,6 +255,8 @@ def grdview(
 
     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
@@ -263,27 +265,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

pygmt/src/histogram.py

@@ -368,6 +368,7 @@ def histogram(
 
     Examples
     --------
+    Plot a histogram of randomly generated data with custom fill color and pen style.
 
     >>> import numpy as np
     >>> import pygmt

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)

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)

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()

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()

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"

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()

pygmt/src/shift_origin.py

@@ -67,7 +67,6 @@ def shift_origin(
 
     Examples
     --------
-
     Shifting the plot origin permanently:
 
     >>> import pygmt

pygmt/src/solar.py

@@ -88,7 +88,6 @@ def solar(
 
     Examples
     --------
-
     Plot the day-night terminator at the current UTC date and time.
 
     >>> import datetime

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(

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)

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
     >>>