Update the docstrings in the plotting modules

pygmt/src/basemap.py

@@ -33,16 +33,16 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def basemap(self, **kwargs):
-    """
+    r"""
     Plot base maps and frames for the figure.
 
     Creates a basic or fancy basemap with axes, fill, and titles. Several
     map projections are available, and the user may specify separate
     tick-mark intervals for boundary annotation, ticking, and [optionally]
     gridlines. A simple map scale or directional rose may also be plotted.
 
-    At least one of the options *frame*, *map_scale*, *rose* or *compass*
-    must be specified.
+    At least one of the options **frame**, **map_scale**, **rose** or
+    **compass** must be specified.
 
     Full option list at :gmt-docs:`basemap.html`
 
@@ -56,7 +56,7 @@ def basemap(self, **kwargs):
     {R}
     {B}
     map_scale : str
-        ``'[g|j|J|n|x]refpoint'``
+        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*
         Draws a simple map scale centered on the reference point specified.
     rose : str
         Draws a map directional rose on the map at the location defined by

pygmt/src/coast.py

@@ -66,9 +66,8 @@ def coast(self, **kwargs):
     {J}
     {R}
     area_thresh : int, float, or str
-        *min_area*\ [/*min_level*/*max_level*][**+ag**\|\ **i**\
-        \|\ **s**\|\ **S**][**+r**\|\ **l**][**+p**\
-        *percent*].
+        *min_area*\ [/*min_level*/*max_level*][**+a**\[**g**\|\ **i**]
+        [**s**\|\ **S**][**+l**\|\ **r**][**+p**\ *percent*].
         Features with an area smaller than min_area in km^2 or of
         hierarchical level that is lower than min_level or higher than
         max_level will not be plotted.

pygmt/src/colorbar.py

@@ -28,7 +28,7 @@
     R="sequence", G="sequence", I="sequence", c="sequence_comma", p="sequence"
 )
 def colorbar(self, **kwargs):
-    """
+    r"""
     Plot a gray or color scale-bar on maps.
 
     Both horizontal and vertical scales are supported. For CPTs with
@@ -49,11 +49,14 @@ def colorbar(self, **kwargs):
         Set color bar boundary frame, labels, and axes attributes.
     {CPT}
     position : str
