inset: Add aliases for R and J and fix two examples (#1931)

Co-authored-by: Michael Grund <[email protected]>

examples/gallery/embellishments/inset_rectangle_region.py

@@ -24,18 +24,22 @@
 # figure
 fig.coast(land="lightbrown", water="azure1", shorelines="2p", area_thresh=1000)
 
-# Create an inset map, setting the position to bottom right, the width to
-# 3 cm, the height to 3.6 cm, and the x- and y-offsets to
-# 0.1 cm, respectively. Draws a rectangular box around the inset with a fill
-# color of "white" and a pen of "1p".
-with fig.inset(position="jBR+w3c/3.6c+o0.1c", box="+gwhite+p1p"):
-    # Plot the Japan main land in the inset using coast. "U54S/?" means UTM
-    # projection with map width automatically determined from the inset width.
+# Create an inset map, setting the position to bottom right, and the x- and
+# y-offsets to 0.1 cm, respectively.
+# The inset map contains the Japan main land. "U54S/3c" means UTM projection
+# with a map width of 3 cm. The inset width and height are automatically
+# calculated from the specified ``region`` and ``projection`` parameters.
+# Draws a rectangular box around the inset with a fill color of "white" and
+# a pen of "1p".
+with fig.inset(
+    position="jBR+o0.1c",
+    box="+gwhite+p1p",
+    region=[129, 146, 30, 46],
+    projection="U54S/3c",
+):
     # Highlight the Japan area in "lightbrown"
     # and draw its outline with a pen of "0.2p".
     fig.coast(
-        region=[129, 146, 30, 46],
-        projection="U54S/?",
         dcw="JP+glightbrown+p0.2p",
         area_thresh=10000,
     )

examples/tutorials/advanced/insets.py

@@ -97,11 +97,16 @@
     frame="a",
 )
 # This does not include an inset fill as it is covered by the inset figure
-with fig.inset(position="jBL+w3c+o0.5c/0.2c", box="+pblack"):
-    # Use a plotting function to create a figure inside the inset
+# Inset width/height are determined by the ``region`` and ``projection``
+# parameters.
+with fig.inset(
+    position="jBL+o0.5c/0.2c",
+    box="+pblack",
+    region=[-80, -65, 35, 50],
+    projection="M3c",
+):
+    # Use a plotting function to create a figure inside the inset.
     fig.coast(
-        region=[-80, -65, 35, 50],
-        projection="M3c",
         land="gray",
         borders=[1, 2],
         shorelines="1/thin",

pygmt/src/inset.py

@@ -11,8 +11,16 @@
 
 @fmt_docstring
 @contextlib.contextmanager
-@use_alias(D="position", F="box", M="margin", N="no_clip", V="verbose")
-@kwargs_to_strings(D="sequence", M="sequence")
+@use_alias(
+    D="position",
+    F="box",
+    J="projection",
+    M="margin",
+    N="no_clip",
+    R="region",
+    V="verbose",
+)
+@kwargs_to_strings(D="sequence", M="sequence", R="sequence")
 def inset(self, **kwargs):
     r"""
     Create an inset figure to be placed within a larger figure.
@@ -39,7 +47,7 @@ def inset(self, **kwargs):
 
         Append **g**\ *lon*/*lat* for map (user) coordinates,
         **j**\ *code* or **J**\ *code* for setting the *refpoint* via a
-        2-char justification code \ that refers to the (invisible)
+        2-char justification code that refers to the (invisible)
         projected map bounding box, **n**\ *xn*/*yn* for normalized (0-1)
         bounding box coordinates, or **x**\ *x*/*y* for plot
         coordinates (inches, cm, points, append unit).
@@ -98,6 +106,8 @@ def inset(self, **kwargs):
     no_clip : bool
         Do NOT clip features extruding outside map inset boundaries [Default
         is clip].
+    {R}
+    {J}
     {V}
 
     Examples