Improve PyGMT documentation

doc/install.rst

@@ -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,6 +147,10 @@ This installs the latest stable release from
 
     pip install pygmt
 
+This upgrades the installed PyGMT to be the latest stable release::
+
+    pip install --upgrade pygmt
+
 Alternatively, you can install the latest development version from
 `TestPyPI <https://test.pypi.org/project/pygmt>`__::
 
@@ -152,8 +161,8 @@ or from PyGMT's `GitHub repository <https://github.com/GenericMappingTools/pygmt
 
     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.
+Any of the above methods (conda/pip) should allow you to use the PyGMT library
+from Python.
 
 
 Testing your install
@@ -182,7 +191,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 +203,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/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 centimeters, 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
@@ -80,7 +82,7 @@
 # 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``.
+#    which is now ``colorbar``. Those reflect the new GMT modern execution mode.
 # 2. 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