Improve PyGMT documentation

doc/install.rst

@@ -41,7 +41,7 @@ Start by looking at the tutorials on our sidebar, good luck!
 
     The sections below provide more detailed, step by step instructions to
     installing and testing PyGMT for those who may have a slightly different
-    setup.
+    setup or want to install the latest development version.
 
 Which Python?
 -------------
@@ -51,9 +51,10 @@ work, but there is no guarantee that PyGMT will behave as expected.
 
 We recommend using the `Anaconda <https://www.anaconda.com/distribution>`__
 Python distribution to ensure you have all dependencies installed and the
-``conda`` package manager available.
-Installing Anaconda does not require administrative rights to your computer and
-doesn't interfere with any other Python installations in your system.
+`conda <https://docs.conda.io/projects/conda/en/latest/>`__
+package manager available. Installing Anaconda does not require administrative
+rights to your computer and doesn't interfere with any other Python
+installations in your system.
 
 
 Which GMT?
@@ -110,14 +111,14 @@ Now we can create a new conda environment with Python and all our dependencies
 installed (we'll call it ``pygmt`` but feel free to change it to whatever you
 want)::
 
-     conda create --name pygmt python=3.9 pip numpy pandas xarray netcdf4 packaging gmt
+    conda create --name pygmt python=3.9 numpy pandas xarray netcdf4 packaging gmt
 
 Activate the environment by running the following (**do not forget this step!**)::
 
     conda activate pygmt
 
 From now on, all commands will take place inside the conda virtual environment
-called 'pygmt' and won't affect your default 'base' installation.
+called ``pygmt`` and won't affect your default ``base`` installation.
 
 
 Installing PyGMT
@@ -134,6 +135,10 @@ This installs the latest stable release of PyGMT from
 
     conda install pygmt
 
+This upgrades the installed PyGMT to be the latest stable release::
+
+    conda update pygmt
+
 Using pip
 ~~~~~~~~~
 
@@ -142,18 +147,28 @@ This installs the latest stable release from
 
     pip install pygmt
 
-Alternatively, you can install the latest development version from
+This upgrades the installed PyGMT to be the latest stable release::
+
+    pip install --upgrade pygmt
+
+You also can install the latest development version from
 `TestPyPI <https://test.pypi.org/project/pygmt>`__::
 
     pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt
 
-or from PyGMT's `GitHub repository <https://github.com/GenericMappingTools/pygmt>`__ 
+To upgrade the installed development version to be the latest one, just add ``--upgrade``::
+
+    pip install --upgrade --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt
+
+Alternatively, you can install the latest development version from PyGMT's `GitHub repository <https://github.com/GenericMappingTools/pygmt>`__ 
 (slower as it downloads the whole archive)::
 
     pip install git+https://github.com/GenericMappingTools/pygmt.git#egg=pygmt
 
-Any of the above methods (conda/pip) should allow you to use the ``pygmt``
-library from Python.
+Run the above command again to upgrade to the latest development version.
+
+Any of the above methods (conda/pip) should allow you to use the PyGMT package
+from Python.
 
 
 Testing your install
@@ -182,7 +197,8 @@ dependencies as well (be sure to have your conda environment activated)::
 
     conda install pytest pytest-mpl ipython
 
-Test your installation by running the following inside a Python interpreter::
+Test your installation by running the following inside a Python interpreter
+(note that it may take a few minutes)::
 
     import pygmt
     pygmt.show_versions()
@@ -193,14 +209,14 @@ Finding the GMT shared library
 ------------------------------
 
 Sometimes, PyGMT will be unable to find the correct version of the GMT shared
-library.
+library (``libgmt``).
 This can happen if you have multiple versions of GMT installed.
 
 You can tell PyGMT exactly where to look for ``libgmt`` by setting the
 ``GMT_LIBRARY_PATH`` environment variable.
 This should be set to the directory where ``libgmt.so``, ``libgmt.dylib`` or
-``gmt.dll`` can be found for Linux, macOS and Windows respectively.
-e.g. on a command line, run::
+``gmt.dll`` can be found for Linux, macOS and Windows, respectively.
+e.g., on a command line, run::
 
     # Linux/macOS
     export GMT_LIBRARY_PATH=$HOME/anaconda3/envs/pygmt/lib

examples/gallery/coast/land_and_water.py

@@ -2,9 +2,10 @@
 Color land and water
 --------------------
 
