Figure.basemap: Migrate the box parameter to the new alias system and improve docstrings (#4369)

Author: seisman

pygmt/src/basemap.py

@@ -11,7 +11,7 @@
 
 
 @fmt_docstring
-@use_alias(F="box", f="coltypes")
+@use_alias(f="coltypes")
 def basemap(  # noqa: PLR0913
     self,
     projection: str | None = None,
@@ -22,29 +22,35 @@ def basemap(  # noqa: PLR0913
     map_scale: str | None = None,
     compass: str | None = None,
     rose: str | None = None,
+    box: str | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
     perspective: float | Sequence[float] | str | bool = False,
     **kwargs,
 ):
-    r"""
+    """
     Plot base maps and frames.
 
     Creates a basic or fancy basemap with axes, fill, and titles. Several map
-    projections are available, and the user may specify separate tick-mark intervals for
-    boundary annotation, ticking, and [optionally] gridlines.
+    projections are available, and separate tick-mark intervals for axis annotation,
+    ticking, and gridlines can be specified.
+
+    If not in subplot mode (see :meth:`pygmt.Figure.subplot`), at least one of the
+    parameters ``frame``, ``map_scale``, ``rose``, or ``compass`` must be specified.
+
+    .. note::
 
-    At least one of the parameters ``frame``, ``map_scale``, ``rose``, or ``compass``
-    must be specified if not in subplot mode.
+        Parameters ``map_scale``, ``rose``, ``compass``, and ``box`` are deprecated in
+        favor of the dedicated higher-level methods:
 
-    See also the following methods that provide higher-level interfaces to the GMT's
-    ``basemap`` module:
+        - :meth:`pygmt.Figure.scalebar`: Add a scale bar on the plot.
+        - :meth:`pygmt.Figure.directional_rose`: Add a directional rose on the plot.
+        - :meth:`pygmt.Figure.magnetic_rose`: Add a magnetic rose on the plot.
 
-    - :meth:`pygmt.Figure.scalebar`: Add a scale bar on the plot.
-    - :meth:``pygmt.Figure.directional_rose`: Add a directional rose on the plot.
-    - :meth:`pygmt.Figure.magnetic_rose`: Add a magnetic rose on the plot.
+        These methods provide more comprehensive and flexible APIs for their respective
+        plot elements.
 
     Full GMT docs at :gmt-docs:`basemap.html`.
 
@@ -64,7 +70,8 @@ def basemap(  # noqa: PLR0913
     Parameters
     ----------
     $projection
-    zscale/zsize
+    zscale
+    zsize
         Set z-axis scaling or z-axis size.
     $region
         *Required if this is the first plot command.*
@@ -74,46 +81,34 @@ def basemap(  # noqa: PLR0913
 
         .. deprecated:: v0.19.0
 
-            This parameter is deprecated. Use :meth:`pygmt.Figure.scalebar` instead,
-            which provides a more comprehensive and flexible API for adding scale bars
-            to plots. This parameter still accepts raw GMT CLI strings for the ``-L``
-            option of the ``basemap`` module for backward compatibility.
+            Use :meth:`pygmt.Figure.scalebar` instead. This parameter is maintained
+            for backward compatibility and accepts raw GMT CLI strings for the ``-L``
+            option.
     compass
         Draw a map magnetic rose on the map.
 
         .. deprecated:: v0.19.0
 
-            This parameter is deprecated. Use :meth:`pygmt.Figure.magnetic_rose`
-            instead, which provides a more comprehensive and flexible API for adding
-            magnetic roses to plots. This parameter still accepts raw GMT CLI strings
-            for the ``-Tm`` option of the ``basemap`` module for backward compatibility.
+            Use :meth:`pygmt.Figure.magnetic_rose` instead. This parameter is maintained
+            for backward compatibility and accepts raw GMT CLI strings for the ``-Tm``
+            option.
     rose
         Draw a map directional rose on the map.
 
         .. deprecated:: v0.19.0
 
-            This parameter is deprecated. Use :meth:`pygmt.Figure.directional_rose`
-            instead, which provides a more comprehensive and flexible API for adding
-            directional roses. This parameter still accepts raw GMT CLI strings for the
-            ``-Td`` option of the ``basemap`` module for backward compatibility.
-    box : bool or str
-        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
-        [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
-        If set to ``True``, draw a rectangular border around the
-        map scale or rose. 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 x and y, 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 2 points and the
-        :gmt-term:`MAP_DEFAULTS_PEN` unless other values are specified. Append
-        **+r** to draw rounded rectangular borders instead, with a 6-points
-        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
-        [Default is ``"4p/-4p"``] and shade sets the fill style to use for
-        shading [Default is ``"gray50"``].
+            Use :meth:`pygmt.Figure.directional_rose` instead. This parameter is
+            maintained for backward compatibility and accepts raw GMT CLI strings for
+            the ``-Td`` option.
+    box
+        Draw a background box behind the scalebar, directional rose, or magnetic rose.
+
+        .. deprecated:: v0.19.0
+
+            Use the ``box`` parameter in :meth:`pygmt.Figure.scalebar`,
+            :meth:`pygmt.Figure.directional_rose`, or :meth:`pygmt.Figure.magnetic_rose`
+            instead. This parameter is maintained for backward compatibility and accepts
+            raw GMT CLI strings for the ``-F`` option.
     $verbose
     $panel
     $coltypes
@@ -123,6 +118,7 @@ def basemap(  # noqa: PLR0913
     self._activate_figure()
 
     aliasdict = AliasSystem(
+        F=Alias(box, name="box"),  # Deprecated.
         Jz=Alias(zscale, name="zscale"),
         JZ=Alias(zsize, name="zsize"),
         L=Alias(map_scale, name="map_scale"),  # Deprecated.

pygmt/src/coast.py

@@ -138,10 +138,9 @@ def coast(  # noqa: PLR0913
 
         .. deprecated:: v0.19.0
 
-            This parameter is deprecated. Use :meth:`pygmt.Figure.scalebar` instead,
-            which provides a more comprehensive and flexible API for adding scale bars
-            to plots. This parameter still accepts raw GMT CLI strings for the ``-L``
-            option of the ``coast`` module for backward compatibility.
+            Use :meth:`pygmt.Figure.scalebar` instead. This parameter is maintained
+            for backward compatibility and accepts raw GMT CLI strings for the ``-L``
+            option.
     box
         Draw a background box behind the map scale or rose. If set to ``True``, a simple
         rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box