Figure.plot3d: Deprecate parameter "color" to "fill" (remove in v0.12.0) (#2178)

Author: seisman

pygmt/src/plot3d.py

@@ -6,6 +6,7 @@
 from pygmt.helpers import (
     build_arg_string,
     data_kind,
+    deprecate_parameter,
     fmt_docstring,
     is_nonstr_iter,
     kwargs_to_strings,
@@ -15,12 +16,13 @@
 
 
 @fmt_docstring
+@deprecate_parameter("color", "fill", "v0.8.0", "v0.12.0")
 @use_alias(
     A="straight_line",
     B="frame",
     C="cmap",
     D="offset",
-    G="color",
+    G="fill",
     I="intensity",
     J="projection",
     Jz="zscale",
@@ -61,7 +63,7 @@ def plot3d(
 
     Must provide either ``data`` or ``x``/``y``/``z``.
 
-    If providing data through ``x/y/z``, ``color`` can be a 1d array
+    If providing data through ``x/y/z``, ``fill`` 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
@@ -70,8 +72,8 @@ def plot3d(
     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
+    fill with ``fill``. If ``fill`` is set, ``pen`` will control whether the
+    polygon outline is drawn or not. If a symbol is selected, ``fill`` and
     ``pen`` determines the fill and outline/no outline, respectively.
 
     Full option list at :gmt-docs:`plot3d.html`
@@ -83,7 +85,7 @@ def plot3d(
     data : str or {table-like}
         Either a data file name, a 2d {table-classes}.
         Optionally, use parameter ``incols`` to specify which columns are x, y,
-        z, color, and size, respectively.
+        z, fill, and size, respectively.
     x/y/z : float or 1d arrays
         The x, y, and z coordinates, or arrays of x, y and z coordinates of
         the data points
@@ -117,8 +119,8 @@ def plot3d(
         *dx*/*dy*\ [/*dz*].
         Offset the plot symbol or line locations by the given amounts
         *dx*/*dy*\ [/*dz*] [Default is no offset].
-    {color}
-        *color* can be a 1d array, but it is only valid if using ``x``/``y``
+    {fill}
+        *fill* can be a 1d array, but it is only valid if using ``x``/``y``
         and ``cmap=True`` is also required.
     intensity : float or bool or 1d array
         Provide an *intensity* value (nominally in the -1 to +1 range) to
@@ -158,11 +160,11 @@ def plot3d(
     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
+        via ``fill`` 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
+        ``fill="+z"``. To apply it to the pen color, append **+z** to
         ``pen``.
     {aspatial}
     {binary}
@@ -208,7 +210,7 @@ def plot3d(
     if kwargs.get("G") is not None and is_nonstr_iter(kwargs["G"]):
         if kind != "vectors":
             raise GMTInvalidInput(
-                "Can't use arrays for color if data is matrix or file."
+                "Can't use arrays for fill if data is matrix or file."
             )
         extra_arrays.append(kwargs["G"])
         del kwargs["G"]