Improve comments/descriptions of inline examples for plotting methods (#4939)

Author: seisman

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