diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py
index 364908f9319..36b1a87dd9a 100644
--- a/pygmt/helpers/decorators.py
+++ b/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
diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py
index 678540c48f7..95a2406d448 100644
--- a/pygmt/src/basemap.py
+++ b/pygmt/src/basemap.py
@@ -33,7 +33,7 @@
 )
 @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
@@ -41,8 +41,8 @@ def basemap(self, **kwargs):
     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
diff --git a/pygmt/src/coast.py b/pygmt/src/coast.py
index 38f3719d47a..02012b99c89 100644
--- a/pygmt/src/coast.py
+++ b/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}
diff --git a/pygmt/src/colorbar.py b/pygmt/src/colorbar.py
index f523ab63609..3fd25c8ee99 100644
--- a/pygmt/src/colorbar.py
+++ b/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,43 +49,47 @@ 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.
@@ -93,8 +97,8 @@ def colorbar(self, **kwargs):
         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}
diff --git a/pygmt/src/contour.py b/pygmt/src/contour.py
index 33fe31cd964..9578d26e9be 100644
--- a/pygmt/src/contour.py
+++ b/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
diff --git a/pygmt/src/grdcontour.py b/pygmt/src/grdcontour.py
index 932e5b7a89e..bf700961fcb 100644
--- a/pygmt/src/grdcontour.py
+++ b/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}
diff --git a/pygmt/src/grdimage.py b/pygmt/src/grdimage.py
index 9658164677b..8922fbaad3b 100644
--- a/pygmt/src/grdimage.py
+++ b/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
@@ -47,17 +47,15 @@ def grdimage(self, grid, **kwargs):
     color) based on the z-value and the CPT file. Optionally, illumination
     may be added by providing a file with intensities in the (-1,+1) range
     or instructions to derive intensities from the input data grid. Values
-    outside this range will be clipped. Such intensity files can be created
-    from the grid using `grdgradient` and, optionally, modified by
-    `grdmath` or `grdhisteq`. If GMT is built with GDAL support, *grid* can
-    be an image file (geo-referenced or not). In this case the image can
-    optionally be illuminated with the file provided via the *shading*
-    option. Here, if image has no coordinates then those of the intensity
-    file will be used.
+    outside this range will be clipped. If GMT is built with GDAL support,
+    ``grid`` can be an image file (geo-referenced or not). In this case the
+    image can optionally be illuminated with the file provided via the
+    ``shading`` parameter. Here, if image has no coordinates then those of the
+    intensity file will be used.
 
     When using map projections, the grid is first resampled on a new
     rectangular grid with the same dimensions. Higher resolution images can
-    be obtained by using the *dpi* option. To obtain the resampled value
+    be obtained by using the ``dpi`` parameter. To obtain the resampled value
     (and hence shade or color) of each map pixel, its location is inversely
     projected back onto the input grid after which a value is interpolated
     between the surrounding input grid values. By default bi-cubic
@@ -65,12 +63,12 @@ def grdimage(self, grid, **kwargs):
     the input grid nodes. If two or more nodes are projected onto the same
     pixel, their average will dominate in the calculation of the pixel
     value. Interpolation and aliasing is controlled with the
-    *interpolation* option.
+    ``interpolation`` parameter.
 
-    The *region* option can be used to select a map region larger or
+    The ``region`` parameter can be used to select a map region larger or
     smaller than that implied by the extent of the grid.
 
-    Full option list at :gmt-docs:`grdimage.html`
+    Full parameter list at :gmt-docs:`grdimage.html`
 
     {aliases}
 
@@ -81,7 +79,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
@@ -91,8 +89,8 @@ def grdimage(self, grid, **kwargs):
         information is required. For other output formats you must append
         the required GDAL driver. The *driver* is the driver code name used
         by GDAL; see your GDAL installation's documentation for available
-        drivers. Append a **+c**\\ *options* string where options is a list
-        of one or more concatenated number of GDAL **-co** options. For
+        drivers. Append a **+c**\ *args* string where *args* is a list
+        of one or more concatenated number of GDAL **-co** arguments. For
         example, to write a GeoPDF with the TerraGo format use
         ``=PDF+cGEO_ENCODING=OGC_BP``. Notes: (1) If a tiff file (.tif) is
         selected then we will write a GeoTiff image if the GMT projection
