Complete most of documentation for makecpt (#676)

Starting to properly document most major arguments for `makecpt`
as per upstream GMT docs at
https://docs.generic-mapping-tools.org/6.1/makecpt.html.
Refreshed current aliases series (T), truncate (G), reverse (I) and continuous (Z).

* Add sphinx extlink 'gmt-term' for linking to gmt.conf parameters
* Complete long description of makecpt
* Alias transparency (A), color_model (F) and log (Q) for makecpt
* Alias categorical (W) for makecpt
* Alias background (D), overrule_bg (M) and no_bg (N)
* Alias cyclic (Ww) and ensure this cannot be used with categorical (W)

doc/conf.py

@@ -37,10 +37,8 @@
 
 # configure links to GMT docs
 extlinks = {
-    "gmt-docs": (
-        "https://docs.generic-mapping-tools.org/latest/%s",
-        "https://docs.generic-mapping-tools.org/latest/",
-    )
+    "gmt-docs": ("https://docs.generic-mapping-tools.org/latest/%s", None),
+    "gmt-term": ("https://docs.generic-mapping-tools.org/latest/gmt.conf#term-%s", ""),
 }
 
 # intersphinx configuration

pygmt/mathops.py

@@ -8,40 +8,105 @@
 
 @fmt_docstring
 @use_alias(
+    A="transparency",
     C="cmap",
-    T="series",
+    D="background",
+    F="color_model",
     G="truncate",
     H="output",
     I="reverse",
+    M="overrule_bg",
+    N="no_bg",
+    Q="log",
+    T="series",
     V="verbose",
+    W="categorical",
+    Ww="cyclic",
     Z="continuous",
 )
 @kwargs_to_strings(T="sequence", G="sequence")
 def makecpt(**kwargs):
     """
-    Creates a static color palette table (CPT).
+    Make GMT color palette tables.
+
+    This is a module that will help you make static color palette tables
+    (CPTs). By default, the CPT will simply be saved to the current session,
+    but you can use *output* to save it to a file. You define an equidistant
+    set of contour intervals or pass your own z-table or list, and create a new
+    CPT based on an existing master (dynamic) CPT. The resulting CPT can be
+    reversed relative to the master cpt, and can be made continuous or
+    discrete. For color tables beyond the standard GMT offerings, visit
+    `cpt-city <http://soliton.vm.bytemark.co.uk/pub/cpt-city/>`_ and
+    `Scientific Colour-Maps <http://www.fabiocrameri.ch/colourmaps.php>`_.
+
+    The CPT includes three additional colors beyond the range of z-values.
+    These are the background color (B) assigned to values lower than the lowest
+    *z*-value, the foreground color (F) assigned to values higher than the
+    highest *z*-value, and the NaN color (N) painted wherever values are
+    undefined.
+
+    If the master CPT includes B, F, and N entries, these will be copied into
+    the new master file. If not, the parameters :gmt-term:`COLOR_BACKGROUND`,
+    :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` from the
+    :gmt-docs:`gmt.conf <gmt.conf>` file or the command line will be used. This
+    default behavior can be overruled using the options *background*,
+    *overrule_bg* or *no_bg*.
+
+    The color model (RGB, HSV or CMYK) of the palette created by **makecpt**
+    will be the same as specified in the header of the master CPT. When there
+    is no :gmt-term:`COLOR_MODEL` entry in the master CPT, the
+    :gmt-term:`COLOR_MODEL` specified in the :gmt-docs:`gmt.conf <gmt.conf>`
+    file or on the command line will be used.
 
     Full option list at :gmt-docs:`makecpt.html`
 
     {aliases}
 
     Parameters
     ----------
+    transparency : str
+        Sets a constant level of transparency (0-100) for all color slices.
+        Append **+a** to also affect the fore-, back-, and nan-colors
+        [Default is no transparency, i.e., 0 (opaque)].
     cmap : str
         Selects the master color palette table (CPT) to use in the
         interpolation. Full list of built-in color palette tables can be found
         at :gmt-docs:`cookbook/cpts.html#built-in-color-palette-tables-cpt`.
+    background : bool or str
+        Select the back- and foreground colors to match the colors for lowest
+        and highest *z*-values in the output CPT [Default (``background=True``
+        or ``background='o'``) uses the colors specified in the master file, or
+        those defined by the parameters :gmt-term:`COLOR_BACKGROUND`,
+        :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN`]. Use
+        ``background='i'`` to match the colors for the lowest and highest
+        values in the input (instead of the output) CPT.
+    color_model :
+        ``[R|r|h|c][+c[label]]``.
+        Force output CPT to be written with r/g/b codes, gray-scale values or
+        color name (**R**, default) or r/g/b codes only (**r**), or h-s-v codes
+        (**h**), or c/m/y/k codes (**c**).  Optionally or alternatively, append
+        **+c** to write discrete palettes in categorical format. If *label* is
+        appended then we create labels for each category to be used when the
+        CPT is plotted. The *label* may be a comma-separated list of category
+        names (you can skip a category by not giving a name), or give
+        *start*[-], where we automatically build monotonically increasing
+        labels from *start* (a single letter or an integer). Append - to build
+        ranges *start*-*start+1* instead.
     series : list or str
-        ``[min/max/inc[+b|l|n]|file|list]``. Defines the range of the new CPT
-        by giving the lowest and highest z-value (and optionally an interval).
-        If this is not given, the existing range in the master CPT will be used
-        intact.
+        ``[min/max/inc[+b|l|n]|file|list]``.
+        Defines the range of the new CPT by giving the lowest and highest
+        z-value (and optionally an interval). If this is not given, the
+        existing range in the master CPT will be used intact. The values
+        produced defines the color slice boundaries.  If **+n** is used it
+        refers to the number of such boundaries and not the number of slices.
+        For details on array creation, see
+        :gmt-docs:`makecpt.html#generate-1d-array`.
     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 any
-        resampling. See also
-        :gmt-docs:`cookbook/features.html#manipulating-cpts`.
+        ``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 any resampling. See
+        also :gmt-docs:`cookbook/features.html#manipulating-cpts`.
     output : str
         Optional. The file name with extension .cpt to store the generated CPT
         file. If not given or False (default), saves the CPT as the session
@@ -51,19 +116,38 @@ def makecpt(**kwargs):
         progression in the master CPT. Set this to z to reverse the sign of
         z-values in the color table. Note that this change of z-direction
         happens before *truncate* and *series* values are used so the latter
-        must be compatible with the changed z-range. See also
+        must be compatible with the changed *z*-range. See also
         :gmt-docs:`cookbook/features.html#manipulating-cpts`.
+    overrule_bg :
+        Overrule background, foreground, and NaN colors specified in the master
+        CPT with the values of the parameters :gmt-term:`COLOR_BACKGROUND`,
+        :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` specified in
+        the :gmt-docs:`gmt.conf <gmt.conf>` file or on the command line. When
+        combined with **background**, only :gmt-term:`COLOR_NAN` is considered.
+    no_bg : bool
+        Do not write out the background, foreground, and NaN-color fields
+        [Default will write them, i.e. ``no_bg=False``].
+    log : bool
+        For logarithmic interpolation scheme with input given as logarithms.
+        Expects input z-values provided via **series** to be log10(*z*),
+        assigns colors, and writes out *z*.
     continuous : bool
-        Creates a continuous CPT [Default is discontinuous, i.e., constant
-        colors for each interval]. This option has no effect when no *series*
-        is used, or when using *series=[z_min, z_max]*; in the first case the
-        input CPT remains untouched, in the second case it is only scaled to
-        match the range z_min/z_max.
-
+        Force a continuous CPT when building from a list of colors and a list
+        of z-values [Default is None, i.e. discrete values].
     {V}
-
+    categorical : bool
+        Do not interpolate the input color table but pick the output colors
+        starting at the beginning of the color table, until colors for all
+        intervals are assigned. This is particularly useful in combination with
+        a categorical color table, like ``cmap='categorical'``.
+    cyclic : bool
+        Produce a wrapped (cyclic) color table that endlessly repeats its
+        range. Note that ``cyclic=True`` cannot be set together with
+        ``categorical=True``.
     """
     with Session() as lib:
+        if "W" in kwargs and "Ww" in kwargs:
+            raise GMTInvalidInput("Set only categorical or cyclic to True, not both.")
         if "H" not in kwargs.keys():  # if no output is set
             arg_str = build_arg_string(kwargs)
         elif "H" in kwargs.keys():  # if output is set

pygmt/tests/test_makecpt.py

@@ -182,3 +182,41 @@ def test_makecpt_continuous(grid):
     makecpt(cmap="blue,white", continuous=True, series="-4500,4500")
     fig.grdimage(grid, projection="W0/6i")
     return fig
+
+
+@check_figures_equal()
+def test_makecpt_categorical(region):
+    """
+    Use static color palette table that is categorical.
+    """
+    fig_ref = Figure()
+    makecpt(C="categorical", W="")
+    fig_ref.colorbar(cmap=True, region=region, frame=True, position="JBC")
+
+    fig_test = Figure()
+    makecpt(cmap="categorical", categorical=True)
+    fig_test.colorbar(cmap=True, region=region, frame=True, position="JBC")
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_makecpt_cyclic(region):
+    """
+    Use static color palette table that is cyclic.
+    """
+    fig_ref = Figure()
+    makecpt(C="cork", W="w")
+    fig_ref.colorbar(cmap=True, region=region, frame=True, position="JBC")
+
+    fig_test = Figure()
+    makecpt(cmap="cork", cyclic=True)
+    fig_test.colorbar(cmap=True, region=region, frame=True, position="JBC")
+    return fig_ref, fig_test
+
+
+def test_makecpt_categorical_and_cyclic():
+    """
+    Use incorrect setting by setting both categorical and cyclic to True.
+    """
+    with pytest.raises(GMTInvalidInput):
+        makecpt(cmap="batlow", categorical=True, cyclic=True)