Update the doc strings in the non-plotting modules

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`` option.
         """
         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,9 @@ 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 uses options ``t2, g2`` in
+            :meth:`pygmt.Figure.psconvert`. Ignored if creating vector
+            graphics.
         show: bool
             If True, will open the figure in an external viewer.
         dpi : int

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}
 

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

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

pygmt/src/info.py

@@ -17,7 +17,7 @@
 @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
@@ -26,11 +26,12 @@ def info(table, **kwargs):
     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.
+    ``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.
 
     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.

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 options ``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
@@ -90,10 +90,10 @@ def makecpt(**kwargs):
         CPT is plotted. The *label* may be a comma-separated list of category
         names (you can skip a category by not giving a name), or give
         *start*[-], where we automatically build monotonically increasing
-        labels from *start* (a single letter or an integer). Append - to build
+        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,7 +102,7 @@ def makecpt(**kwargs):
         For details on array creation, see
         :gmt-docs:`makecpt.html#generate-1d-array`.
     truncate : list or str
-        ``zlo/zhi``.
+        *zlo/zhi*\ .
         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
@@ -112,11 +112,11 @@ def makecpt(**kwargs):
         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

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