-        ``[g|j|J|n|x]refpoint[+wlength[/width]][+e[b|f][length]][+h|v]
-        [+jjustify][+m[a|c|l|u]][+n[txt]][+odx[/dy]]``. Defines the
-        reference point on the map for the color scale using one of four
-        coordinate systems: (1) Use *g* for map (user) coordinates, (2) use
-        *j* or *J* for setting refpoint via a 2-char justification code
+        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*
+        [**+w**\ *length*\ [/\ *width*]]\ [**+e**\ [**b**\|\ **f**][*length*]]
+        [**+h**\|\ **v**][**+j**\ *justify*]
+        [**+m**\ [**a**\|\ **c**\|\ **l**\|\ **u**]]
+        [**+n**\ [*txt*]][**+o**\ *dx*\ [/*dy*]].
+        Defines the reference point on the map for the color scale using one of
+        four coordinate systems: (1) Use *g* for map (user) coordinates, (2)
+        use *j* or *J* for setting refpoint via a 2-char justification code
         that refers to the (invisible) map domain rectangle, (3) use *n*
         for normalized (0-1) coordinates, or (4) use *x* for plot
         coordinates (inches, cm, etc.). All but *x* requires both *region*
@@ -66,26 +69,26 @@ def colorbar(self, **kwargs):
         changed by appending +j followed by a 2-char justification code
         *justify*.
     box : bool or str
-        ``[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]]
-        [+s[[dx/dy/][shade]]]``. If set to True, draws a rectangular
-        border around the color scale. Alternatively, specify a different
-        pen with +ppen. Add +gfill to fill the scale panel [no fill].
-        Append +cclearance where clearance is either gap, xgap/ygap, or
-        lgap/rgap/bgap/tgap where these items are uniform, separate in x-
-        and y-direction, or individual side spacings between scale and
-        border. Append +i to draw a secondary, inner border as well. We use
-        a uniform gap between borders of 2p and the MAP_DEFAULTS_PEN unless
-        other values are specified. Append +r to draw rounded rectangular
-        borders instead, with a 6p corner radius. You can override this
-        radius by appending another value. Finally, append +s to draw an
+        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]
+        [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
+        If set to True, draws a rectangular border around the color scale.
+        Alternatively, specify a different pen with +ppen. Add +gfill to fill
+        the scale panel [no fill]. Append +cclearance where clearance is either
+        gap, xgap/ygap, or lgap/rgap/bgap/tgap where these items are uniform,
+        separate in x- and y-direction, or individual side spacings between
+        scale and border. Append +i to draw a secondary, inner border as well.
+        We use a uniform gap between borders of 2p and the MAP_DEFAULTS_PEN
+        unless other values are specified. Append +r to draw rounded
+        rectangular borders instead, with a 6p corner radius. You can override
+        this radius by appending another value. Finally, append +s to draw an
         offset background shaded region. Here, dx/dy indicates the shift
         relative to the foreground frame [4p/-4p] and shade sets the fill
         style to use for shading [gray50].
     truncate : list or str
-        ``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 the plotting.
+        *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 the plotting.
     scale : float
         Multiply all z-values in the CPT by the provided scale. By default
         the CPT is used as is.

pygmt/src/contour.py

@@ -36,13 +36,13 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
 def contour(self, x=None, y=None, z=None, data=None, **kwargs):
-    """
+    r"""
     Contour table data by direct triangulation.
 
     Takes a matrix, (x,y,z) pairs, or a file name as input and plots lines,
     polygons, or symbols at those locations on a map.
 
-    Must provide either *data* or *x*, *y*, and *z*.
+    Must provide either **data** or **x**/**y**/**z**.
 
     [TODO: Insert more documentation]
 
@@ -79,10 +79,11 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
         Do NOT clip contours or image at the boundaries [Default will clip
         to fit inside region].
     Q : float or str
+        [*cut*][**+z**].
         Do not draw contours with less than cut number of points.
-        ``'[cut[unit]][+z]'``
     skip : bool or str
-        Skip input points outside region ``'[p|t]'``
+        [**p**\|\ **t**].
+        Skip input points outside region
     {W}
     label : str
         Add a legend entry for the contour being plotted. Normally, the

pygmt/src/grdcontour.py

@@ -38,7 +38,7 @@
     R="sequence", L="sequence", A="sequence_plus", c="sequence_comma", p="sequence"
 )
 def grdcontour(self, grid, **kwargs):
-    """
+    r"""
     Convert grids or images to contours and plot them on maps.
 
     Takes a grid file name or an xarray.DataArray object as input.
@@ -72,8 +72,8 @@ def grdcontour(self, grid, **kwargs):
           ``'[annot_int]+e'``  or with a list of options
           ``([annot_int], 'e', 'f10p', 'gred')``.
     limit : str or list of 2 ints
+        *low*/*high*
         Do no draw contours below `low` or above `high`, specify as string
-        ``'[low]/[high]'``  or list ``[low,high]``.
     cut : str or int
         Do not draw contours with less than `cut` number of points.
     resample : str or int
@@ -82,7 +82,7 @@ def grdcontour(self, grid, **kwargs):
     {R}
     {B}
     label_placement : str
-        ``[d|f|n|l|L|x|X]params``.
+        [**d**\|\ **f**\|\ **n**\|\ **l**\|\ **L**\|\ **x**\|\ **X**]\ *params*
         The required argument controls the placement of labels along the
         quoted lines. It supports five controlling algorithms. See
         :gmt-docs:`grdcontour.html#g` for details.

pygmt/src/grdimage.py

@@ -39,7 +39,7 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def grdimage(self, grid, **kwargs):
-    """
+    r"""
     Project and plot grids or images.
 
     Reads a 2-D grid file and produces a gray-shaded (or colored) map by
@@ -81,7 +81,7 @@ def grdimage(self, grid, **kwargs):
         set or image to be plotted (See GRID FILE FORMATS at
         :gmt-docs:`grdimage.html#grid-file-formats`).
     img_out : str
-        ``out_img[=driver]``.
+        *out_img*\[=\ *driver*].
         Save an image in a raster format instead of PostScript. Use
         extension .ppm for a Portable Pixel Map format which is the only
         raster format GMT can natively write. For GMT installations
@@ -101,7 +101,7 @@ def grdimage(self, grid, **kwargs):
     {B}
     {CPT}
     img_in : str
-        ``[r]``
+        [**r**].
         GMT will automatically detect standard image files (Geotiff, TIFF,
         JPG, PNG, GIF, etc.) and will read those via GDAL. For very obscure
         image formats you may need to explicitly set *img_in*, which
@@ -111,33 +111,33 @@ def grdimage(self, grid, **kwargs):
         image will be assigned a global domain. This mode allows you to
         project a raw image (an image without referencing coordinates).
     dpi : int
-        ``[i|dpi]``.
+        [**i**\|\ *dpi*].
         Sets the resolution of the projected grid that will be created if a
         map projection other than Linear or Mercator was selected [100]. By
         default, the projected grid will be of the same size (rows and
         columns) as the input file. Specify **i** to use the PostScript
         image operator to interpolate the image at the device resolution.
     bit_color : str
-        ``color[+b|f]``.
+        *color*\ [**+b**\|\ **f**\].
         This option only applies when a resulting 1-bit image otherwise
         would consist of only two colors: black (0) and white (255). If so,
         this option will instead use the image as a transparent mask and
         paint the mask with the given color. Append **+b** to paint the
         background pixels (1) or **+f** for the foreground pixels
         [Default].
     shading : str
-        ``[intensfile|intensity|modifiers]``.
+        *intensfile*\|\ *intensity*\|\ *modifiers*.
         Give the name of a grid file with intensities in the (-1,+1) range,
         or a constant intensity to apply everywhere (affects the ambient
         light). Alternatively, derive an intensity grid from the input data
         grid via a call to `grdgradient`; append **+a**\\ *azimuth*,
         **+n**\\ *args*, and **+m**\\ *ambient* to specify azimuth,
         intensity, and ambient arguments for that module, or just give
-        **+d** to select the default arguments (``+a-45+nt1+m0``). If you
-        want a more specific intensity scenario then run `grdgradient`
-        separately first. If we should derive intensities from another file
-        than grid, specify the file with suitable modifiers [Default is no
-        illumination].
+        **+d** to select the default arguments
+        (**+a**\ -45\ **+nt**\ 1\ **+m**\ 0). If you want a more specific
+        intensity scenario then run `grdgradient` separately first. If we
+        should derive intensities from another file than grid, specify the file
+        with suitable modifiers [Default is no illumination].
     {J}
     monochrome : bool
         Force conversion to monochrome image using the (television) YIQ

pygmt/src/grdview.py

@@ -39,7 +39,7 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def grdview(self, grid, **kwargs):
-    """
+    r"""
     Create 3-D perspective image or surface mesh from a grid.
 
     Reads a 2-D grid file and produces a 3-D perspective plot by drawing a
@@ -58,58 +58,52 @@ def grdview(self, grid, **kwargs):
     grid : str or xarray.DataArray
         The file name of the input relief grid or the grid loaded as a
         DataArray.
-
     zscale/zsize : float or str
         Set z-axis scaling or z-axis size.
-
     {B}
-
     cmap : str
         The name of the color palette table to use.
-
     drapegrid : str or xarray.DataArray
         The file name or a DataArray of the image grid to be draped on top
         of the relief provided by grid. [Default determines colors from
-        grid]. Note that -Jz and -N always refers to the grid. The
-        drapegrid only provides the information pertaining to colors, which
-        (if drapegrid is a grid) will be looked-up via the CPT (see -C).
-
+        grid]. Note that **zscale** and **plane** always refers to the grid.
+        The drapegrid only provides the information pertaining to colors, which
+        (if drapegrid is a grid) will be looked-up via the CPT (see **cmap**).
     plane : float or str
-        ``level[+gfill]``.
+        *level*\ [**+g**\ *fill*].
         Draws a plane at this z-level. If the optional color is provided
-        via the +g modifier, and the projection is not oblique, the frontal
+        via the **+g** modifier, and the projection is not oblique, the frontal
         facade between the plane and the data perimeter is colored.
-
     surftype : str
         Specifies cover type of the grid.
         Select one of following settings:
-        1. 'm' for mesh plot [Default].
-        2. 'mx' or 'my' for waterfall plots (row or column profiles).
-        3. 's' for surface plot.
-        4. 'i' for image plot.
-        5. 'c'. Same as 'i' but will make nodes with z = NaN transparent.
-        For any of these choices, you may force a monochrome image by
-        appending the modifier +m.
 
+        - **m** - mesh plot [Default].
+        - **mx** or **my** - waterfall plots (row or column profiles).
+        - **s** - surface plot, and optionally append **m** to have mesh lines
+          drawn on top of the surface.
+        - **i** - image plot.
+        - **c** - Same as **i** but will make nodes with z = NaN transparent.
+        For any of these choices, you may force a monochrome image by
+        appending the modifier **+m**.
     contourpen : str
         Draw contour lines on top of surface or mesh (not image). Append
         pen attributes used for the contours.
     meshpen : str
-        Sets the pen attributes used for the mesh. You must also select -Qm
-        or -Qsm for meshlines to be drawn.
+        Sets the pen attributes used for the mesh. You must also select
+        **surftype** of **m** or **sm** for meshlines to be drawn.
     facadepen :str
         Sets the pen attributes used for the facade. You must also select
-        -N for the facade outline to be drawn.
-
+        **plane** for the facade outline to be drawn.
     shading : str
         Provide the name of a grid file with intensities in the (-1,+1)
         range, or a constant intensity to apply everywhere (affects the
         ambient light). Alternatively, derive an intensity grid from the
         input data grid reliefgrid via a call to ``grdgradient``; append
-        ``+aazimuth``, ``+nargs``, and ``+mambient`` to specify azimuth,
-        intensity, and ambient arguments for that module, or just give
-        ``+d`` to select the default arguments (``+a-45+nt1+m0``).
-
+        **+a**\ *azimuth*, **+n**\ *args*, and **+m**\ *ambient* to specify
+        azimuth, intensity, and ambient arguments for that module, or just give
+        **+d** to select the default arguments
+        (**+a**\ -45\ **+nt**\ 1\ **+m**\ 0).
     {V}
     {XY}
     {c}

pygmt/src/image.py

@@ -21,7 +21,7 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def image(self, imagefile, **kwargs):
-    """
+    r"""
     Place images or EPS files on maps.
 
     Reads an Encapsulated PostScript file or a raster image file and plots
@@ -42,13 +42,16 @@ def image(self, imagefile, **kwargs):
     {J}
     {R}
     position : str
-        ``'[g|j|J|n|x]refpoint+rdpi+w[-]width[/height][+jjustify]
-        [+nnx[/ny]][+odx[/dy]]'`` Sets reference point on the map for the
+        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+r**\ *dpi*
+        **+w**\ [**-**]\ *width*\ [/*height*]\ [**+j**\ *justify*]
+        [**+n**\ *nx*\ [/*ny*] ]\ [**+o**\ *dx*\ [/*dy*]].
+        Sets reference point on the map for the
         image.
     box : bool or str
-        ``'[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]]
-        [+s[[dx/dy/][shade]]]'`` Without further options, draws a
-        rectangular border around the image using **MAP_FRAME_PEN**.
+        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]
+        [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
+        Without further options, draws a rectangular border around the image
+        using **MAP_FRAME_PEN**.
     monochrome : bool
         Convert color image to monochrome grayshades using the (television)
         YIQ-transformation.

pygmt/src/legend.py

@@ -28,7 +28,7 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwargs):
-    """
+    r"""
     Plot legends on maps.
 
     Makes legends that can be overlaid on maps. Reads specific
@@ -50,16 +50,19 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
     {J}
     {R}
     position : str
-        ``'[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+lspacing]
-        [+odx[/dy]]'`` Defines the reference point on the map for the
+        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*
+        **+w**\ *width*\ [/*height*]\ [**+j**\ *justify*]\ [**+l**\ *spacing*]
+        [**+o**\ *dx*\ [/*dy*]].
+        Defines the reference point on the map for the
         legend. By default, uses 'JTR+jTR+o0.2c' which places the legend at
         the top-right corner inside the map frame, with a 0.2 cm offset.
     box : bool or str
-        ``'[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]]
-        [+s[[dx/dy/][shade]]]'`` Without further options, draws a
-        rectangular border around the legend using **MAP_FRAME_PEN**. By
-        default, uses '+gwhite+p1p' which draws a box around the legend
-        using a 1 point black pen and adds a white background.
+        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]
+        [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
+        Without further options, draws a rectangular border around the legend
+        using **MAP_FRAME_PEN**. By default, uses **+g**\ white\ **+p**\ 1p
+        which draws a box around the legend using a 1 point black pen and adds
+        a white background.
     {V}
     {XY}
     {c}