Figure.subplot: Add an inline example

pygmt/src/subplot.py

@@ -21,6 +21,8 @@
 from pygmt.params import Axis, Box, Frame, Position
 from pygmt.src._common import _parse_position
 
+__doctest_skip__ = ["subplot"]
+
 
 def _alias_option_A(  # ruff: ignore[invalid-function-name]
     tag: str | bool = False,
@@ -297,6 +299,42 @@ def subplot(
     $region
     $frame
     $verbose
+
+    Examples
+    --------
+    Create a figure with two subplots in one row, showing regional maps of Japan and New
+    Zealand in the Mercator projection. The subplots are tagged as "a)" and "b)" at the
+    Top Left corner outside each map frame. The ``"?"`` in ``projection`` means the
+    width of each map is automatically determined from the subplot dimensions:
+
+    >>> import pygmt
+    >>> from pygmt.params import Position
+    >>> fig = pygmt.Figure()
+    >>> with fig.subplot(
+    ...     nrows=1,
+    ...     ncols=2,
+    ...     figsize=("15c", "6c"),
+    ...     tag=True,
+    ...     tag_position=Position("TL", cstype="outside"),
+    ...     margins="0.5c",
+    ... ):
+    ...     fig.coast(
+    ...         region=[128, 146, 30, 46],
+    ...         projection="M?",
+    ...         land="gray",
+    ...         water="lightblue",
+    ...         frame=True,
+    ...         panel=0,
+    ...     )
+    ...     fig.coast(
+    ...         region=[165, 180, -48, -34],
+    ...         projection="M?",
+    ...         land="gray",
+    ...         water="lightblue",
+    ...         frame=True,
+    ...         panel=1,
+    ...     )
+    >>> fig.show()
     """
     if nrows < 1 or ncols < 1:
         _value = f"{nrows=}, {ncols=}"