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