@@ -101,47 +99,47 @@ 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
+        image formats you may need to explicitly set ``img_in``, which
         specifies that the grid is in fact an image file to be read via
-        GDAL. Append **r** to assign the region specified by *region*
+        GDAL. Append **r** to assign the region specified by ``region``
         to the image. For example, if you have used ``region='d'`` then the
         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]``.
-        This option only applies when a resulting 1-bit image otherwise
+        *color*\ [**+b**\|\ **f**\].
+        This parameter 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
+        this parameter 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].
+        [Default is **+f**].
     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,
+        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
+        [Default is **+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
-        transformation. Cannot be used with *nan_transparent*.
+        transformation. Cannot be used with ``nan_transparent``.
     no_clip : bool
         Do not clip the image at the map boundary (only relevant for
         non-rectangular maps).
diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py
index 77127e343d9..15c9fc3bfc1 100644
--- a/pygmt/src/grdview.py
+++ b/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,53 @@ 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
+        [Default is **+a**\ -45\ **+nt**\ 1\ **+m**\ 0].
     {V}
     {XY}
     {c}
diff --git a/pygmt/src/image.py b/pygmt/src/image.py
index 9864422a120..769f18835bc 100644
--- a/pygmt/src/image.py
+++ b/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,15 @@ 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
-        image.
+        [**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 arguments, draws a rectangular border around the image
+        using :gmt-term:`MAP_FRAME_PEN`.
     monochrome : bool
         Convert color image to monochrome grayshades using the (television)
         YIQ-transformation.
diff --git a/pygmt/src/inset.py b/pygmt/src/inset.py
index 95a5a04089a..45fabacce53 100644
--- a/pygmt/src/inset.py
+++ b/pygmt/src/inset.py
@@ -28,10 +28,10 @@ def inset(self, **kwargs):
     position : str or list
         *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*]] \
         | [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
-        **+w**\ *width*\ [/*height*][**+j**\ *justify*]
-        [**+o**\ *dx*\ [/*dy*]]
+        **+w**\ *width*\ [/*height*][**+j**\ *justify*]\
+        [**+o**\ *dx*\ [/*dy*]].
 
-        *This is the only required argument.*
+        *This is the only required parameter.*
         Define the map inset rectangle on the map. Specify the rectangle
         in one of three ways:
 
@@ -46,7 +46,7 @@ def inset(self, **kwargs):
         **+o**\ *dx*/*dy* in the direction implied by *code* or
         **+j**\ *justify*.
 
-        Alternatively, Give *west/east/south/north* of geographic
+        Alternatively, give *west/east/south/north* of geographic
         rectangle bounded by parallels and meridians; append **+r** if the
         coordinates instead are the lower left and upper right corners of
         the desired rectangle. (Or, give *xmin/xmax/ymin/ymax* of bounding
@@ -55,17 +55,17 @@ def inset(self, **kwargs):
 
         Append **+w**\ *width*\ [/*height*] of bounding rectangle or box
         in plot coordinates (inches, cm, etc.). By default, the anchor
-        point on the scale is assumed to be the bottom left corner (BL),
+        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*.
         **Note**: If **j** is used then *justify* defaults to the same
         as *refpoint*, if **J** is used then *justify* defaults to the
         mirror opposite of *refpoint*. Specify inset box attributes via
-        the ``box`` option [outline only].
+        the ``box`` parameter [Default is outline only].
     box : str or bool
         [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\
         *pen*]][**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\
-        [[*dx*/*dy*/][*shade*]]]
+        [[*dx*/*dy*/][*shade*]]].
 
         If passed ``True``, this draws a rectangular box around the map
         inset using the default pen; specify a different pen
@@ -78,11 +78,11 @@ def inset(self, **kwargs):
         Append **+i** to draw a secondary, inner border as well. We use a
         uniform *gap* between borders of 2\ **p** and the default pen
         unless other values are specified. Append **+r** to draw rounded
