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.