Figure.shift_origin: Improve docstrings, add inline examples and add type hints

pygmt/src/shift_origin.py

@@ -1,33 +1,57 @@
 """
 shift_origin - Shift plot origin in x and/or y directions.
 """
+from __future__ import annotations
 
 from pygmt.clib import Session
 
 
-def shift_origin(self, xshift=None, yshift=None):
-    """
+def shift_origin(
+    self, xshift: float | str | None = None, yshift: float | str | None = None
+) -> None:
+    r"""
     Shift plot origin in x and/or y directions.
 
-    This method shifts the plot origin relative to the current origin
-    by (*xshift*, *yshift*). Optionally, append the length unit (**c**,
-    **i**, or **p**). Default unit if not given is **c** for centimeters.
+    This method shifts the plot origin relative to the current origin by
+    *xshift* and *yshift* in x and y directions, respectively. Optionally,
+    append the length unit (**c** for centimeters, **i** for inches, or **p**
+    for points) to the shifts. Default unit if not explicitely given is **c**,
+    but can be changed to other units via :gmt-term:`PROJ_LENGTH_UNIT`.
+
+    For *xshift*, a special character **w** can also be used, which represents
+    the bounding box **width** of the previous plot. The full syntax is
+    [[±][*f*]\ **w**\ [/\ *d*\ ]±]\ *xoff*, where optional signs, factor *f*
+    and divisor *d* can be used to compute an offset that may be adjusted
+    further by ±*off*. For example, assuming that the previous plot has a width
+    of 10 centimeter, here are some example values for *xshift*:
 
-    Prepend **a** to shift the origin back to the original position after
-    plotting, prepend **c** to center the plot on the center of the paper
-    (optionally add shift), prepend **f** to shift the origin relative to
-    the fixed lower left corner of the page, or prepend **r** [Default] to
-    move the origin relative to its current location.
+    - ``w``: x-shift is 10 cm
+    - ``w+2c``: x-shift is 10+2=12 cm
+    - ``2w+3c``: x-shift is 2*10+3=23 cm
+    - ``w/2-2c``: x-shift is 10/2-2=3 cm
 
-    Detailed usage at
-    :gmt-docs:`cookbook/options.html#plot-positioning-and-layout-the-x-y-options`
+    Similarly, for *yshift*, a special character **h** can also be used, which
+    is the bounding box **height** of the previous plot.
 
     Parameters
     ----------
-    xshift : str
+    xshift
         Shift plot origin in x direction.
-    yshift : str
+    yshift
         Shift plot origin in y direction.
+
+    Examples
+    --------
+    >>> import pygmt
+    >>> fig = pygmt.Figure()
+    >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True)
+    >>> # shift the plot origin in x-direction by 12 cm
+    >>> fig.shift_origin(xshift=12)
+    >>> fig.basemap(region=[0, 10, 0, 10], projection="X14c/10c", frame=True)
+    >>> # shift the plot origin in x-direction based on the previous plot width
+    >>> # here, the width is 14 cm, and the xshift is 16 cm
+    >>> fig.shift_origin(xshift="w+2c")
+    >>> fig.show()
     """
     self._preprocess()
     args = ["-T"]