Update the docstrings in the non-plotting modules (#882)

willschlitzer · Meghan Jones · seisman · web-flow · commit 529eed79db02 · 2021-02-14T15:59:32.000-05:00
* Update docstrings for makecpt.py
* Update docstrings for savefig in figure.py
* Update docstrings for psconvert in figure.py
* Update docstrings in blockmedian.py
* Update docstrings in surface.py
* Update docstrings in grdcut.py
* Update docstrings in grdfilter.py
* Update docstrings in x2sys.py
* Update docstrings for x2sys_cross in x2sys.py
* Update docstrings for info.py
* Update output docstring in info.py
* Update formatting in makecpt.py

Co-authored-by: Meghan Jones &lt;meghanj@hawaii.edu&gt;
Co-authored-by: Dongdong Tian &lt;seisman.info@gmail.com&gt;
diff --git a/pygmt/figure.py b/pygmt/figure.py
@@ -115,7 +115,7 @@ def region(self):
     )
     @kwargs_to_strings()
     def psconvert(self, **kwargs):
-        """
+        r"""
         Convert [E]PS file(s) to other formats.
 
         Converts one or more PostScript files to other formats (BMP, EPS, JPEG,
@@ -149,20 +149,22 @@ def psconvert(self, **kwargs):
         icc_gray : bool
             Enforce gray-shades by using ICC profiles.
         anti_aliasing : str
-            Set the anti-aliasing options for graphics or text. Append the size
-            of the subsample box (1, 2, or 4) [4]. Default is no anti-aliasing
-            (same as bits = 1).
+            [**g**\|\ **p**\|\ **t**\][**1**\|\ **2**\|\ **4**].
+            Set the anti-aliasing options for **g**\ raphics or **t**\ ext.
+            Append the size of the subsample box (1, 2, or 4) [4]. [Default is
+            no anti-aliasing (same as bits = 1)].
         fmt : str
-            Sets the output format, where *b* means BMP, *e* means EPS, *E*
-            means EPS with PageSize command, *f* means PDF, *F* means
-            multi-page PDF, *j* means JPEG, *g* means PNG, *G* means
-            transparent PNG (untouched regions are transparent), *m* means PPM,
-            *s* means SVG, and *t* means TIFF [default is JPEG]. To ``'bjgt'``
-            you can append ``'+m'`` in order to get a monochrome (grayscale)
-            image. The EPS format can be combined with any of the other
-            formats. For example, ``'ef'`` creates both an EPS and a PDF file.
-            Using ``'F'`` creates a multi-page PDF file from the list of input
-            PS or PDF files. It requires the *prefix* option.
+            Sets the output format, where **b** means BMP, **e** means EPS,
+            **E** means EPS with PageSize command, **f** means PDF, **F** means
+            multi-page PDF, **j** means JPEG, **g** means PNG, **G** means
+            transparent PNG (untouched regions are transparent), **m** means
+            PPM, **s** means SVG, and **t** means TIFF [default is JPEG]. To
+            **b**\|\ **j**\|\ **g**\|\ **t**\ , optionally append **+m** in
+            order to get a monochrome (grayscale) image. The EPS format can be
+            combined with any of the other formats. For example, **ef** creates
+            both an EPS and a PDF file. Using **F** creates a multi-page PDF
+            file from the list of input PS or PDF files. It requires the
+            ``prefix`` parameter.
         """
         kwargs = self._preprocess(**kwargs)
         # Default cropping the figure to True
@@ -178,7 +180,7 @@ def savefig(
         Save the figure to a file.
 
         This method implements a matplotlib-like interface for
-        :meth:`~gmt.Figure.psconvert`.
+        :meth:`pygmt.Figure.psconvert`.
 
         Supported formats: PNG (``.png``), JPEG (``.jpg``), PDF (``.pdf``),
         BMP (``.bmp``), TIFF (``.tif``), EPS (``.eps``), and KML (``.kml``).
@@ -199,9 +201,10 @@ def savefig(
             If True, will crop the figure canvas (page) to the plot area.
         anti_alias: bool
             If True, will use anti aliasing when creating raster images (PNG,
-            JPG, TIf). More specifically, uses options ``Qt=2, Qg=2`` in
-            :meth:`~gmt.Figure.psconvert`. Ignored if creating vector graphics.
-            Overrides values of ``Qt`` and ``Qg`` passed in through ``kwargs``.
+            JPG, TIFF). More specifically, it passes arguments ``t2``
+            and ``g2`` to the ``anti_aliasing`` parameter of
+            :meth:`pygmt.Figure.psconvert`. Ignored if creating vector
+            graphics.
         show: bool
             If True, will open the figure in an external viewer.
         dpi : int
diff --git a/pygmt/src/blockmedian.py b/pygmt/src/blockmedian.py
@@ -19,7 +19,7 @@
 @use_alias(I="spacing", R="region", V="verbose")
 @kwargs_to_strings(R="sequence")
 def blockmedian(table, outfile=None, **kwargs):
-    """
+    r"""
     Block average (x,y,z) data tables by median estimation.
 
     Reads arbitrarily located (x,y,z) triples [or optionally weighted
@@ -39,15 +39,17 @@ def blockmedian(table, outfile=None, **kwargs):
         ASCII data table.
 
     spacing : str
-        ``'xinc[unit][+e|n][/yinc[unit][+e|n]]'``.
-        x_inc [and optionally y_inc] is the grid spacing.
+        *xinc*\[\ *unit*\][**+e**\|\ **n**]
+        [/*yinc*\ [*unit*][**+e**\|\ **n**]].
+        *xinc* [and optionally *yinc*] is the grid spacing.
 
     region : str or list
-        ``'xmin/xmax/ymin/ymax[+r][+uunit]'``.
+        *xmin/xmax/ymin/ymax*\[\ **+r**\][**+u**\ *unit*].
         Specify the region of interest.
 
     outfile : str
-        Required if 'table' is a file. The file name for the output ASCII file.
+        Required if ``table`` is a file. The file name for the output ASCII
+        file.
 
     {V}
 
diff --git a/pygmt/src/grdcut.py b/pygmt/src/grdcut.py
@@ -28,10 +28,10 @@
 )
 @kwargs_to_strings(R="sequence")
 def grdcut(grid, **kwargs):
-    """
+    r"""
     Extract subregion from a grid.
 
-    Produce a new *outgrid* file which is a subregion of *grid*. The
+    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
     :meth:`pygmt.grdinfo` to check range. Alternatively, define the subregion
@@ -54,16 +54,16 @@ def grdcut(grid, **kwargs):
     {J}
     {R}
     extend : bool or int or float
-        Allow grid to be extended if new *region* exceeds existing boundaries.
-        Give a value to initialize nodes outside current region.
+        Allow grid to be extended if new ``region`` exceeds existing
+        boundaries. Give a value to initialize nodes outside current region.
     circ_subregion : str
-        ``'lon/lat/radius[unit][+n]'``.
+        *lon/lat/radius*\[\ *unit*\][**+n**].
         Specify an origin (*lon* and *lat*) and *radius*; append a distance
         *unit* and we determine the corresponding rectangular region so that
         all grid nodes on or inside the circle are contained in the subset.
         If **+n** is appended we set all nodes outside the circle to NaN.
     z_subregion : str
-        ``'[min/max][+n|N|r]'``.
+        [*min/max*\][**+n**\|\ **N**\|\ **r**].
         Determine a new rectangular region so that all nodes outside this
         region are also outside the given z-range [-inf/+inf]. To indicate no
         limit on *min* or *max* only, specify a hyphen (-). Normally, any NaNs
diff --git a/pygmt/src/grdfilter.py b/pygmt/src/grdfilter.py
@@ -29,18 +29,18 @@
 )
 @kwargs_to_strings(R="sequence")
 def grdfilter(grid, **kwargs):
-    """
+    r"""
     Filter a grid in the space (or time) domain.
 
     Filter a grid file in the time domain using one of the selected convolution
     or non-convolution isotropic or rectangular filters and compute distances
     using Cartesian or Spherical geometries. The output grid file can
-    optionally be generated as a sub-region of the input (via *region*) and/or
-    with new increment (via *spacing*) or registration (via *toggle*). In this
-    way, one may have "extra space" in the input data so that the edges will
-    not be used and the output can be within one half-width of the input edges.
-    If the filter is low-pass, then the output may be less frequently sampled
-    than the input.
+    optionally be generated as a sub-region of the input (via ``region``)
+    and/or with new increment (via ``spacing``) or registration
+    (via ``toggle``). In this way, one may have "extra space" in the input
+    data so that the edges will not be used and the output can be within one
+    half-width of the input edges. If the filter is low-pass, then the output
+    may be less frequently sampled than the input.
 
     Full option list at :gmt-docs:`grdfilter.html`
 
@@ -54,11 +54,23 @@ def grdfilter(grid, **kwargs):
         The name of the output netCDF file with extension .nc to store the grid
         in.
     filter : str
-        ``xwidth[/width2][modifiers]``.
-        Name of filter type you which to apply, followed by the width
-        b: Box Car; c: Cosine Arch; g: Gaussian; o: Operator; m: Median;
-        p: Maximum Likelihood probability; h: histogram
-        Example: F='m600' for a median filter with width of 600
+        **b**\|\ **c**\|\ **g**\|\ **o**\|\ **m**\|\ **p**\|\ **h**\ *xwidth*\
+        [/*width2*\][*modifiers*].
+        Name of filter type you which to apply, followed by the width:
+
+        b: Box Car
+
+        c: Cosine Arch
+
+        g: Gaussian
+
+        o: Operator
+
+        m: Median
+
+        p: Maximum Likelihood probability
+
+        h: histogram
     distance : str
         Distance *flag* tells how grid (x,y) relates to filter width as
         follows:
@@ -87,10 +99,11 @@ def grdfilter(grid, **kwargs):
         Spherical distance calculation.
 
     spacing : str
-        ``xinc[+e|n][/yinc[+e|n]]``.
-        x_inc [and optionally y_inc] is the grid spacing.
+        *xinc*\[\ *unit*\][**+e**\|\ **n**]
+        [/*yinc*\ [*unit*][**+e**\|\ **n**]].
+        *xinc* [and optionally *yinc*] is the grid spacing.
     nans : str or float
-        ``i|p|r``.
+        **i**\|\ **p**\|\ **r**.
         Determine how NaN-values in the input grid affects the filtered output.
     {R}
     toggle : bool
diff --git a/pygmt/src/info.py b/pygmt/src/info.py
@@ -17,20 +17,21 @@
 @fmt_docstring
 @use_alias(C="per_column", I="spacing", T="nearest_multiple", V="verbose")
 def info(table, **kwargs):
-    """
+    r"""
     Get information about data tables.
 
     Reads from files and finds the extreme values in each of the columns
     reported as min/max pairs. It recognizes NaNs and will print warnings if
     the number of columns vary from record to record. As an option, it will
     find the extent of the first two columns rounded up and down to the nearest
-    multiple of the supplied increments given by *spacing*. Such output will be
-    in a numpy.ndarray form ``[w, e, s, n]``, which can be used directly as the
-    *region* argument for other modules (hence only dx and dy are needed). If
-    the *per_column* option 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 option *nearest_multiple* option will
-    provide a numpy.ndarray in the form of ``[zmin, zmax, dz]`` for makecpt.
+    multiple of the supplied increments given by ``spacing``. Such output will
+    be in a numpy.ndarray form [*w*, *e*, *s*, *n*], which can be used
+    directly as the ``region`` parameter for other modules (hence only *dx*
+    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.
 
     Full option list at :gmt-docs:`gmtinfo.html`
 
@@ -45,12 +46,12 @@ def info(table, **kwargs):
     per_column : bool
         Report the min/max values per column in separate columns.
     spacing : str
-        ``'[b|p|f|s]dx[/dy[/dz...]]'``.
+        [**b**\|\ **p**\|\ **f**\|\ **s**]\ *dx*\[/*dy*\[/*dz*...]].
         Report the min/max of the first n columns to the nearest multiple of
         the provided increments and output results in the form
         ``[w, e, s, n]``.
     nearest_multiple : str
-        ``'dz[+ccol]'``
+        **dz**\[\ **+c**\ *col*].
         Report the min/max of the first (0'th) column to the nearest multiple
         of dz and output this in the form ``[zmin, zmax, dz]``.
 
@@ -59,8 +60,8 @@ def info(table, **kwargs):
     Returns
     -------
     output : np.ndarray or str
-        Return type depends on whether any of the 'per_column', 'spacing', or
-        'nearest_multiple' parameters are set.
+        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.
         - str if none of the above parameters are used.
diff --git a/pygmt/src/makecpt.py b/pygmt/src/makecpt.py
@@ -26,12 +26,12 @@
 )
 @kwargs_to_strings(T="sequence", G="sequence")
 def makecpt(**kwargs):
-    """
+    r"""
     Make GMT color palette tables.
 
     This is a module that will help you make static color palette tables
     (CPTs). By default, the CPT will simply be saved to the current session,
-    but you can use *output* to save it to a file. You define an equidistant
+    but you can use ``output`` to save it to a file. You define an equidistant
     set of contour intervals or pass your own z-table or list, and create a new
     CPT based on an existing master (dynamic) CPT. The resulting CPT can be
     reversed relative to the master cpt, and can be made continuous or
@@ -49,8 +49,8 @@ def makecpt(**kwargs):
     the new master file. If not, the parameters :gmt-term:`COLOR_BACKGROUND`,
     :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` from the
     :gmt-docs:`gmt.conf <gmt.conf>` file or the command line will be used. This
-    default behavior can be overruled using the options *background*,
-    *overrule_bg* or *no_bg*.
+    default behavior can be overruled using the parameters ``background``,
+    ``overrule_bg`` or ``no_bg``.
 
     The color model (RGB, HSV or CMYK) of the palette created by **makecpt**
     will be the same as specified in the header of the master CPT. When there
@@ -81,7 +81,7 @@ def makecpt(**kwargs):
         ``background='i'`` to match the colors for the lowest and highest
         values in the input (instead of the output) CPT.
     color_model :
-        ``[R|r|h|c][+c[label]]``.
+        [**R**\|\ **r**\|\ **h**\|\ **c**][**+c**\ [*label*]].
         Force output CPT to be written with r/g/b codes, gray-scale values or
         color name (**R**, default) or r/g/b codes only (**r**), or h-s-v codes
         (**h**), or c/m/y/k codes (**c**).  Optionally or alternatively, append
@@ -93,7 +93,7 @@ def makecpt(**kwargs):
         labels from *start* (a single letter or an integer). Append - to build
         ranges *start*-*start+1* instead.
     series : list or str
-        ``[min/max/inc[+b|l|n]|file|list]``.
+        [*min/max/inc*\[**+b**\|\ **l**\|\ **n**]\|\ *file*\|\ *list*].
         Defines the range of the new CPT by giving the lowest and highest
         z-value (and optionally an interval). If this is not given, the
         existing range in the master CPT will be used intact. The values
@@ -102,21 +102,22 @@ def makecpt(**kwargs):
         For details on array creation, see
         :gmt-docs:`makecpt.html#generate-1d-array`.
     truncate : list or str
-        ``zlo/zhi``.
+        *zlow/zhigh*.
         Truncate the incoming CPT so that the lowest and highest z-levels are
-        to *zlo* and *zhi*. If one of these equal NaN then we leave that end of
-        the CPT alone. The truncation takes place before any resampling. See
+        to *zlow* and *zhigh*. If one of these equal NaN then we leave that
+        end of the CPT alone. The truncation takes place before any
+        resampling. See
         also :gmt-docs:`cookbook/features.html#manipulating-cpts`.
     output : str
         Optional. The file name with extension .cpt to store the generated CPT
         file. If not given or False (default), saves the CPT as the session
         current CPT.
     reverse : str
-        Set this to True or c [Default] to reverse the sense of color
+        Set this to True or **c**\ [Default] to reverse the sense of color
         progression in the master CPT. Set this to z to reverse the sign of
         z-values in the color table. Note that this change of z-direction
-        happens before *truncate* and *series* values are used so the latter
-        must be compatible with the changed *z*-range. See also
+        happens before ``truncate`` and ``series`` values are used so the
+        latter must be compatible with the changed *z*-range. See also
         :gmt-docs:`cookbook/features.html#manipulating-cpts`.
     overrule_bg : str
         Overrule background, foreground, and NaN colors specified in the master
diff --git a/pygmt/src/surface.py b/pygmt/src/surface.py
@@ -20,7 +20,7 @@
 @use_alias(I="spacing", R="region", G="outfile", V="verbose")
 @kwargs_to_strings(R="sequence")
 def surface(x=None, y=None, z=None, data=None, **kwargs):
-    """
+    r"""
     Grids table data using adjustable tension continuous curvature splines.
 
     Surface reads randomly-spaced (x,y,z) triples and produces gridded values
@@ -47,11 +47,12 @@ def surface(x=None, y=None, z=None, data=None, **kwargs):
         Either a data file name or a 2d numpy array with the tabular data.
 
     spacing : str
-        ``'xinc[unit][+e|n][/yinc[unit][+e|n]]'``.
-        x_inc [and optionally y_inc] is the grid spacing.
+        *xinc*\[\ *unit*\][**+e**\|\ **n**]\
+        [/*yinc*\ [*unit*][**+e**\|\ **n**]].
+        *xinc* [and optionally *yinc*] is the grid spacing.
 
     region : str or list
-        ``'xmin/xmax/ymin/ymax[+r][+uunit]'``.
+        *xmin/xmax/ymin/ymax*\[**+r**][**+u**\ *unit*].
         Specify the region of interest.
 
     outfile : str
diff --git a/pygmt/x2sys.py b/pygmt/x2sys.py