-The ``land`` and ``water`` parameters of :meth:`pygmt.Figure.coast` specify a color to
-fill in the land and water masses, respectively. You can use standard GMT color names or
-give a hex value (like ``#333333``).
+The ``land`` and ``water`` parameters of :meth:`pygmt.Figure.coast` specify a
+color to fill in the land and water masses, respectively. You can use
+:gmt-docs:`standard GMT color names <gmtcolors.html#list-of-colors>`
+or give a hex value (like ``#333333``).
 """
 import pygmt
 

examples/gallery/grid/grdview_surface.py

@@ -5,11 +5,11 @@
 The :meth:`pygmt.Figure.grdview()` method can plot 3-D surfaces with ``surftype="s"``. Here,
 we supply the data as an :class:`xarray.DataArray` with the coordinate vectors ``x`` and
 ``y`` defined. Note that the ``perspective`` parameter here controls the azimuth and
-elevation angle of the view. We provide a list of two arguments to ``frame`` - the
-first argument specifies the :math:`x`- and :math:`y`:-axes frame attributes and the
+elevation angle of the view. Specifying the same scale for the ``projection`` and ``zcale``
+parameters ensures equal axis scaling. We provide a list of two arguments to ``frame`` - the
+first argument specifies the :math:`x`- and :math:`y`-axes frame attributes and the
 second argument, prepended with ``"z"``, specifies the :math:`z`-axis frame attributes.
-Specifying the same scale for the ``projection`` and ``zcale`` parameters ensures equal
-axis scaling. The ``shading`` parameter specifies illumination; here we choose an azimuth of
+The ``shading`` parameter specifies illumination; here we choose an azimuth of
 45° with ``shading="+a45"``.
 """
 
@@ -41,13 +41,13 @@ def ackley(x, y):
 SCALE = 0.5  # in centimeter
 fig.grdview(
     data,
-    frame=["a5f1", "za5f1"],
+    surftype="s",
     projection=f"x{SCALE}c",
     zscale=f"{SCALE}c",
-    surftype="s",
-    cmap="roma",
     perspective=[135, 30],  # Azimuth southeast (135°), at elevation 30°
+    frame=["a5f1", "za5f1"],
     shading="+a45",
+    cmap="roma",
 )
 
 fig.show()

examples/gallery/grid/track_sampling.py

@@ -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/15c")
+fig.basemap(region="g", projection="Cyl_stere/150/-20/15c", frame=True)
 fig.grdimage(grid=grid, cmap="gray")
 fig.coast(land="#666666")
-# Plot using circles (c) of 0.15 cm, the sampled bathymetry points
+# Plot the sampled bathymetry points using circles (c) of 0.15 cm
 # Points are colored using elevation values (normalized for visual purposes)
 fig.plot(
     x=track.longitude,

examples/gallery/line/line-custom-cpt.py

@@ -19,7 +19,7 @@
 x = np.arange(start=20, stop=30, step=0.2)
 
 fig = pygmt.Figure()
-fig.basemap(frame=["WSne", "af"], region=[20, 30, -10, 10])
+fig.basemap(region=[20, 30, -10, 10], frame=["WSne", "af"])
 
 # Create a custom CPT with the batlow CPT and 10 discrete z-values (colors)
 pygmt.makecpt(cmap="batlow", series=[0, 10, 1])

examples/gallery/line/linestyles.py

@@ -38,7 +38,9 @@
     "1p,lightblue,-.",  # dash-dotted line
     "2p,blue,..-",  # dot-dot-dashed line
     "2p,tomato,--.",  # dash-dash-dotted line
-    "2p,tomato,4_2:2p",  # A pattern of 4-point-long line segment and 2-point-gap between segment
+    # A pattern of 4-point-long line segment and 2-point-gap between segment,
+    # with pattern offset by 2 points from the origin
+    "2p,tomato,4_2:2p",
 ]:
     y -= 1  # Move the current line down
     fig.plot(x=x, y=y, pen=linestyle)

examples/gallery/plot/colorbar.py

@@ -49,8 +49,7 @@
     # with a length/width (+w) of 7cm by 0.5cm and a box for NaN values (+n)
     position="JMR+o1c/0c+w7c/0.5c+n+mc",
     # Note that the label 'Elevation' is moved to the opposite side and plotted
-    # vertically as a column of text using '+mc' in the position parameter
-    # above
+    # vertically as a column of text using '+mc' in the position parameter above
     frame=["x+lElevation", "y+lm"],
     scale=10,
 )

examples/gallery/plot/image.py

@@ -18,7 +18,8 @@
 fig.basemap(region=[0, 2, 0, 2], projection="X6c", frame=True)
 
 # place and center the GMT logo from the GMT website to the position 1/1
-# on a basemap and draw a rectangular border around the image
+# on a basemap, scaled up to be 3 cm wide and draw a rectangular border
+# around the image
 fig.image(
     imagefile="https://www.generic-mapping-tools.org/_static/gmt-logo.png",
     position="g1/1+w3c+jCM",

examples/gallery/plot/inset.py

@@ -4,8 +4,8 @@
 
 The :meth:`pygmt.Figure.inset` method adds an inset figure inside a larger
 figure. The function is called using a ``with`` statement, and its position,
-box, offset, and margin parameters are set. Within the ``with`` statement,
-PyGMT plotting functions can be called that add to the inset figure.
+box, offset, and margin parameters are set. Plotting methods called within the
+``with`` statement plot into the inset figure.
 """
 import pygmt
 

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

@@ -26,37 +26,26 @@
 import pygmt
 
 fig = pygmt.Figure()
-
 fig.basemap(region=[0, 6, 0, 2], projection="x3c", frame=True)
 
-###################
 # ELLIPSE
 data = np.array([[0.5, 1, 45, 3, 1]])
-
 fig.plot(data=data, style="e", color="orange", pen="2p,black")
 
-###################
 # ROTATED RECTANGLE
 data = np.array([[1.5, 1, 120, 5, 0.5]])
-
 fig.plot(data=data, style="j", color="red3", pen="2p,black")
 
-###################
 # RECTANGLE
 data = np.array([[3, 1, 4, 1.5]])
-
 fig.plot(data=data, style="r", color="dodgerblue", pen="2p,black")
 
-###################
 # ROUNDED RECTANGLE
 data = np.array([[4.5, 1, 1.25, 4, 0.5]])
-
 fig.plot(data=data, style="R", color="seagreen", pen="2p,black")
 
-###################
 # PIE WEDGE
 data = np.array([[5.5, 1, 2.5, 45, 330]])
-
 fig.plot(data=data, style="w", color="lightgray", pen="2p,black")
 
 fig.show()

examples/gallery/plot/points-transparency.py

@@ -18,8 +18,8 @@
 fig = pygmt.Figure()
 fig.basemap(
     region=[-5, 105, 0, 2],
-    frame=['xaf+l"Transparency level"+u%', "WSrt"],
     projection="X15c/6c",
+    frame=['xaf+l"Transparency level"+u%', "WSrt"],
 )
 fig.plot(x=x, y=y, style="c0.6c", color="blue", pen="1p,red", transparency=transparency)
 fig.show()

examples/gallery/plot/scatter3d.py

@@ -5,7 +5,7 @@
 The :meth:`pygmt.Figure.plot3d` method can be used to plot symbols in 3D.
 In the example below, we show how the
 `Iris flower dataset <https://en.wikipedia.org/wiki/Iris_flower_data_set>`__
-can be visualized using a perspective 3-dimensional plot. The ``region``
+can be visualized using a perspective 3D plot. The ``region``
 parameter has to include the :math:`x`, :math:`y`, :math:`z` axis limits in the
 form of (xmin, xmax, ymin, ymax, zmin, zmax), which can be done automatically
 using :meth:`pygmt.info`. To plot the z-axis frame, set ``frame`` as a
@@ -36,6 +36,7 @@
     x=df.petal_width,
     y=df.sepal_length,
     z=df.petal_length,
+    style="uc",  # 3D cUbe, with size in centimeter units
     sizes=0.1 * df.sepal_width,  # Vary each symbol size according to a data column
     color=df.species.cat.codes.astype(int),  # Points colored by categorical number code
     cmap=True,  # Use colormap created by makecpt
@@ -46,7 +47,6 @@
         'yafg+l"Sepal Length"',
         'zafg+l"Petal Length"',
     ],
-    style="uc",  # 3D cUbe, with size in centimeter units
     perspective=[315, 25],  # Azimuth NorthWest (315°), at elevation 25°
     zscale=1.5,  # Vertical exaggeration factor
 )

examples/tutorials/first-figure.py

@@ -7,7 +7,8 @@
 
 .. note::
 
-    This tutorial assumes the use of a Python notebook, such as IPython or Jupyter Notebook.
+    This tutorial assumes the use of a Python notebook, such as `IPython <https://ipython.org/>`__
+    or `JupyterLab <https://jupyter.org/>`__.
     To see the figures while using a Python script instead, use
     ``fig.show(method="external")`` to display the figure in the default PDF viewer.
 
@@ -34,11 +35,12 @@
 fig = pygmt.Figure()
 
 ########################################################################################
-# Add elements to the figure using its methods. For example, let's start a map with an
-# automatic frame and ticks around a given longitude and latitude bound, set the
-# projection to Mercator (``M``), and the map width to 8 inches:
+# Add elements to the figure using its methods. For example, let's use
+# :meth:`pygmt.Figure.basemap` to start a map for a region indicated by a given
+# longitude and latitude bound, set the projection to Mercator (**M**), the
+# map width to 8 cm, and frame type to be generated automatically:
 
-fig.basemap(region=[-90, -70, 0, 20], projection="M8i", frame=True)
+fig.basemap(region=[-90, -70, 0, 20], projection="M8c", frame=True)
 
 ########################################################################################
 # Now we can add coastlines using :meth:`pygmt.Figure.coast` to this map using the
@@ -56,7 +58,7 @@
 # without calling :meth:`gmt.Figure.basemap`:
 
 fig = pygmt.Figure()
-fig.coast(shorelines=True, region=[-90, -70, 0, 20], projection="M8i", frame=True)
+fig.coast(shorelines=True, region=[-90, -70, 0, 20], projection="M8c", frame=True)
 fig.show()
 
 ########################################################################################
@@ -74,20 +76,25 @@
 # ------------------------------
 #
 # You’ll probably have noticed several things that are different from classic
-# command-line GMT. Many of these changes reflect the new GMT modern execution mode that
-# are part of GMT 6. A few are PyGMT exclusive (like the ``savefig`` method).
+# command-line GMT. Many of these changes reflect the new GMT modern execution
+# mode that is part of GMT 6.
 #
 # 1. The name of method is ``coast`` instead of ``pscoast``. As a general rule, all
 #    ``ps*`` modules had their ``ps`` prefix removed. The exceptions are:
 #    ``psxy`` which is now ``plot``, ``psxyz`` which is now ``plot3d``, and ``psscale``
 #    which is now ``colorbar``.
-# 2. The parameters don't use the GMT 1-letter syntax (**R**, **J**, **B**, etc). We use longer
+#
+# 2. More details can be found at :gmt-docs:`/cookbook/introduction.html#modern-and-classic-mode`
+#
+# A few are PyGMT exclusive (like the ``savefig`` method).
+#
+# 1. The parameters don't use the GMT 1-letter syntax (**R**, **J**, **B**, etc). We use longer
 #    aliases for these parameters and have some Python exclusive names. The mapping
 #    between the GMT parameters and their Python counterparts should be straight
 #    forward.
-# 3. Parameters like ``region`` can take lists as well as strings like ``1/2/3/4``.
-# 4. If a GMT parameter has no options (like ``-B`` instead of ``-Baf``), use a ``True``
+# 2. Parameters like ``region`` can take lists as well as strings like ``1/2/3/4``.
+# 3. If a GMT parameter has no options (like ``-B`` instead of ``-Baf``), use a ``True``
 #    in Python. An empty string would also be acceptable. For repeated parameters, such
 #    as ``-B+Loleron -Bxaf -By+lm``, provide a list: ``frame=["+Loleron", "xaf", "y+lm"]``.
-# 5. There is no output redirecting to a PostScript file. The figure is generated in the
+# 4. There is no output redirecting to a PostScript file. The figure is generated in the
 #    background and will only be shown or saved when you ask for it.

examples/tutorials/plot.py

@@ -41,8 +41,8 @@
 
 
 ########################################################################################
-# We'll use :meth:`pygmt.Figure.plot` method to plot circles on the locations of the
-# hypocenters of the earthquakes.
+# We'll use :meth:`pygmt.Figure.plot` method to plot circles on the locations
+# of the earthquakes.
 
 fig = pygmt.Figure()
 fig.basemap(region=region, projection="M15c", frame=True)

examples/tutorials/regions.py

@@ -147,7 +147,7 @@
 ########################################################################################
 #
 # The area encompassed by the ISO code can be expanded by appending **+r**\ *increment*
-# to the ISO code. The *increment* unit is in degrees, and if only value is added it
+# to the ISO code. The *increment* unit is in degrees, and if only one value is added it
 # expands the range of the region in all directions. Using **+r** rounds to the nearest
 # increment.
 
@@ -226,8 +226,8 @@
 
 ########################################################################################
 #
-# The ``region`` increment can be appended with **+e**, which expand the bounding box
-# by at least 25% beyond the increment.
+# The ``region`` increment can be appended with **+e**, which expands the
+# bounding box by at least 25% beyond the increment.
 
 fig = pygmt.Figure()
 fig.coast(