Update the docstrings in the plotting modules (#881)

Update docstrings in basemap, coast, colorbar, contour,
grdcontour, grdimage, grdview, image, inset, legend, logo,
plot, plot3d, and text following the convention in #631.
Also fixed an unescaped return in decorators.py.

Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Will Schlitzer <[email protected]>
Co-authored-by: Wei Ji <[email protected]>

pygmt/helpers/decorators.py

@@ -98,7 +98,7 @@
             - **n** for nearest-neighbor""",
     "p": r"""
         perspective : list or str
-            [**x**\|\ **y**\|\ **z**]\ *azim*\[/*elev*\[/*zlevel*]]
+            [**x**\|\ **y**\|\ **z**]\ *azim*\[/*elev*\[/*zlevel*]]\
             [**+w**\ *lon0*/*lat0*\[/*z0*]][**+v**\ *x0*/*y0*].
             Select perspective view and set the azimuth and elevation angle of
             the viewpoint. Default is [180, 90]. Full documentation is at

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 parameters ``frame``, ``map_scale``, ``rose`` or
+    ``compass`` must be specified.
 
     Full option list at :gmt-docs:`basemap.html`
 
@@ -56,7 +56,8 @@ def basemap(self, **kwargs):
     {R}
     {B}
     map_scale : str
-        ``'[g|j|J|n|x]refpoint'``
+        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
+        **+w**\ *length*.
         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,12 +66,11 @@ 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*].
-        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.
+        *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\ :sup:`2` or of
+        hierarchical level that is lower than *min_level* or higher than
+        *max_level* will not be plotted.
     {B}
     lakes : str or list
         *fill*\ [**+l**\|\ **+r**].
@@ -90,7 +89,7 @@ def coast(self, **kwargs):
     rivers : int or str or list
         *river*\ [/*pen*].
         Draw rivers. Specify the type of rivers and [optionally] append
-        pen attributes [Default pen: width = default, color = black,
+        pen attributes [Default pen is width = default, color = black,
         style = solid].
 
         Choose from the list of river types below; pass a list to
@@ -132,12 +131,13 @@ def coast(self, **kwargs):
 
         c = All canals (8-10)
     map_scale : str
-        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*.
+        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
+        **+w**\ *length*.
         Draws a simple map scale centered on the reference point specified.
     borders : int or str or list
         *border*\ [/*pen*].
         Draw political boundaries. Specify the type of boundary and
-        [optionally] append pen attributes [Default pen: width = default,
+        [optionally] append pen attributes [Default pen is width = default,
         color = black, style = solid].
 
         Choose from the list of boundaries below. Pass a list to
@@ -156,7 +156,7 @@ def coast(self, **kwargs):
     shorelines : int or str or list
         [*level*\ /]\ *pen*.
         Draw shorelines [Default is no shorelines]. Append pen attributes
-        [Defaults: width = default, color = black, style = solid] which
+        [Default is width = default, color = black, style = solid] which
         apply to all four levels. To set the pen for a single level,
         pass a string with *level*\ /*pen*\ , where level is
         1-4 and represent coastline, lakeshore, island-in-lake shore, and
@@ -177,11 +177,9 @@ def coast(self, **kwargs):
         prepend **=** to any of the continent codes (e.g. =EU for Europe).
         Append **+p**\ *pen* to draw polygon outlines
         (default is no outline) and **+g**\ *fill* to fill them
-        (default is no fill). Append **+l**\|\ **+L** to *=continent* to
+        (default is no fill). Append **+l**\|\ **+L** to =\ *continent* to
         only list countries in that continent; repeat if more than one
-        continent is requested. Append **+z** to place the country code in
-        the segment headers via **-Z**\ *code* settings.To apply different
-        settings to different countries, pass a list of string arguments.
+        continent is requested.
     {XY}
     {c}
     {p}

pygmt/src/colorbar.py

@@ -28,16 +28,16 @@
     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
     gradational colors (i.e., the lower and upper boundary of an interval
     have different colors) we will interpolate to give a continuous scale.
     Variations in intensity due to shading/illumination may be displayed by
-    setting the option -I. Colors may be spaced according to a linear
-    scale, all be equal size, or by providing a file with individual tile
-    widths.
+    setting the ``shading`` parameter. Colors may be spaced according to a
+    linear scale, all be equal size, or by providing a file with individual
+    tile widths.
 
     Full option list at :gmt-docs:`colorbar.html`
 
@@ -49,52 +49,56 @@ 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
-        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*
-        and *projection* to be specified. Append +w followed by the length
-        and width of the color bar. If width is not specified then it is
+        [**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``
+        and ``projection`` to be specified. Append **+w** followed by the
+        length and width of the color bar. If width is not specified then it is
         set to 4% of the given length. Give a negative length to reverse
-        the scale bar. Append +h to get a horizontal scale
-        [Default is vertical (+v)]. By default, the anchor point on the
-        scale is assumed to be the bottom left corner (BL), but this can be
-        changed by appending +j followed by a 2-char justification code
+        the scale bar. Append **+h** to get a horizontal scale
+        [Default is vertical (**+v**)]. By default, the anchor point on the
+        scale is assumed to be the bottom left corner (**BL**), but this can be
+        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
-        offset background shaded region. Here, dx/dy indicates the shift
+        [**+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 **+p**\ *pen*. Add
+        **+g**\ *fill* to fill the scale panel [default is no fill]. Append
+        **+c**\ *clearance* 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 :gmt-term:`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].
+        style to use for shading [default is 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.
     shading : str or list or bool
         Add illumination effects. Passing a single numerical value sets the
         range of intensities from -value to +value. If not specified, 1 is
         used. Alternatively, set ``shading=[low, high]`` to specify an
-        asymmetric intensity range from *low* to *high*. The default is no
-        illumination.
+        asymmetric intensity range from *low* to *high*. [Default is no
+        illumination].
     {V}
     {XY}
     {c}

pygmt/src/contour.py

@@ -43,7 +43,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
     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``.
 
     Full option list at :gmt-docs:`contour.html`
 
@@ -67,23 +67,24 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
     levels : str
         Contour file or level(s)
     D : str
-        Dump contour coordinates
+        Dump contour coordinates.
     E : str
-        Network information
+        Network information.
     label_placement : str
-        Placement of labels
+        Placement of labels.
     I : bool
-        Color the triangles using CPT
+        Color the triangles using CPT.
     triangular_mesh_pen : str
-        Pen to draw the underlying triangulation (default none)
+        Pen to draw the underlying triangulation [Default is none].
     no_clip : bool
         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.
@@ -57,23 +57,23 @@ def grdcontour(self, grid, **kwargs):
         - The filename of a `CPT`  file where the color boundaries will
           be used as contour levels.
         - The filename of a 2 (or 3) column file containing the contour
-          levels (col 1), (C)ontour or (A)nnotate (col 2), and optional
+          levels (col 1), (**C**)ontour or (**A**)nnotate (col 2), and optional
           angle (col 3)
-        - A fixed contour interval ``cont_int`` or a single contour with
-          ``+[cont_int]``
+        - A fixed contour interval *cont_int* or a single contour with
+          +\ *cont_int*
     annotation : str,  int, or list
         Specify or disable annotated contour levels, modifies annotated
-        contours specified in ``-C``.
+        contours specified in ``interval``.
 
-        - Specify a fixed annotation interval ``annot_int`` or a
-          single annotation level ``+[annot_int]``
-        - Disable all annotation  with  ``'-'``
+        - Specify a fixed annotation interval *annot_int* or a
+          single annotation level +\ *annot_int*
+        - Disable all annotation with  **-**
         - Optional label modifiers can be specified as a single string
-          ``'[annot_int]+e'``  or with a list of options
+          ``'[annot_int]+e'``  or with a list of arguments
           ``([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,8 +82,9 @@ def grdcontour(self, grid, **kwargs):
     {R}
     {B}
     label_placement : str
-        ``[d|f|n|l|L|x|X]params``.
-        The required argument controls the placement of labels along the
+        [**d**\|\ **f**\|\ **n**\|\ **l**\|\ **L**\|\ **x**\|\ **X**]\
+        *args*.
+        The required parameter controls the placement of labels along the
         quoted lines. It supports five controlling algorithms. See
         :gmt-docs:`grdcontour.html#g` for details.
     {U}