Improve gallery examples (GenericMappingTools#827)

- Use SI units
- Improve some comments
- Improve some external references
- Improve some stylings
- Remove some links to the GMT documentation

Author: seisman

examples/gallery/coast/borders.py

@@ -18,8 +18,8 @@
 import pygmt
 
 fig = pygmt.Figure()
-# Make a Sinusoidal projection map of the Americas with automatic ticks
-fig.basemap(region=[-150, -30, -60, 60], projection="I-90/8i", frame="afg")
+# Make a Sinusoidal projection map of the Americas with automatic annotations, ticks and gridlines
+fig.basemap(region=[-150, -30, -60, 60], projection="I-90/15c", frame="afg")
 # Plot each level of the boundaries dataset with a different color.
 fig.coast(borders=["1/0.5p,black", "2/0.5p,red", "3/0.5p,blue"], land="gray")
 fig.show()

examples/gallery/coast/land_and_water.py

@@ -10,7 +10,7 @@
 
 fig = pygmt.Figure()
 # Make a global Mollweide map with automatic ticks
-fig.basemap(region="g", projection="W8i", frame=True)
-# Plot the land as light gray
+fig.basemap(region="g", projection="W15c", frame=True)
+# Plot the land as light gray, and the water as sky blue
 fig.coast(land="#666666", water="skyblue")
 fig.show()

examples/gallery/coast/shorelines.py

@@ -8,7 +8,7 @@
 
 fig = pygmt.Figure()
 # Make a global Mollweide map with automatic ticks
-fig.basemap(region="g", projection="W8i", frame=True)
+fig.basemap(region="g", projection="W15c", frame=True)
 # Display the shorelines as black lines with 0.5 point thickness
 fig.coast(shorelines="0.5p,black")
 fig.show()

examples/gallery/grid/grdview_surface.py

@@ -37,12 +37,12 @@ def ackley(x, y):
 fig = pygmt.Figure()
 
 # Plot grid as a 3-D surface
-SCALE = 0.2  # [inches]
+SCALE = 0.5  # in centimeter
 fig.grdview(
     data,
     frame=["a5f1", "za5f1"],
-    projection=f"x{SCALE}i",
-    zscale=f"{SCALE}i",
+    projection=f"x{SCALE}c",
+    zscale=f"{SCALE}c",
     surftype="s",
     cmap="roma",
     perspective=[135, 30],  # Azimuth southeast (135°), at elevation 30°

examples/gallery/grid/track_sampling.py

@@ -4,13 +4,13 @@
 
 The :func:`pygmt.grdtrack` function samples a raster grid's value along specified
 points. We will need to input a 2D raster to ``grid`` which can be an
-``xarray.DataArray``. The ``points`` parameter can be a ``pandas.DataFrame`` table where
+:class:`xarray.DataArray`. The ``points`` argument can be a :class:`pandas.DataFrame` table where
 the first two columns are x and y (or longitude and latitude). Note also that there is a
-``newcolname`` parameter that will be used to name the new column of values we sampled
+``newcolname`` argument that will be used to name the new column of values we sampled
 from the grid.
 
 Alternatively, we can provide a NetCDF file path to ``grid``. An ASCII file path can
-also be accepted for ``points``, but an ``outfile`` parameter will then need to be set
+also be accepted for ``points``, but an ``outfile`` argument will then need to be set
 to name the resulting output ASCII file.
 """
 
@@ -24,10 +24,10 @@
 
 fig = pygmt.Figure()
 # Plot the earth relief grid on Cylindrical Stereographic projection, masking land areas
-fig.basemap(region="g", frame=True, projection="Cyl_stere/150/-20/8i")
+fig.basemap(region="g", frame=True, projection="Cyl_stere/150/-20/15c")
 fig.grdimage(grid=grid, cmap="gray")
 fig.coast(land="#666666")
-# Plot using circles (c) of 0.15cm, the sampled bathymetry points
+# Plot using circles (c) of 0.15 cm, the sampled bathymetry points
 # Points are colored using elevation values (normalized for visual purposes)
 fig.plot(
     x=track.longitude,

examples/gallery/plot/colorbar.py

@@ -5,23 +5,21 @@
 The :meth:`pygmt.Figure.colorbar` method creates a color scalebar. We must
 specify the colormap via the ``cmap`` argument, and optionally set the
 placement via the ``position`` argument. The full list of color palette tables
-can be found at :gmt-docs:`cookbook/cpts.html`. You can set the `position` of
+can be found at :gmt-docs:`cookbook/cpts.html`. You can set the ``position`` of
 the colorbar using the following options:
 
-- j/J: justified inside/outside the map frame using any 2 character combination
-  of vertical (**T** op, **M** iddle, **B** ottom) and horizontal (**L** eft,
-  **C** enter, **R** ight) alignment codes, e.g. `position="jTR"` for top
+- **j/J**: justified inside/outside the map frame using any 2 character combination
+  of vertical (**T**\ op, **M**\ iddle, **B**\ ottom) and horizontal (**L**\ eft,
+  **C**\ enter, **R**\ ight) alignment codes, e.g. ``position="jTR"`` for top
   right.
-- g: using map coordinates, e.g. `position="g170/-45"` for longitude 170E,
+- **g**: using map coordinates, e.g. ``position="g170/-45"`` for longitude 170E,
   latitude 45S.
-- x: using paper coordinates, e.g. `position="x5c/7c"` for 5cm,7cm from anchor
+- **x**: using paper coordinates, e.g. ``position="x5c/7c"`` for 5cm,7cm from anchor
   point.
-- n: using normalized (0-1) coordinates, e.g. `position="n0.4/0.8"`.
+- **n**: using normalized (0-1) coordinates, e.g. ``position="n0.4/0.8"``.
 
-Note that the anchor point defaults to the bottom left (BL). Append +h to
-``position`` to get a horizontal colorbar instead of a vertical one. For more
-advanced styling options, see the full option list at
-:gmt-docs:`colorbar.html`.
+Note that the anchor point defaults to the bottom left (BL). Append ``+h`` to
+``position`` to get a horizontal colorbar instead of a vertical one.
 """
 import pygmt
 

examples/gallery/plot/image.py

@@ -1,15 +1,13 @@
 """
 Images or EPS files on maps
 ---------------------------
-The :meth:`pygmt.Figure.image` method can be used to read and 
+The :meth:`pygmt.Figure.image` method can be used to read and
 place a raster image file or an Encapsulated PostScript file
-on a map. We must specify the file as *str* via the ``imagefile`` 
-argument or simply use the filename as first argument. You can 
-also use a full URL pointing to your desired image. The ``position`` 
+on a map. We must specify the file as *str* via the ``imagefile``
+argument or simply use the filename as the first argument. You can
+also use a full URL pointing to your desired image. The ``position``
 argument allows us to set a reference point on the map for the image.
 
-For more advanced style options, see the full option list 
-at :gmt-docs:`image.html`.
 """
 
 import pygmt

examples/gallery/plot/meca.py

@@ -20,7 +20,6 @@
     land="grey",
     water="lightblue",
     shorelines=True,
-    resolution="f",
     frame="a",
 )
 

examples/gallery/plot/multi-parameter-symbols.py

@@ -2,25 +2,24 @@
 Multi-parameter symbols
 -------------------------
 
-The :meth:`pygmt.Figure.plot` method can plot individual multi-parameter symbols by passing 
-the corresponding shortcuts listed below to the ``style`` argument. Additionally, we must define 
-the required parameters in a 2d list or numpy array (``[[parameters]]`` for a single symbol 
-or ``[[parameters_1],[parameters_2],[parameters_i]]`` for several ones) or use an 
-appropriately formatted input file and pass it to ``data``. 
+The :meth:`pygmt.Figure.plot` method can plot individual multi-parameter symbols by passing
+the corresponding shortcuts listed below to the ``style`` argument. Additionally, we must define
+the required parameters in a 2d list or numpy array (``[[parameters]]`` for a single symbol
+or ``[[parameters_1],[parameters_2],[parameters_i]]`` for several ones) or use an
+appropriately formatted input file and pass it to ``data``.
 
 The following symbols are available:
 
 - **e**: ellipse, ``[[lon, lat, direction, major_axis, minor_axis]]``
 - **j**: rotated rectangle, ``[[lon, lat, direction, width, height]]``
 - **r**: rectangle, ``[[lon, lat, width, height]]``
 - **R**: rounded rectangle, ``[[lon, lat, width, height, radius]]``
-- **w**: pie wedge, ``[[lon, lat, radius, startdir, stopdir]]``, the last two arguments are 
-  directions given in degrees counter-clockwise from horizontal 
+- **w**: pie wedge, ``[[lon, lat, radius, startdir, stopdir]]``, the last two arguments are
+  directions given in degrees counter-clockwise from horizontal
 
-Upper-case versions **E**, **J**, and **W** are similar to **e**, **j** and **w** but expect geographic 
+Upper-case versions **E**, **J**, and **W** are similar to **e**, **j** and **w** but expect geographic
 azimuths and distances.
 
-For more advanced options, see the full option list at :gmt-docs:`plot.html`.
 """
 
 import numpy as np

examples/gallery/plot/points.py

@@ -15,8 +15,8 @@
 y = np.random.uniform(region[2], region[3], 100)
 
 fig = pygmt.Figure()
-# Create a 6x6 inch basemap with a Cartesian projection (X) using the data region
-fig.basemap(region=region, projection="X6i", frame=True)
+# Create a 15x15 cm basemap with a Cartesian projection (X) using the data region
+fig.basemap(region=region, projection="X15c", frame=True)
 # Plot using triangles (i) of 0.5 cm
 fig.plot(x, y, style="i0.5c", color="black")
 fig.show()