Update docstrings links for return classes (GenericMappingTools#954)

This PR adds links to xarray, pandas, and numpy classes in the Returns 
section of the docstrings. It also includes a few small fixes according 
to the conventions set in GenericMappingTools#631.

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

pygmt/src/blockmedian.py

@@ -56,10 +56,12 @@ def blockmedian(table, outfile=None, **kwargs):
     Returns
     -------
     output : pandas.DataFrame or None
-        Return type depends on whether the outfile parameter is set:
+        Return type depends on whether the ``outfile`` parameter is set:
 
-        - pandas.DataFrame table with (x, y, z) columns if outfile is not set
-        - None if outfile is set (filtered output will be stored in outfile)
+        - :class:`pandas.DataFrame` table with (x, y, z) columns if ``outfile``
+          is not set
+        - None if ``outfile`` is set (filtered output will be stored in file
+          set by ``outfile``)
     """
     kind = data_kind(table)
     with GMTTempFile(suffix=".csv") as tmpfile:

pygmt/src/grdcut.py

@@ -32,13 +32,13 @@ def grdcut(grid, **kwargs):
     Extract subregion from a grid.
 
     Produce a new ``outgrid`` file which is a subregion of ``grid``. The
-    subregion is specified with *region*; the specified range must not exceed
-    the range of *grid* (but see *extend*). If in doubt, run
+    subregion is specified with ``region``; the specified range must not exceed
+    the range of ``grid`` (but see ``extend``). If in doubt, run
     :meth:`pygmt.grdinfo` to check range. Alternatively, define the subregion
     indirectly via a range check on the node values or via distances from a
-    given point. Finally, you can give *projection* for oblique projections to
-    determine the corresponding rectangular *region* setting that will give a
-    grid that fully covers the oblique domain.
+    given point. Finally, you can give ``projection`` for oblique projections
+    to determine the corresponding rectangular ``region`` that will give a grid
+    that fully covers the oblique domain.
 
     Full option list at :gmt-docs:`grdcut.html`
 
@@ -83,10 +83,11 @@ def grdcut(grid, **kwargs):
     Returns
     -------
     ret: xarray.DataArray or None
-        Return type depends on whether the *outgrid* parameter is set:
+        Return type depends on whether the ``outgrid`` parameter is set:
 
-        - xarray.DataArray if *outgrid* is not set
-        - None if *outgrid* is set (grid output will be stored in *outgrid*)
+        - :class:`xarray.DataArray` if ``outgrid`` is not set
+        - None if ``outgrid`` is set (grid output will be stored in file set by
+          ``outgrid``)
     """
     kind = data_kind(grid)
 

pygmt/src/grdfilter.py

@@ -115,9 +115,11 @@ def grdfilter(grid, **kwargs):
     Returns
     -------
     ret: xarray.DataArray or None
-        Return type depends on whether the *outgrid* parameter is set:
-        - xarray.DataArray if *outgrid* is not set
-        - None if *outgrid* is set (grid output will be stored in *outgrid*)
+        Return type depends on whether the ``outgrid`` parameter is set:
+
+        - :class:`xarray.DataArray` if ``outgrid`` is not set
+        - None if ``outgrid`` is set (grid output will be stored in file set by
+          ``outgrid``)
 
     Examples
     --------

pygmt/src/grdtrack.py

@@ -26,7 +26,7 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs):
     table with the interpolated values added as (one or more) new columns. A
     bicubic [Default], bilinear, B-spline or nearest-neighbor interpolation is
     used, requiring boundary conditions at the limits of the region (see
-    *interpolation*; Default uses “natural” conditions (second partial
+    ``interpolation``; Default uses “natural” conditions (second partial
     derivative normal to edge is zero) unless the grid is automatically
     recognized as periodic.)
 
@@ -46,12 +46,12 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs):
         format).
 
     newcolname : str
-        Required if 'points' is a pandas.DataFrame. The name for the new column
-        in the track pandas.DataFrame table where the sampled values will be
-        placed.
+        Required if ``points`` is a :class:`pandas.DataFrame`. The name for the
+        new column in the track :class:`pandas.DataFrame` table where the
+        sampled values will be placed.
 
     outfile : str
-        Required if 'points' is a file. The file name for the output ASCII
+        Required if ``points`` is a file. The file name for the output ASCII
         file.
 
     {V}
@@ -61,11 +61,12 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs):
     Returns
     -------
     track: pandas.DataFrame or None
-        Return type depends on whether the outfile parameter is set:
+        Return type depends on whether the ``outfile`` parameter is set:
 
-        - pandas.DataFrame table with (x, y, ..., newcolname) if outfile is not
-          set
-        - None if outfile is set (track output will be stored in outfile)
+        - :class:`pandas.DataFrame` table with (x, y, ..., newcolname) if
+          ``outfile`` is not set
+        - None if ``outfile`` is set (track output will be stored in file set
+          by ``outfile``)
     """
 
     with GMTTempFile(suffix=".csv") as tmpfile:

pygmt/src/info.py

@@ -30,8 +30,8 @@ def info(table, **kwargs):
     and *dy* are needed). If the ``per_column`` parameter is combined with
     ``spacing``, then the numpy.ndarray output will be rounded up/down for as
     many columns as there are increments provided in ``spacing``. A similar
-    parameter ``nearest_multiple`` option will provide a numpy.ndarray in the
-    form of [*zmin*, *zmax*, *dz*]`` for makecpt.
+    parameter ``nearest_multiple`` will provide a numpy.ndarray in the form
+    of [*zmin*, *zmax*, *dz*] for makecpt.
 
     Full option list at :gmt-docs:`gmtinfo.html`
 
@@ -63,7 +63,7 @@ def info(table, **kwargs):
         Return type depends on whether any of the ``per_column``,
         ``spacing``, or ``nearest_multiple`` parameters are set.
 
-        - np.ndarray if either of the above parameters are used.
+        - :class:`numpy.ndarray` if either of the above parameters are used.
         - str if none of the above parameters are used.
     """
     kind = data_kind(table)