Complete documentation for plot (#666)

All major arguments for `plot` are now aliased and documented
as per upstream GMT docs at https://docs.generic-mapping-tools.org/6.1/plot.html

* Alias straight_line(A), error_bar(E), close(L), offset(D) for plot
* Alias connection (F), intensity (I) and zvalue (Z) for plot
* Change some args to italics instead of bold, and use singular aliases

Co-Authored-By: Dongdong Tian <[email protected]>

pygmt/base_plotting.py

@@ -606,47 +606,52 @@ def grdview(self, grid, **kwargs):
 
     @fmt_docstring
     @use_alias(
-        R="region",
-        J="projection",
+        A="straight_line",
         B="frame",
-        S="style",
+        C="cmap",
+        D="offset",
+        E="error_bar",
+        F="connection",
         G="color",
+        I="intensity",
+        J="projection",
+        L="close",
         N="no_clip",
-        W="pen",
-        i="columns",
-        l="label",
-        C="cmap",
+        R="region",
+        S="style",
         U="timestamp",
         V="verbose",
+        W="pen",
         X="xshift",
         Y="yshift",
+        Z="zvalue",
+        i="columns",
+        l="label",
         p="perspective",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
     def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         """
-        Plot lines, polygons, and symbols on maps.
-
-        Used to be psxy.
+        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*.
 
-        If providing data through *x* and *y*, *color* (G) can be a 1d array
-        that will be mapped to a colormap.
+        If providing data through *x* and *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 psxy will
+        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 *S* below) must be present as last column in the
-        input. If *S* is not used, a line connecting the data points will be
-        drawn instead. To explicitly close polygons, use *L*. Select a fill
-        with *G*. If *G* is set, *W* will control whether the polygon outline
-        is drawn or not. If a symbol is selected, *G* and *W* 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`
 
@@ -671,19 +676,69 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
             depending on the style options chosen.
         {J}
         {R}
-        A : bool or str
-            ``'[m|p|x|y]'``
+        straight_line : bool or str
+            ``[m|p|x|y]``.
             By default, geographic line segments are drawn as great circle
-            arcs. To draw them as straight lines, use *A*.
+            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.
         {B}
         {CPT}
-        D : str
-            ``'dx/dy'``: Offset the plot symbol or line locations by the given
-            amounts dx/dy.
-        E : bool or str
-            ``'[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen]'``.
-            Draw symmetrical error bars.
+        offset : str
+            ``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]``.
+            Draw symmetrical error bars. Full documentation is at
+            :gmt-docs:`plot.html#e`.
+        connection : str
+            ``[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:
+
+            - **c** : Draw continuous line segments for each group [Default].
+            - **r** : Draw line segments from a reference point reset for each
+              group.
+            - **n** : Draw networks of line segments between all points in
+              each group.
+
+            Optionally, append the one of four segmentation methods to define
+            the group:
+
+            - **a** : Ignore all segment headers, i.e., let all points belong
+              to a single group, and set group reference point to the very
+              first point of the first file.
+            - **f** : Consider all data in each file to be a single separate
+              group and reset the group reference point to the first point of
+              each group.
+            - **s** : Segment headers are honored so each segment is a group;
+              the group reference point is reset to the first point of each
+              incoming segment [Default].
+            - **r** : Same as **s**, but the group reference point is reset
+              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
+            reference point for all groups.
         {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
+            first data column after the symbol parameters (if given).
+        close : str
+            ``[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]``.
+            Force closed polygons. Full documentation is at
+            :gmt-docs:`plot.html#l`.
         no_clip : bool or str
             ``'[c|r]'``.
             Do NOT clip symbols that fall outside map border [Default plots
@@ -703,6 +758,15 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         {U}
         {V}
         {XY}
+        zvalue : str
+            ``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
+            *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**.
         label : str
             Add a legend entry for the symbol or line being plotted.