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,9 +149,10 @@ 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
@@ -178,7 +179,7 @@ def savefig(
         Save the figure to a file.
 
         This method implements a matplotlib-like interface for
-        :meth:`~gmt.Figure.psconvert`.
+        :doc:psconvert </psconvert>.
 
         Supported formats: PNG (``.png``), JPEG (``.jpg``), PDF (``.pdf``),
         BMP (``.bmp``), TIFF (``.tif``), EPS (``.eps``), and KML (``.kml``).
@@ -199,9 +200,8 @@ 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
+            :doc:psconvert </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,11 +39,12 @@ def blockmedian(table, outfile=None, **kwargs):
         ASCII data table.
 
     spacing : str
-        ``'xinc[unit][+e|n][/yinc[unit][+e|n]]'``.
+        *xinc*\[\ *unit*\][**+e**\|\ **n**]
+        [/*yinc*\ [*unit*][**+e**\|\ **n**]].
         x_inc [and optionally y_inc] 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

pygmt/src/grdcut.py

@@ -28,7 +28,7 @@
 )
 @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
@@ -57,13 +57,13 @@ def grdcut(grid, **kwargs):
         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,7 +29,7 @@
 )
 @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
@@ -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]]``.
+        *xinc*\[\ *unit*\][**+e**\|\ **n**]
+        [/*yinc*\ [*unit*][**+e**\|\ **n**]].
         x_inc [and optionally y_inc] 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
@@ -45,12 +45,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]``.
 

pygmt/src/makecpt.py

@@ -26,7 +26,7 @@
 )
 @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
@@ -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,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

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]]'``.
+        *xinc*\[\ *unit*\][**+e**\|\ **n**]
+        [/*yinc*\ [*unit*][**+e**\|\ **n**]].
         x_inc [and optionally y_inc] 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

pygmt/x2sys.py

@@ -69,7 +69,7 @@ def tempfile_from_dftrack(track, suffix):
 )
 @kwargs_to_strings(I="sequence", R="sequence")
 def x2sys_init(tag, **kwargs):
-    """
+    r"""
     Initialize a new x2sys track database.
 
     x2sys_init is the starting point for anyone wishing to use x2sys; it
@@ -113,21 +113,22 @@ def x2sys_init(tag, **kwargs):
         *fmtfile*).
 
     discontinuity : str
-        ``d|g``
+        **d**\|\ **g**.
         Selects geographical coordinates. Append **d** for discontinuity at the
         Dateline (makes longitude go from -180 to + 180) or **g** for
         discontinuity at Greenwich (makes longitude go from 0 to 360
         [Default]). If not given we assume the data are Cartesian.
 
     spacing : str or list
-         ``dx[/dy]``
+         *dx*\[/*dy*\].
          x_inc [and optionally y_inc] is the grid spacing. Append **m** to
          indicate minutes or **s** to indicate seconds for geographic data.
          These spacings refer to the binning used in the track bin-index data
          base.
 
     units : str or list
-        ``d|sunit``.
+        **d**\|\ **s**\
+        **c**\|\ **e**\|\ **f**\|\ **k**\|\ **m**\|\ **n**\|\ **u** .
         Sets the units used for distance and speed when requested by other
         programs. Append **d** for distance or **s** for speed, then give the
         desired unit as:
@@ -147,7 +148,7 @@ def x2sys_init(tag, **kwargs):
     {V}
 
     gap : str or list
-        ``t|dgap``.
+        **t**\|\ **d**\ *gap*.
         Give **t** or **d** and append the corresponding maximum time gap (in
         user units; this is typically seconds [Infinity]), or distance (for
         units, see *units*) gap [Infinity]) allowed between the two data points
@@ -177,7 +178,7 @@ def x2sys_init(tag, **kwargs):
 )
 @kwargs_to_strings(R="sequence")
 def x2sys_cross(tracks=None, outfile=None, **kwargs):
-    """
+    r"""
     Calculate crossovers between track data files.
 
     x2sys_cross is used to determine all intersections between ("external
@@ -231,7 +232,7 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs):
         split_file4coes.m that lives in the x2sys supplement source code.
 
     override : bool or str
-        ``S|N``.
+        **S**\|\ **N**.
         Control how geographic coordinates are handled (Cartesian data are
         unaffected). By default, we determine if the data are closer to one
         pole than the other, and then we use a cylindrical polar conversion to
@@ -245,7 +246,7 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs):
         longitudinal range at higher latitudes.
 
     interpolation : str
-        ``l|a|c``.
+        **l**\|\ **a**\|\ **c**.
         Sets the interpolation mode for estimating values at the crossover.
         Choose among:
 
@@ -260,7 +261,7 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs):
     {R}
 
     speed : str or list
-        ``l|u|hspeed``.
+        **l**\|\ **u**\|\ **h**\ *speed*.
         Defines window of track speeds. If speeds are outside this window we do
         not calculate a COE. Specify: