Style and formatting fixes for tutorials (#818)

*Update tutorials to use the term "arguments" when referring to PyGMT inputs
*Standardize and clean up GMT arguments and PyGMT code in doc strings
*Change line plotting tutorial file name and update index

Co-authored-by: Will Schlitzer <[email protected]>

Author: seisman

doc/index.rst

@@ -33,7 +33,7 @@
     tutorials/coastlines.rst
     tutorials/regions.rst
     tutorials/plot.rst
-    tutorials/plot-lines.rst
+    tutorials/lines.rst
     tutorials/text.rst
     tutorials/contour-map.rst
     tutorials/earth-relief.rst

examples/tutorials/3d-perspective-image.py

@@ -121,7 +121,7 @@
 ########################################################################################
 # :meth:`pygmt.Figure.colorbar` can be used to add a color bar to the figure. The
 # ``cmap`` argument does not need to be passed again. To keep the color bar's alignment
-# similar to the figure, use **True** as the ``perspective`` argument.
+# similar to the figure, use ``True`` as the ``perspective`` argument.
 
 fig = pygmt.Figure()
 fig.grdview(

examples/tutorials/coastlines.py

@@ -14,7 +14,7 @@
 # Use the ``shorelines`` argument to plot only the shorelines:
 
 fig = pygmt.Figure()
-fig.basemap(region="g", projection="W10i", frame=True)
+fig.basemap(region="g", projection="W15c", frame=True)
 fig.coast(shorelines=True)
 fig.show()
 
@@ -31,7 +31,7 @@
 # lines:
 
 fig = pygmt.Figure()
-fig.basemap(region="g", projection="W10i", frame=True)
+fig.basemap(region="g", projection="W15c", frame=True)
 fig.coast(shorelines="1/0.5p,black")
 fig.show()
 
@@ -40,7 +40,7 @@
 # ``shorelines``:
 
 fig = pygmt.Figure()
-fig.basemap(region="g", projection="W10i", frame=True)
+fig.basemap(region="g", projection="W15c", frame=True)
 fig.coast(shorelines=["1/1p,black", "2/0.5p,red"])
 fig.show()
 
@@ -60,15 +60,15 @@
 oahu = [-158.3, -157.6, 21.2, 21.8]
 fig = pygmt.Figure()
 for res in ["c", "l", "i", "h", "f"]:
-    fig.coast(resolution=res, shorelines="1p", region=oahu, projection="M5i")
-    fig.shift_origin(xshift="5i")
+    fig.coast(resolution=res, shorelines="1p", region=oahu, projection="M5c")
+    fig.shift_origin(xshift="5c")
 fig.show()
 
 ########################################################################################
 # Land and water
 # --------------
 #
-# Use the ``land`` and ``water`` attributes to specify a fill color for land and water
+# Use the ``land`` and ``water`` arguments to specify a fill color for land and water
 # bodies. The colors can be given by name or hex codes (like the ones used in HTML and
 # CSS):
 

examples/tutorials/earth-relief.py

@@ -10,7 +10,7 @@
 import pygmt
 
 ########################################################################################
-# Load sample Earth relief data for the entire globe at a resolution of 30 minutes.
+# Load sample Earth relief data for the entire globe at a resolution of 30 arc minutes.
 # The other available resolutions are show at :gmt-docs:`datasets/remote-data.html#global-earth-relief-grids`.
 grid = pygmt.datasets.load_earth_relief(resolution="30m")
 
@@ -30,7 +30,7 @@
 ########################################################################################
 #
 # :meth:`pygmt.Figure.grdimage` can take the optional argument ``projection`` for the
-# map. In the example below, the ``projection`` is set as ``"R12c"`` for 12 centimeter
+# map. In the example below, the ``projection`` is set as ``R12c`` for 12 centimeter
 # figure with a Winkel Tripel projection. For a list of available projections,
 # see :gmt-docs:`cookbook/map-projections.html`.
 
@@ -71,8 +71,8 @@
 # for :meth:`pygmt.Figure.grdimage`. The ``frame`` argument for
 # :meth:`pygmt.Figure.colorbar` can be used to set the axis intervals and labels. A
 # list is used to pass multiple arguments to ``frame``. In the example below,
-# ``"a2500"`` sets the axis interval to 2,500, ``"x+lElevation"`` sets  the x-axis
-# label, and ``"y+lm"`` sets the y-axis label.
+# ``a2500`` sets the axis interval to 2,500, ``x+lElevation`` sets the x-axis
+# label, and ``y+lm`` sets the y-axis label.
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, projection="R12c", cmap="geo")
@@ -85,11 +85,11 @@
 #
 # In addition to providing global data, the ``region`` argument for
 # :meth:`pygmt.datasets.load_earth_relief` can be used to provide data for a specific
-# area. The ``region`` argument is required for resolutions at 5 minutes or higher, and
+# area. The ``region`` argument is required for resolutions at 5 arc minutes or higher, and
 # accepts a list (as in the example below) or a string. The geographic ranges are
-# passed as *x-min*/*x-max*/*y-min*/*y-max*.
+# passed as *xmin*/*xmax*/*ymin*/*ymax*.
 #
-# The example below uses data with a 5 minute resolution, and plots it on a
+# The example below uses data with a 5 arc minute resolution, and plots it on a
 # 15 centimeter figure with a Mercator projection and a CPT set to *geo*.
 # ``frame="a"`` is used to add a frame to the figure.
 

examples/tutorials/frames.py

@@ -52,7 +52,7 @@
 # Title
 # -----
 #
-# The figure title can be set by passing **+t**\ *title* to the ``frame`` parameter of
+# The figure title can be set by passing **+t**\ *title* to the ``frame`` argument of
 # :meth:`pygmt.Figure.basemap`. Passing multiple arguments to ``frame`` can be done by
 # using a list, as show in the example below.
 
@@ -65,7 +65,7 @@
 ########################################################################################
 # To use a title with multiple words, the title must be placed inside another set of
 # quotation marks. To prevent the quotation marks from appearing in the figure title,
-# the frame argument can be passed in single quotation marks and the title can be
+# the ``frame`` argument can be passed in single quotation marks and the title can be
 # passed in double quotation marks.
 
 fig = pygmt.Figure()
@@ -78,15 +78,15 @@
 # Axis labels
 # -----------
 #
-# Axis labels can be set by passing **x+l**\ *label* (or starting with y if
-# labeling the y-axis) if  to the ``frame`` parameter of :meth:`pygmt.Figure.basemap`.
+# Axis labels can be set by passing **x+l**\ *label* (or starting with **y** if
+# labeling the y-axis) to the ``frame`` argument of :meth:`pygmt.Figure.basemap`.
 # Axis labels will be displayed on all primary axes, which the default is all sides of
 # the figure. To designate only some of the axes as primary, an argument that
 # capitlizes only the primary axes can be passed, which is ``"WSne"`` in the example
 # below. The letters correspond with west (left), south (bottom), north (top), and
 # east (right) sides of a figure.
 #
-# The example below used a Cartesian projection, as GMT does not allow axis labels to
+# The example below uses a Cartesian projection, as GMT does not allow axis labels to
 # be set for geographic maps.
 
 fig = pygmt.Figure()

examples/tutorials/plot-lines.py renamed to examples/tutorials/lines.py

@@ -11,7 +11,7 @@
 # Plot lines
 # ----------
 #
-# Create a Cartesian figure using ``projection`` parameter and set the axis scales
+# Create a Cartesian figure using ``projection`` argument and set the axis scales
 # using ``region`` (in this case, each axis is 0-10). Pass a list of ``x`` and ``y``
 # values to be plotted as a line.
 
@@ -43,7 +43,7 @@
 
 ########################################################################################
 # To plot multiple lines, :meth:`pygmt.Figure.plot` needs to be used for each
-# additional line. Parameters such as ``region``, ``projection``, and ``frame`` do
+# additional line. Arguments such as ``region``, ``projection``, and ``frame`` do
 # not need to be repeated in subsequent uses.
 
 fig = pygmt.Figure()
@@ -62,11 +62,11 @@
 # Change line attributes
 # ----------------------
 #
-# The line attributes can be set using the ``pen`` parameter. ``pen`` takes a string
+# The line attributes can be set by the ``pen`` argument. ``pen`` takes a string
 # argument with the optional values *width*,\ *color*,\ *style*.
 #
-# In the example below, the pen width is set to ``"5p"``, and with *black* as the
-# default color and *solid* as the default style.
+# In the example below, the pen width is set to ``5p``, and with ``black`` as the
+# default color and ``solid`` as the default style.
 
 fig = pygmt.Figure()
 fig.plot(
@@ -81,7 +81,7 @@
 
 ########################################################################################
 # The line color can be set and is added after the line width to the ``pen`` argument.
-# In the example below, the line color is set to "red".
+# In the example below, the line color is set to ``red``.
 
 fig = pygmt.Figure()
 fig.plot(
@@ -96,8 +96,8 @@
 
 ########################################################################################
 # The line style can be set and is added after the line width or color to the
-# ``pen`` argument.  In the example below, the line color is set to *dot dot dash*, and
-# the default color *black* is used.
+# ``pen`` argument.  In the example below, the line style is set to
+# ``..-`` (*dot dot dash*), and the default color ``black`` is used.
 
 fig = pygmt.Figure()
 fig.plot(
@@ -112,8 +112,8 @@
 
 ########################################################################################
 # The line width, color, and style can all be set in the same ``pen`` argument. In the
-# example below, the line width is set to *7p*, the color is set to *green*, and the
-# line style is *dash dot dash*.
+# example below, the line width is set to ``7p``, the color is set to ``green``, and the
+# line style is ``-.-`` (*dash dot dash*).
 #
 # For a gallery showing other ``pen`` settings, see :doc:`/gallery/line/linestyles`.
 

examples/tutorials/plot.py

@@ -35,21 +35,21 @@
 # hypocenters of the earthquakes.
 
 fig = pygmt.Figure()
-fig.basemap(region=region, projection="M8i", frame=True)
+fig.basemap(region=region, projection="M15c", frame=True)
 fig.coast(land="black", water="skyblue")
 fig.plot(x=data.longitude, y=data.latitude, style="c0.3c", color="white", pen="black")
 fig.show()
 
 ########################################################################################
 # We used the style ``c0.3c`` which means "circles of 0.3 centimeter size". The ``pen``
-# attribute controls the outline of the symbols and the ``color`` controls the fill.
+# argument controls the outline of the symbols and the ``color`` controls the fill.
 #
 # We can map the size of the circles to the earthquake magnitude by passing an array to
 # the ``sizes`` argument. Because the magnitude is on a logarithmic scale, it helps to
 # show the differences by scaling the values using a power law.
 
 fig = pygmt.Figure()
-fig.basemap(region=region, projection="M8i", frame=True)
+fig.basemap(region=region, projection="M15c", frame=True)
 fig.coast(land="black", water="skyblue")
 fig.plot(
     x=data.longitude,
@@ -76,7 +76,7 @@
 #
 
 fig = pygmt.Figure()
-fig.basemap(region=region, projection="M8i", frame=True)
+fig.basemap(region=region, projection="M15c", frame=True)
 fig.coast(land="black", water="skyblue")
 pygmt.makecpt(cmap="viridis", series=[data.depth_km.min(), data.depth_km.max()])
 fig.plot(

examples/tutorials/regions.py

@@ -14,7 +14,7 @@
 # -----------
 #
 # A string of coordinates can be passed to ``region``, in the form of
-# *xmin*\ /*xmax*\ /*ymin*\ /*ymax*\ .
+# *xmin*/*xmax*/*ymin*/*ymax*.
 
 fig = pygmt.Figure()
 fig.coast(
@@ -26,19 +26,19 @@
     land="lightgray",
     # Set the color of the water to white
     water="white",
-    # Display the national borders and set the pen-size to 0.5p
+    # Display the national borders and set the pen thickness to 0.5p
     borders="1/0.5p",
-    # Display the shorelines and set the pen-size to 0.5p
+    # Display the shorelines and set the pen thickness to 0.5p
     shorelines="1/0.5p",
-    # Set the frame to automatic and display gridlines
+    # Set the frame to display annotations and gridlines
     frame="ag",
 )
 fig.show()
 
 ########################################################################################
 #
-# The coordinates coordinates can be passed to ``region`` as a list, in the form
-# of [*xmin*\ ,\ *xmax*\ ,\ *ymin*\ ,\ *ymax*\ ].
+# The coordinates can be passed to ``region`` as a list, in the form
+# of [*xmin*,\ *xmax*,\ *ymin*,\ *ymax*].
 
 fig = pygmt.Figure()
 fig.coast(
@@ -81,7 +81,7 @@
 # region to the entire globe. The range is 180W to 180E (-180, 180) and 90S to
 # 90N (-90 to 90). With no parameters set for the projection, the figure defaults to be
 # centered at the mid-point of both x- and y-axes. Using **d**\ , the figure is
-# centered at 0,0, or the intersection of the equator and prime meridian.
+# centered at (0, 0), or the intersection of the equator and prime meridian.
 
 fig = pygmt.Figure()
 fig.coast(
@@ -99,7 +99,7 @@
 #
 # The argument **g** can be passed, which encompasses the entire globe. The range is
 # 0E to 360E (0, 360) and 90S to 90N (-90 to 90). With no parameters set for the
-# projection, the figure is centered at 180,0, or the intersection of the equator and
+# projection, the figure is centered at (180, 0), or the intersection of the equator and
 # International Date Line.
 
 fig = pygmt.Figure()
@@ -159,7 +159,7 @@
 ########################################################################################
 #
 # Instead of expanding the range of the plot uniformly in all directions, two values
-# can be passed to expand differently on each axis. The format is *xinc*\ /\ *yinc*.
+# can be passed to expand differently on each axis. The format is *xinc*/*yinc*.
 
 fig = pygmt.Figure()
 fig.coast(
@@ -179,7 +179,7 @@
 #
 # Instead of expanding the range of the plot uniformly in all directions, four values
 # can be passed to expand differently in each direction.
-# The format is *winc*\ /\ *einc*\ /\ *sinc*\ /\ *ninc*\ , which expands on the west,
+# The format is *winc*/*einc*/*sinc*/*ninc*, which expands on the west,
 # east, south, and north axes.
 
 fig = pygmt.Figure()

examples/tutorials/text.py

@@ -19,8 +19,8 @@
 #
 # Here we create a simple map and add an annotation using the ``text``, ``x``,
 # and ``y`` arguments to specify the annotation text and position in the
-# projection frame. ``text`` accepts 'str' types, while ``x``, and ``y``
-# accepts either 'int'/'float' numbers, or a list/array of numbers.
+# projection frame. ``text`` accepts *str* types, while ``x``, and ``y``
+# accepts either *int* or *float* numbers, or a list/array of numbers.
 
 fig = pygmt.Figure()
 with pygmt.config(MAP_FRAME_TYPE="plain"):
@@ -59,8 +59,8 @@
 # Plotting from a text file
 # -------------------------
 #
-# It is also possible to add annotations from a file containing `x`, `y`, and
-# `text` fields. Here we give a complete example.
+# It is also possible to add annotations from a file containing ``x``, ``y``, and
+# ``text`` fields. Here we give a complete example.
 
 fig = pygmt.Figure()
 with pygmt.config(MAP_FRAME_TYPE="plain"):
@@ -78,7 +78,7 @@
 
 # Plot region names / sea names from a text file, where
 # the longitude (x) and latitude (y) coordinates are in the first two columns.
-# Setting angle/font/justiry to True will indicate that those columns are
+# Setting angle/font/justify to ``True`` will indicate that those columns are
 # present in the text file too (Note: must be in that order!).
 # Finally, the text to be printed will be in the last column
 fig.text(textfiles="examples.txt", angle=True, font=True, justify=True)
@@ -98,8 +98,9 @@
 #
 # The anchor is specified with a two letter (order independent) code, chosen
 # from:
-# * Vertical anchor: T(op), M(iddle), B(ottom)
-# * Horizontal anchor: L(eft), C(entre), R(ight)
+#
+# * Vertical anchor: **T**\(op), **M**\(iddle), **B**\(ottom)
+# * Horizontal anchor: **L**\(eft), **C**\(entre), **R**\(ight)
 
 fig = pygmt.Figure()
 fig.basemap(region=[0, 3, 0, 3], projection="X10c", frame=["WSne", "af0.5g"])