-        rectangular borders instead, with a 6\ **p** corner radius. You
+        rectangular borders instead, with a 6p corner radius. You
         can override this radius by appending another value. Append
         **+s** to draw an offset background shaded region. Here, *dx*/*dy*
         indicates the shift relative to the foreground frame
-        [4\ **p**/-4\ **p**] and *shade* sets the fill style to use for
+        [4p/-4p] and ``shade`` sets the fill style to use for
         shading [Default is gray50].
     margin : int or str or list
         This is clearance that is added around the inside of the inset.
@@ -95,7 +95,7 @@ def inset(self, **kwargs):
         slashes [Default is no margins].
     no_clip : bool
         Do NOT clip features extruding outside map inset boundaries [Default
-        will clip].
+        is clip].
     {V}
 
     Examples
diff --git a/pygmt/src/legend.py b/pygmt/src/legend.py
index cd3e9362f12..6e30b65a22b 100644
--- a/pygmt/src/legend.py
+++ b/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
@@ -44,22 +44,26 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
     Parameters
     ----------
     spec : None or str
-        Either None (default) for using the automatically generated legend
-        specification file, or a filename pointing to the legend
+        Either ``None`` [default] for using the automatically generated legend
+        specification file, or a *filename* pointing to the legend
         specification file.
     {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
-        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.
+        [**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**\ +\ **o**\ *0.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 arguments, draws a rectangular border around the legend
+        using :gmt-term:`MAP_FRAME_PEN`. By default, uses
+        **+g**\ white\ **+p**\ 1p which draws a box around the legend using a
+        1p black pen and adds a white background.
     {V}
     {XY}
     {c}
diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index af0d60c0754..1101fd0aacb 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -22,7 +22,7 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def logo(self, **kwargs):
-    """
+    r"""
     Plot the GMT logo.
 
     By default, the GMT logo is 2 inches wide and 1 inch high and
@@ -39,13 +39,14 @@ def logo(self, **kwargs):
     {J}
     {R}
     position : str
-        ``'[g|j|J|n|x]refpoint+wwidth[+jjustify][+odx[/dy]]'``.
+        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
+        **+w**\ *width*\ [**+j**\ *justify*]\ [**+o**\ *dx*\ [/*dy*]].
         Sets reference point on the map for the image.
     box : bool or str
-        Without further options, draws a rectangular border around the
+        Without further arguments, draws a rectangular border around the
         GMT logo.
     style : str
-        ``l|n|u``.
+        [**l**\|\ **n**\|\ **u**].
         Control what is written beneath the map portion of the logo.
 
         - **l** to plot the text label "The Generic Mapping Tools"
diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py
index 0ec3d0bc89a..cdceba2bcec 100644
--- a/pygmt/src/plot.py
+++ b/pygmt/src/plot.py
@@ -44,28 +44,28 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
 def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
-    """
+    r"""
     Plot lines, polygons, and symbols in 2-D.
 
     Takes a matrix, (x,y) 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* and *y*.
+    Must provide either ``data`` or ``x``/``y``.
 
-    If providing data through *x* and *y*, *color* can be a 1d array that
+    If providing data through ``x``/``y``, ``color`` can be a 1d array that
     will be mapped to a colormap.
 
     If a symbol is selected and no symbol size given, then plot will
     interpret the third column of the input data as symbol size. Symbols
     whose size is <= 0 are skipped. If no symbols are specified then the
-    symbol code (see *style* below) must be present as last column in the
-    input. If *style* is not used, a line connecting the data points will
-    be drawn instead. To explicitly close polygons, use *close*. Select a
-    fill with *color*. If *color* is set, *pen* will control whether the
-    polygon outline is drawn or not. If a symbol is selected, *color* and
-    *pen* determines the fill and outline/no outline, respectively.
+    symbol code (see ``style`` below) must be present as last column in the
+    input. If ``style`` is not used, a line connecting the data points will
+    be drawn instead. To explicitly close polygons, use ``close``. Select a
+    fill with ``color``. If ``color`` is set, ``pen`` will control whether the
+    polygon outline is drawn or not. If a symbol is selected, ``color`` and
+    ``pen`` determines the fill and outline/no outline, respectively.
 
-    Full option list at :gmt-docs:`plot.html`
+    Full parameter list at :gmt-docs:`plot.html`
 
     {aliases}
 
@@ -76,11 +76,11 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         data points
     data : str or 2d array
         Either a data file name or a 2d numpy array with the tabular data.
-        Use option *columns* (i) to choose which columns are x, y, color,
+        Use parameter ``columns`` to choose which columns are x, y, color,
         and size, respectively.
     sizes : 1d array
-        The sizes of the data points in units specified in *style* (S).
-        Only valid if using *x* and *y*.
+        The sizes of the data points in units specified using ``style``.
+        Only valid if using ``x``/``y``.
     direction : list of two 1d arrays
         If plotting vectors (using ``style='V'`` or ``style='v'``), then
         should be a list of two 1d arrays with the vector directions. These
@@ -89,9 +89,9 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
     {J}
     {R}
     straight_line : bool or str
-        ``[m|p|x|y]``.
+        [**m**\|\ **p**\|\ **x**\|\ **y**].
         By default, geographic line segments are drawn as great circle
-        arcs. To draw them as straight lines, use *straight_line*.
+        arcs. To draw them as straight lines, use ``straight_line``.
         Alternatively, add **m** to draw the line by first following a
         meridian, then a parallel. Or append **p** to start following a
         parallel, then a meridian. (This can be practical to draw a line
@@ -102,16 +102,18 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
     {B}
     {CPT}
     offset : str
-        ``dx/dy``.
+        *dx*/*dy*.
         Offset the plot symbol or line locations by the given amounts
         *dx/dy* [Default is no offset]. If *dy* is not given it is set
         equal to *dx*.
     error_bar : bool or str
-        ``[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen]``.
+        [**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*]\
+        [**+yl**\|\ **r**\|\ *y0*][**+p**\ *pen*].
         Draw symmetrical error bars. Full documentation is at
         :gmt-docs:`plot.html#e`.
     connection : str
-        ``[c|n|r][a|f|s|r|refpoint]``.
+        [**c**\|\ **n**\|\ **r**]\
+        [**a**\|\ **f**\|\ **s**\|\ **r**\|\ *refpoint*].
         Alter the way points are connected (by specifying a *scheme*) and
         data are grouped (by specifying a *method*). Append one of three
         line connection schemes:
@@ -138,8 +140,8 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
           after each record to the previous point (this method is only
           available with the ``connection='r'`` scheme).
 
-        Instead of the codes **a**|**f**|**s**|**r** you may append the
-        coordinates of a *refpoint* which will serve as a fixed external
+        Instead of the codes **a**\|\ **f**\|\ **s**\|\ **r** you may append
+        the coordinates of a *refpoint* which will serve as a fixed external
         reference point for all groups.
     {G}
     intensity : float or bool
@@ -148,14 +150,15 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         using ``intensity=True``, we will instead read *intens* from the
         first data column after the symbol parameters (if given).
     close : str
-        ``[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]``.
+        [**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*]\
+        [**+yl**\|\ **r**\|\ *y0*][**+p**\ *pen*].
         Force closed polygons. Full documentation is at
         :gmt-docs:`plot.html#l`.
     no_clip : bool or str
-        ``'[c|r]'``.
+        [**c**\|\ **r**].
         Do NOT clip symbols that fall outside map border [Default plots
         points whose coordinates are strictly inside the map border only].
-        The option does not apply to lines and polygons which are always
+        The parameter does not apply to lines and polygons which are always
         clipped to the map region. For periodic (360-longitude) maps we
         must plot all symbols twice in case they are clipped by the
         repeating boundary. ``no_clip=True`` will turn off clipping and not
@@ -171,14 +174,14 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
     {V}
     {XY}
     zvalue : str
-        ``value|file``.
+        *value*\|\ *file*.
         Instead of specifying a symbol or polygon fill and outline color
-        via **color** and **pen**, give both a *value* via **zvalue** and a
-        color lookup table via **cmap**.  Alternatively, give the name of a
+        via ``color`` and ``pen``, give both a *value* via ``zvalue`` and a
+        color lookup table via ``cmap``.  Alternatively, give the name of a
         *file* with one z-value (read from the last column) for each
         polygon in the input data. To apply it to the fill color, use
         ``color='+z'``. To apply it to the pen color, append **+z** to
-        **pen**.
+        ``pen``.
     {c}
     columns : str or 1d array
         Choose which columns are x, y, color, and size, respectively if
diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py
index 682cd7494a4..8c42b5eae7b 100644
--- a/pygmt/src/plot3d.py
+++ b/pygmt/src/plot3d.py
@@ -46,28 +46,28 @@
 def plot3d(
     self, x=None, y=None, z=None, data=None, sizes=None, direction=None, **kwargs
 ):
-    """
+    r"""
     Plot lines, polygons, and symbols in 3-D.
 
     Takes a matrix, (x,y,z) triplets, or a file name as input and plots
     lines, polygons, or symbols at those locations in 3-D.
 
-    Must provide either *data* or *x*, *y* and *z*.
+    Must provide either ``data`` or ``x``/``y``/``z``.
 
-    If providing data through *x*, *y* and *z*, *color* can be a 1d array
+    If providing data through ``x/y/z``, ``color`` can be a 1d array
     that will be mapped to a colormap.
 
     If a symbol is selected and no symbol size given, then plot3d will
     interpret the fourth column of the input data as symbol size. Symbols
     whose size is <= 0 are skipped. If no symbols are specified then the
-    symbol code (see *style* below) must be present as last column in the
-    input. If *style* is not used, a line connecting the data points will
-    be drawn instead. To explicitly close polygons, use *close*. Select a
-    fill with *color*. If *color* is set, *pen* will control whether the
-    polygon outline is drawn or not. If a symbol is selected, *color* and
-    *pen* determines the fill and outline/no outline, respectively.
+    symbol code (see ``style`` below) must be present as last column in the
+    input. If ``style`` is not used, a line connecting the data points will
+    be drawn instead. To explicitly close polygons, use ``close``. Select a
+    fill with ``color``. If ``color`` is set, ``pen`` will control whether the
+    polygon outline is drawn or not. If a symbol is selected, ``color`` and
+    ``pen`` determines the fill and outline/no outline, respectively.
 
-    Full option list at :gmt-docs:`plot3d.html`
+    Full parameter list at :gmt-docs:`plot3d.html`
 
     {aliases}
 
@@ -78,11 +78,11 @@ def plot3d(
         the data points
     data : str or 2d array
         Either a data file name or a 2d numpy array with the tabular data.
-        Use option *columns* (i) to choose which columns are x, y, z,
+        Use parameter ``columns`` to choose which columns are x, y, z,
         color, and size, respectively.
     sizes : 1d array
-        The sizes of the data points in units specified in *style* (S).
-        Only valid if using *x*, *y* and *z*.
+        The sizes of the data points in units specified in ``style``.
+        Only valid if using ``x``/``y``/``z``.
     direction : list of two 1d arrays
         If plotting vectors (using ``style='V'`` or ``style='v'``), then
         should be a list of two 1d arrays with the vector directions. These
@@ -93,38 +93,39 @@ def plot3d(
         Set z-axis scaling or z-axis size.
     {R}
     straight_line : bool or str
-        ``[m|p|x|y]``.
+        [**m**\|\ **p**\|\ **x**\|\ **y**].
         By default, geographic line segments are drawn as great circle
-        arcs. To draw them as straight lines, use *straight_line*.
+        arcs. To draw them as straight lines, use ``straight_line``.
         Alternatively, add **m** to draw the line by first following a
         meridian, then a parallel. Or append **p** to start following a
         parallel, then a meridian. (This can be practical to draw a line
         along parallels, for example). For Cartesian data, points are
         simply connected, unless you append **x** or **y** to draw
         stair-case curves that whose first move is along *x* or *y*,
-        respectively. **Note**: The **straight_line** option requires
+        respectively. **Note**: The ``straight_line`` parameter requires
         constant *z*-coordinates.
     {B}
     {CPT}
     offset : str
-        ``dx/dy[/dz]``.
+        *dx*/*dy*\ [/*dz*].
         Offset the plot symbol or line locations by the given amounts
-        *dx/dy*[*dz*] [Default is no offset].
+        *dx*/*dy*\ [/*dz*] [Default is no offset].
     {G}
     intensity : float or bool
         Provide an *intens* value (nominally in the -1 to +1 range) to
-        modulate the fill color by simulating illumination [None]. If
-        using ``intensity=True``, we will instead read *intens* from the
+        modulate the fill color by simulating illumination [Default is None].
+        If using ``intensity=True``, we will instead read *intens* from the
         first data column after the symbol parameters (if given).
     close : str
-        ``[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]``.
+        [**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*]\
+        [**+yl**\|\ **r**\|\ *y0*][**+p**\ *pen*].
         Force closed polygons. Full documentation is at
         :gmt-docs:`plot3d.html#l`.
     no_clip : bool or str
-        ``[c|r]``.
+        [**c**\|\ **r**].
         Do NOT clip symbols that fall outside map border [Default plots
         points whose coordinates are strictly inside the map border only].
-        The option does not apply to lines and polygons which are always
+        This parameter does not apply to lines and polygons which are always
         clipped to the map region. For periodic (360-longitude) maps we
         must plot all symbols twice in case they are clipped by the
         repeating boundary. ``no_clip=True`` will turn off clipping and not
@@ -143,14 +144,14 @@ def plot3d(
     {W}
     {XY}
     zvalue : str
-        ``value|file``.
+        *value*\|\ *file*.
         Instead of specifying a symbol or polygon fill and outline color
-        via **color** and **pen**, give both a *value* via **zvalue** and a
-        color lookup table via **cmap**.  Alternatively, give the name of a
+        via ``color`` and ``pen``, give both a *value* via **zvalue** and a
+        color lookup table via ``cmap``.  Alternatively, give the name of a
         *file* with one z-value (read from the last column) for each
         polygon in the input data. To apply it to the fill color, use
         ``color='+z'``. To apply it to the pen color, append **+z** to
-        **pen**.
+        ``pen``.
     {c}
     label : str
         Add a legend entry for the symbol or line being plotted.
diff --git a/pygmt/src/text.py b/pygmt/src/text.py
index 0fa0a9698a8..3ab49e61508 100644
--- a/pygmt/src/text.py
+++ b/pygmt/src/text.py
@@ -53,16 +53,16 @@ def text_(
     justify=None,
     **kwargs,
 ):
-    """
+    r"""
     Plot or typeset text strings of variable size, font type, and orientation.
 
     Must provide at least one of the following combinations as input:
 
-    - *textfiles*
-    - *x*, *y*, and *text*
-    - *position* and *text*
+    - ``textfiles``
+    - ``x``/``y``, and ``text``
+    - ``position`` and ``text``
 
-    Full option list at :gmt-docs:`text.html`
+    Full parameter list at :gmt-docs:`text.html`
 
     {aliases}
 
@@ -76,70 +76,70 @@ def text_(
         the text
     position : str
         Sets reference point on the map for the text by using x,y
-        coordinates extracted from *region* instead of providing them
-        through *x* and *y*. Specify with a two letter (order independent)
+        coordinates extracted from ``region`` instead of providing them
+        through ``x``/``y``. Specify with a two letter (order independent)
         code, chosen from:
 
-        * Horizontal: L(eft), C(entre), R(ight)
-        * Vertical: T(op), M(iddle), B(ottom)
+        * Horizontal: **L**\ (eft), **C**\ (entre), **R**\ (ight)
+        * Vertical: **T**\ (op), **M**\ (iddle), **B**\ (ottom)
 
-        For example, position="TL" plots the text at the Upper Left corner
+        For example, ``position="TL"`` plots the text at the Upper Left corner
         of the map.
     text : str or 1d array
         The text string, or an array of strings to plot on the figure
     angle: int, float, str or bool
         Set the angle measured in degrees counter-clockwise from
-        horizontal. E.g. 30 sets the text at 30 degrees. If no angle is
-        explicitly given (i.e. angle=True) then the input textfile(s) must
-        have this as a column.
+        horizontal (e.g. 30 sets the text at 30 degrees). If no angle is
+        explicitly given (i.e. ``angle=True``) then the input to ``textfiles``
+        must have this as a column.
     font : str or bool
-        Set the font specification with format "size,font,color" where size
-        is text size in points, font is the font to use, and color sets the
-        font color. E.g. "12p,Helvetica-Bold,red" selects a 12p red
-        Helvetica-Bold font. If no font info is explicitly given (i.e.
-        font=True), then the input textfile(s) must have this information
-        in one of its columns.
+        Set the font specification with format *size*\ ,\ *font*\ ,\ *color*
+        where *size* is text size in points, *font* is the font to use, and
+        *color* sets the font color. For example,
+        ``font="12p,Helvetica-Bold,red"`` selects a 12p, red, Helvetica-Bold
+        font. If no font info is explicitly given (i.e. ``font=True``), then
+        the input to ``textfiles`` must have this information in one of its
+        columns.
     justify : str or bool
         Set the alignment which refers to the part of the text string that
         will be mapped onto the (x,y) point. Choose a 2 character
-        combination of L, C, R (for left, center, or right) and T, M, B for
-        top, middle, or bottom. E.g., BL for lower left. If no
-        justification is explicitly given (i.e. justify=True), then the
-        input textfile(s) must have this as a column.
+        combination of **L**, **C**, **R** (for left, center, or right) and
+        **T**, **M**, **B** for top, middle, or bottom. E.g., **BL** for lower
+        left. If no justification is explicitly given (i.e. ``justify=True``),
+        then the input to ``textfiles`` must have this as a column.
     {J}
     {R}
     clearance : str
-        ``[dx/dy][+to|O|c|C]``
+        [*dx/dy*][**+to**\|\ **O**\|\ **c**\|\ **C**].
         Adjust the clearance between the text and the surrounding box
-        [15%]. Only used if *pen* or *fill* are specified. Append the unit
-        you want ('c' for cm, 'i' for inch, or 'p' for point; if not given
-        we consult 'PROJ_LENGTH_UNIT') or '%' for a percentage of the
-        font size. Optionally, use modifier '+t' to set the shape of the
-        textbox when using *fill* and/or *pen*. Append lower case 'o' to
-        get a straight rectangle [Default]. Append upper case 'O' to get a
-        rounded rectangle. In paragraph mode (*paragraph*) you can also
-        append lower case 'c' to get a concave rectangle or append upper
-        case 'C' to get a convex rectangle.
+        [Default is 15% of the font size]. Only used if ``pen`` or ``fill`` are
+        specified. Append the unit you want (*c* for cm, *i* for inch, or *p*
+        for point; if not given we consult **PROJ_LENGTH_UNIT**) or *%* for a
+        percentage of the font size. Optionally, use modifier **+t** to set
+        the shape of the textbox when using ``fill`` and/or ``pen``. Append
+        lower case **o** to get a straight rectangle [Default is **o**]. Append
+        upper case **O** to get a rounded rectangle. In paragraph mode
+        (*paragraph*) you can also append lower case **c** to get a concave
+        rectangle or append upper case **C** to get a convex rectangle.
     fill : str
         Sets the shade or color used for filling the text box [Default is
         no fill].
     offset : str
-        ``[j|J]dx[/dy][+v[pen]]``
-        Offsets the text from the projected (x,y) point by dx,dy [0/0]. If
-        dy is not specified then it is set equal to dx. Use offset='j' to
+        [**j**\|\ **J**]\ *dx*\[/*dy*][**+v**\[*pen*]].
+        Offsets the text from the projected (x,y) point by *dx*,\ *dy* [0/0].
+        If *dy* is not specified then it is set equal to *dx*. Use **j** to
         offset the text away from the point instead (i.e., the text
         justification will determine the direction of the shift). Using
-        offset='J' will shorten diagonal offsets at corners by sqrt(2).
-        Optionally, append '+v' which will draw a line from the original
+        **J** will shorten diagonal offsets at corners by sqrt(2).
+        Optionally, append **+v** which will draw a line from the original
         point to the shifted point; append a pen to change the attributes
         for this line.
     pen : str
         Sets the pen used to draw a rectangle around the text string
-        (see *clearance*) [Default is width = default, color = black,
+        (see ``clearance``) [Default is width = default, color = black,
         style = solid].
     no_clip : bool
-        Do NOT clip text at map boundaries [Default is False, i.e. will
-        clip].
+        Do NOT clip text at map boundaries [Default is will clip].
     {V}
     {XY}
     {c}