DOC/tutorial "Plotting lines": General improvements (#3587)

Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Michael Grund <[email protected]>

examples/tutorials/basics/lines.py

@@ -2,7 +2,7 @@
 Plotting lines
 ==============
 
-Plotting lines is handled by :meth:`pygmt.Figure.plot`.
+Plotting lines is handled by the :meth:`pygmt.Figure.plot` method.
 """
 
 # %%
@@ -12,123 +12,93 @@
 # Plot lines
 # ----------
 #
-# Create a Cartesian figure using ``projection`` parameter 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.
+# Create a Cartesian figure using the :meth:`pygmt.Figure.basemap` method. Pass lists
+# containing two values to the ``x`` and ``y`` parameters of the
+# :meth:`pygmt.Figure.plot` method. By default, a 0.25-points thick, black, solid
+# line is drawn between these two data points.
 
 fig = pygmt.Figure()
-fig.plot(
-    region=[0, 10, 0, 10],
-    projection="X15c/10c",
-    frame="a",
-    x=[1, 8],
-    y=[5, 9],
-    pen="1p,black",
-)
+fig.basemap(region=[0, 10, 0, 10], projection="X15c/10c", frame=True)
+
+fig.plot(x=[1, 5], y=[5, 9])
+
 fig.show()
 
 # %%
-# Additional line segments can be added by including additional values for
-# ``x`` and ``y``.
+# Additional line segments can be added by including more data points in the lists
+# passed to ``x`` and ``y``.
 
 fig = pygmt.Figure()
-fig.plot(
-    region=[0, 10, 0, 10],
-    projection="X15c/10c",
-    frame="a",
-    x=[1, 6, 9],
-    y=[5, 7, 4],
-    pen="1p,black",
-)
+fig.basemap(region=[0, 10, 0, 10], projection="X15c/10c", frame=True)
+
+fig.plot(x=[1, 5, 8], y=[5, 9, 4])
+
 fig.show()
 
 # %%
-# To plot multiple lines, :meth:`pygmt.Figure.plot` needs to be used for each
-# additional line. Parameters such as ``region``, ``projection``, and ``frame``
-# do not need to be repeated in subsequent uses.
+# To plot multiple lines, :meth:`pygmt.Figure.plot` needs to be used for each line
+# separately.
 
 fig = pygmt.Figure()
-fig.plot(
-    region=[0, 10, 0, 10],
-    projection="X15c/10c",
-    frame="a",
-    x=[1, 6, 9],
-    y=[5, 7, 4],
-    pen="2p,blue",
-)
-fig.plot(x=[2, 4, 10], y=[3, 8, 9], pen="2p,red")
+fig.basemap(region=[0, 10, 0, 10], projection="X15c/10c", frame=True)
+
+fig.plot(x=[1, 5, 8], y=[5, 9, 4])
+fig.plot(x=[2, 4, 9], y=[3, 7, 5])
+
 fig.show()
 
 
 # %%
 # Change line attributes
 # ----------------------
 #
-# The line attributes can be set by the ``pen`` parameter. ``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.
+# The line attributes can be set by the ``pen`` parameter which takes a string
+# argument with the optional values *width*,\ *color*,\ *style*.
 
 fig = pygmt.Figure()
-fig.plot(
-    region=[0, 10, 0, 10],
-    projection="X15c/10c",
-    frame="a",
-    x=[1, 8],
-    y=[3, 9],
-    pen="5p",
-)
+fig.basemap(region=[0, 10, 0, 10], projection="X15c/10c", frame=True)
+
+# Set the pen width to "5p" (5 points), and use the default color "black" and the
+# default style "solid"
+fig.plot(x=[1, 8], y=[3, 9], pen="5p")
+
 fig.show()
 
 # %%
 # The line color can be set and is added after the line width to the ``pen``
-# parameter. In the example below, the line color is set to ``red``.
+# parameter.
 
 fig = pygmt.Figure()
-fig.plot(
-    region=[0, 10, 0, 10],
-    projection="X15c/10c",
-    frame="a",
-    x=[1, 8],
-    y=[3, 9],
-    pen="5p,red",
-)
+fig.basemap(region=[0, 10, 0, 10], projection="X15c/10c", frame=True)
+
+# Set the line color to "red", use the default style "solid"
+fig.plot(x=[1, 8], y=[3, 9], pen="5p,red")
+
 fig.show()
 
 # %%
 # The line style can be set and is added after the line width or color to the
-# ``pen`` parameter.  In the example below, the line style is set to
-# ``..-`` (*dot dot dash*), and the default color ``black`` is used.
+# ``pen`` parameter.
 
 fig = pygmt.Figure()
-fig.plot(
-    region=[0, 10, 0, 10],
-    projection="X15c/10c",
-    frame="a",
-    x=[1, 8],
-    y=[3, 9],
-    pen="5p,..-",
-)
+fig.basemap(region=[0, 10, 0, 10], projection="X15c/10c", frame=True)
+
+# Set the line style to "..-" (dot dot dash), use the default color "black"
+fig.plot(x=[1, 8], y=[3, 9], pen="5p,..-")
+
 fig.show()
 
 # %%
-# The line width, color, and style can all be set in the same ``pen``
-# parameter. 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*).
-#
-# For a gallery showing other ``pen`` settings, see
+# The line width, color, and style can all be set in the same ``pen`` parameter.
+# For a gallery example showing other ``pen`` settings, see
 # :doc:`/gallery/lines/linestyles`.
 
 fig = pygmt.Figure()
-fig.plot(
-    region=[0, 10, 0, 10],
-    projection="X15c/10c",
-    frame="a",
-    x=[1, 8],
-    y=[3, 9],
-    pen="7p,green,-.-",
-)
+fig.basemap(region=[0, 10, 0, 10], projection="X15c/10c", frame=True)
+
+# Draw a 7-points thick, green line with style "-.-" (dash dot dash)
+fig.plot(x=[1, 8], y=[3, 9], pen="7p,green,-.-")
+
 fig.show()
 
-# sphinx_gallery_thumbnail_number = 3
+# sphinx_gallery_thumbnail_number = 6