Update docstrings links for return classes (#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 #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)