From fb64cbf18f6f8cf870c9cd8a0892b3874e3b1664 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 26 Jul 2025 15:14:02 +0800
Subject: [PATCH 01/25] Figure.logo: Refactor using the AliasSystem class

---
 pygmt/src/logo.py        | 48 +++++++++++++++++++++++++++++++++++++---
 pygmt/tests/test_logo.py |  8 ++++++-
 2 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index d65bf3bc775..b302d806883 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -2,7 +2,11 @@
 logo - Plot the GMT logo.
 """
 
+from typing import Literal
+
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
+from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
 
 
@@ -10,7 +14,6 @@
 @use_alias(
     R="region",
     J="projection",
-    D="position",
     F="box",
     S="style",
     V="verbose",
@@ -18,7 +21,18 @@
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def logo(self, **kwargs):
+def logo(
+    self,
+    position_type: Literal[
+        "user", "justify", "mirror", "normalize", "plot", None
+    ] = None,
+    position=None,
+    height=None,
+    width=None,
+    justify=None,
+    offset=None,
+    **kwargs,
+):
     r"""
     Plot the GMT logo.
 
@@ -39,6 +53,9 @@ def logo(self, **kwargs):
         [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
         **+w**\ *width*\ [**+j**\ *justify*]\ [**+o**\ *dx*\ [/*dy*]].
         Set reference point on the map for the image.
+    positon_type
+    width/height
+        Width or height of the GMT logo.
     box : bool or str
         If set to ``True``, draw a rectangular border around the
         GMT logo.
@@ -55,5 +72,30 @@ def logo(self, **kwargs):
     {transparency}
     """
     self._activate_figure()
+    if width is not None and height is not None:
+        msg = "Cannot specify both width and height."
+        raise GMTInvalidInput(msg)
+
+    aliasdict = AliasSystem(
+        D=[
+            Alias(
+                position_type,
+                name="position_type",
+                mapping={
+                    "user": "g",
+                    "justify": "j",
+                    "mirror": "J",
+                    "normalize": "n",
+                    "plot": "x",
+                },
+            ),
+            Alias(position, name="position", separator="/"),
+            Alias(height, name="height", prefix="+h"),
+            Alias(width, name="width", prefix="+w"),
+            Alias(justify, name="justify", prefix="+j"),
+            Alias(offset, name="offset", prefix="+o", separator="/", size=2),
+        ]
+    ).merge(kwargs)
+
     with Session() as lib:
-        lib.call_module(module="logo", args=build_arg_list(kwargs))
+        lib.call_module(module="logo", args=build_arg_list(aliasdict))
diff --git a/pygmt/tests/test_logo.py b/pygmt/tests/test_logo.py
index 62bddf4eb24..bcd803d8252 100644
--- a/pygmt/tests/test_logo.py
+++ b/pygmt/tests/test_logo.py
@@ -24,5 +24,11 @@ def test_logo_on_a_map():
     """
     fig = Figure()
     fig.basemap(region=[-90, -70, 0, 20], projection="M15c", frame=True)
-    fig.logo(position="jTR+o0.25c/0.25c+w7.5c", box=True)
+    fig.logo(
+        position_type="justify",
+        position="TR",
+        offset=(0.25, 0.25),
+        width="7.5c",
+        box=True,
+    )
     return fig

From 1eb6587657ffc55ed33b48c0a677a91e3165819c Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sun, 10 Aug 2025 20:12:00 +0800
Subject: [PATCH 02/25] Update position_type

---
 pygmt/src/logo.py | 44 ++++++++++++++++++++++++++++----------------
 1 file changed, 28 insertions(+), 16 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index b302d806883..f02cf44b8bc 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -2,8 +2,10 @@
 logo - Plot the GMT logo.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
+from pygmt._typing import AnchorCode
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
@@ -23,14 +25,14 @@
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def logo(
     self,
+    position: Sequence[str | float] | AnchorCode,
     position_type: Literal[
-        "user", "justify", "mirror", "normalize", "plot", None
-    ] = None,
-    position=None,
+        "mapcoords", "inside", "outside", "boxcoords", "plotcoords"
+    ] = "mapcoords",
     height=None,
     width=None,
     justify=None,
-    offset=None,
+    anchor_offset=None,
     **kwargs,
 ):
     r"""
@@ -49,11 +51,21 @@ def logo(
     ----------
     {projection}
     {region}
-    position : str
-        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
-        **+w**\ *width*\ [**+j**\ *justify*]\ [**+o**\ *dx*\ [/*dy*]].
-        Set reference point on the map for the image.
-    positon_type
+    position/position_type
+        Location of the GMT logo. The actual meaning of this parameter depends on the
+        ``position_type`` parameter.
+        - ``position_type="mapcoords"``: *position* is given as (x, y) in user
+          coordinates.
+        - ``position_type="boxcoords"``: *position* is given as (nx, ny) in normalized
+          coordinates, where (0, 0) is the lower-left corner and (1, 1) is the
+          upper-right corner of the map.
+        - ``position_type="plotcoords"``: *position* is given as (x, y) in plot
+          coordinates.
+        - ``position_type="inside"``: *position* is given as a two-character
+          justification code, meaning the anchor point of the rose is inside the map
+          bounding box.
+        - ``position_type="outside"``: *position* is given as a two-character
+          justification code, but the rose is outside the map bounding box.
     width/height
         Width or height of the GMT logo.
     box : bool or str
@@ -82,18 +94,18 @@ def logo(
                 position_type,
                 name="position_type",
                 mapping={
-                    "user": "g",
-                    "justify": "j",
-                    "mirror": "J",
-                    "normalize": "n",
-                    "plot": "x",
+                    "mapcoords": "g",
+                    "inside": "j",
+                    "outside": "J",
+                    "boxcoords": "n",
+                    "plotcoords": "x",
                 },
             ),
-            Alias(position, name="position", separator="/"),
+            Alias(position, name="position", sep="/"),
             Alias(height, name="height", prefix="+h"),
             Alias(width, name="width", prefix="+w"),
             Alias(justify, name="justify", prefix="+j"),
-            Alias(offset, name="offset", prefix="+o", separator="/", size=2),
+            Alias(anchor_offset, name="anchor_offset", prefix="+o", sep="/", size=2),
         ]
     ).merge(kwargs)
 

From 6fa17ac3cbe843d75268ce8464781adbc835d231 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sun, 10 Aug 2025 20:39:36 +0800
Subject: [PATCH 03/25] Updates

---
 pygmt/src/logo.py | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index f02cf44b8bc..230a23555a8 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -27,7 +27,7 @@ def logo(
     self,
     position: Sequence[str | float] | AnchorCode,
     position_type: Literal[
-        "mapcoords", "inside", "outside", "boxcoords", "plotcoords"
+        "mapcoords", "boxcoords", "plotcoords", "inside", "outside"
     ] = "mapcoords",
     height=None,
     width=None,
@@ -58,14 +58,15 @@ def logo(
           coordinates.
         - ``position_type="boxcoords"``: *position* is given as (nx, ny) in normalized
           coordinates, where (0, 0) is the lower-left corner and (1, 1) is the
-          upper-right corner of the map.
+          upper-right corner of the plot.
         - ``position_type="plotcoords"``: *position* is given as (x, y) in plot
-          coordinates.
+          coordinates, i.e., the distances in inches, centimeters, or points from the
+          lower left plot origin.
         - ``position_type="inside"``: *position* is given as a two-character
-          justification code, meaning the anchor point of the rose is inside the map
+          justification code, meaning the anchor point of the rose is inside the plot
           bounding box.
         - ``position_type="outside"``: *position* is given as a two-character
-          justification code, but the rose is outside the map bounding box.
+          justification code, but the rose is outside the plot bounding box.
     width/height
         Width or height of the GMT logo.
     box : bool or str
@@ -95,10 +96,10 @@ def logo(
                 name="position_type",
                 mapping={
                     "mapcoords": "g",
-                    "inside": "j",
-                    "outside": "J",
                     "boxcoords": "n",
                     "plotcoords": "x",
+                    "inside": "j",
+                    "outside": "J",
                 },
             ),
             Alias(position, name="position", sep="/"),

From cd1165fcc744853f4962e1ad8623290fd5bf0d7b Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Tue, 9 Sep 2025 22:59:20 +0800
Subject: [PATCH 04/25] fix

---
 examples/gallery/embellishments/gmt_logo.py |  3 +-
 pygmt/src/inset.py                          |  5 +-
 pygmt/src/logo.py                           | 94 +++++++++++++--------
 pygmt/tests/test_logo.py                    |  2 +-
 4 files changed, 61 insertions(+), 43 deletions(-)

diff --git a/examples/gallery/embellishments/gmt_logo.py b/examples/gallery/embellishments/gmt_logo.py
index b0311881577..1993dafa325 100644
--- a/examples/gallery/embellishments/gmt_logo.py
+++ b/examples/gallery/embellishments/gmt_logo.py
@@ -13,6 +13,5 @@
 
 # Add the GMT logo in the Top Right (TR) corner of the current plot, scaled up to be 3
 # centimeters wide and offset by 0.3 cm in x-direction and 0.6 cm in y-direction.
-fig.logo(position="jTR+o0.3c/0.6c+w3c")
-
+fig.logo(position="TR", position_type="inside", anchor_offset=(0.3, 0.6), width="3c")
 fig.show()
diff --git a/pygmt/src/inset.py b/pygmt/src/inset.py
index ad0195875e8..fee3289c528 100644
--- a/pygmt/src/inset.py
+++ b/pygmt/src/inset.py
@@ -139,9 +139,8 @@ def inset(
     ...         dcw="MG+gred",
     ...     )
     ...
-    >>> # Map elements outside the "with" statement are plotted in the main
-    >>> # figure
-    >>> fig.logo(position="jBR+o0.2c+w3c")
+    >>> # Map elements outside the "with" statement are plotted in the main figure
+    >>> fig.logo(position="BR", position_type="inside", offset=0.2, width="3c")
     >>> fig.show()
     """
     self._activate_figure()
diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 71d257e8433..a30c034a9ea 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -17,7 +17,7 @@
 @kwargs_to_strings(R="sequence", p="sequence")
 def logo(  # noqa: PLR0913
     self,
-    position: Sequence[str | float] | AnchorCode,
+    position: Sequence[str | float] | AnchorCode | None = None,
     position_type: Literal[
         "mapcoords", "boxcoords", "plotcoords", "inside", "outside"
     ] = "plotcoords",
@@ -26,7 +26,6 @@ def logo(  # noqa: PLR0913
     height: float | str | None = None,
     width: float | str | None = None,
     projection=None,
-    box=False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
@@ -36,14 +35,20 @@ def logo(  # noqa: PLR0913
     r"""
     Plot the GMT logo.
 
-    By default, the GMT logo is 2 inches wide and 1 inch high and
-    will be positioned relative to the current plot origin.
-    Use various options to change this and to place a transparent or
-    opaque rectangular map panel behind the GMT logo.
+    .. figure:: https://docs.generic-mapping-tools.org/6.5/_images/GMT_coverlogo.png
+       :alt: GMT logo
+       :align: center
+
+    By default, the GMT logo is 2 inches wide and 1 inch high and will be positioned
+    relative to the current plot origin. The position can be changed by specifying the
+    reference point (via ``position_type`` and ``position``) and anchor point (via
+    ``anchor`` and ``anchor_offset``). Refer to :doc:`/techref/reference_anchor_points`
+    for details about the positioning.
 
     Full GMT docs at :gmt-docs:`gmtlogo.html`.
 
     {aliases}
+       - D = position/position_type/anchor/anchor_offset/width/height
        - J = projection
        - V = verbose
        - c = panel
@@ -54,23 +59,42 @@ def logo(  # noqa: PLR0913
     {projection}
     {region}
     position/position_type
-        Location of the GMT logo. The actual meaning of this parameter depends on the
-        ``position_type`` parameter.
-        - ``position_type="mapcoords"``: *position* is given as (x, y) in user
+        Specify the reference point on the plot for the GMT logo. The reference point
+        can be specified in five different ways, which is selected by the
+        **position_type** parameter. The actual reference point is then given by the
+        coordinates or code specified by the **position** parameter.
+
+        The **position_type** parameter can be one of the following:
+
+        - ``"mapcoords"``: **position** is given as (*longitude*, *latitude*) in map
           coordinates.
-        - ``position_type="boxcoords"``: *position* is given as (nx, ny) in normalized
-          coordinates, where (0, 0) is the lower-left corner and (1, 1) is the
-          upper-right corner of the plot.
-        - ``position_type="plotcoords"``: *position* is given as (x, y) in plot
-          coordinates, i.e., the distances in inches, centimeters, or points from the
-          lower left plot origin.
-        - ``position_type="inside"``: *position* is given as a two-character
-          justification code, meaning the anchor point of the rose is inside the plot
-          bounding box.
-        - ``position_type="outside"``: *position* is given as a two-character
-          justification code, but the rose is outside the plot bounding box.
+        - ``"boxcoords"``: **position** is given as (*nx*, *ny*) in normalized
+          coordinates, i.e., fractional coordinates between 0 and 1 in both the x and y
+          directions. For example, (0, 0) is the lower-left corner and (1, 1) is the
+          upper-right corner of the plot bounding box.
+        - ``"plotcoords"``: **position** is given as (x, y) in plot coordinates, i.e.,
+          the distances in inches, centimeters, or points from the lower left plot
+          origin.
+        - ``"inside"`` or ``"outside"``: **position** is one of the nine
+          :doc:`2-character justification codes </techref/justification_codes>`, meaning
+          placing the reference point at specific locations, either inside or outside
+          the plot bounding box.
+    anchor
+        Anchor point of the magnetic rose, specified by one of the
+        :doc:`2-character justification codes </techref/justification_codes>`.
+        The default value depends on the **position_type** parameter.
+
+        - ``position_type="inside"``: **anchor** defaults to the same as **position**.
+        - ``position_type="outside"``: **anchor** defaults to the mirror opposite of
+          **position**.
+        - Otherwise, **anchor** defaults to ``"MC"`` (middle center).
+    anchor_offset
+        *offset* or (*offset_x*, *offset_y*).
+        Offset the anchor point by *offset_x* and *offset_y*. If a single value *offset*
+        is given, *offset_y* = *offset_x* = *offset*.
     width/height
-        Width or height of the GMT logo.
+        Width or height of the GMT logo. Since the aspect ratio is fixed, only one of
+        the two can be specified.
     box : bool or str
         If set to ``True``, draw a rectangular border around the
         GMT logo.
@@ -87,33 +111,29 @@ def logo(  # noqa: PLR0913
     {transparency}
     """
     self._activate_figure()
+
+    # width and height are mutually exclusive.
     if width is not None and height is not None:
         msg = "Cannot specify both width and height."
         raise GMTInvalidInput(msg)
 
+    # Mapping position_type to GMT shorthand.
+    _position_type = {
+        "mapcoords": "g",
+        "boxcoords": "n",
+        "plotcoords": "x",
+        "inside": "j",
+        "outside": "J",
+    }.get(position_type)
+
     aliasdict = AliasSystem(
         D=[
-            Alias(
-                position_type,
-                name="position_type",
-                mapping={
-                    "mapcoords": "g",
-                    "boxcoords": "n",
-                    "plotcoords": "x",
-                    "inside": "j",
-                    "outside": "J",
-                },
-            ),
-            Alias(position, name="position", sep="/"),
+            Alias(position, name="position", sep="/", size=2, prefix=_position_type),
             Alias(anchor, name="justify", prefix="+j"),
             Alias(anchor_offset, name="anchor_offset", prefix="+o", sep="/", size=2),
             Alias(height, name="height", prefix="+h"),
             Alias(width, name="width", prefix="+w"),
         ]
-    ).merge(kwargs)
-
-    aliasdict = AliasSystem(
-        F=Alias(box, name="box"),
     ).add_common(
         J=projection,
         V=verbose,
diff --git a/pygmt/tests/test_logo.py b/pygmt/tests/test_logo.py
index bcd803d8252..10bf8608456 100644
--- a/pygmt/tests/test_logo.py
+++ b/pygmt/tests/test_logo.py
@@ -25,7 +25,7 @@ def test_logo_on_a_map():
     fig = Figure()
     fig.basemap(region=[-90, -70, 0, 20], projection="M15c", frame=True)
     fig.logo(
-        position_type="justify",
+        position_type="inside",
         position="TR",
         offset=(0.25, 0.25),
         width="7.5c",

From b17ecfeb93b94c933fcf06a4bab72bbc63007f61 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Tue, 9 Sep 2025 23:19:12 +0800
Subject: [PATCH 05/25] Remove D from use_alias

---
 pygmt/src/logo.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index a30c034a9ea..76d9d5e0381 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -13,7 +13,7 @@
 
 
 @fmt_docstring
-@use_alias(R="region", D="position", F="box", S="style")
+@use_alias(R="region", F="box", S="style")
 @kwargs_to_strings(R="sequence", p="sequence")
 def logo(  # noqa: PLR0913
     self,

From 6ec9c6601d5c45ed763ae555b174998c87862e95 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Tue, 9 Sep 2025 23:31:08 +0800
Subject: [PATCH 06/25] Fix typos

---
 pygmt/src/logo.py        | 2 +-
 pygmt/tests/test_logo.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 76d9d5e0381..035864a3f31 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -124,7 +124,7 @@ def logo(  # noqa: PLR0913
         "plotcoords": "x",
         "inside": "j",
         "outside": "J",
-    }.get(position_type)
+    }[position_type]
 
     aliasdict = AliasSystem(
         D=[
diff --git a/pygmt/tests/test_logo.py b/pygmt/tests/test_logo.py
index 10bf8608456..b75c6c05641 100644
--- a/pygmt/tests/test_logo.py
+++ b/pygmt/tests/test_logo.py
@@ -27,7 +27,7 @@ def test_logo_on_a_map():
     fig.logo(
         position_type="inside",
         position="TR",
-        offset=(0.25, 0.25),
+        anchor_offset=(0.25, 0.25),
         width="7.5c",
         box=True,
     )

From 9a0575d37c232158f962b0b477ec487a284e284d Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 12 Sep 2025 00:43:00 +0800
Subject: [PATCH 07/25] Improve docstrings

---
 pygmt/src/logo.py        | 14 +++++++++-----
 pygmt/tests/test_logo.py | 10 ++++++++++
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 035864a3f31..dfca512973b 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -38,6 +38,7 @@ def logo(  # noqa: PLR0913
     .. figure:: https://docs.generic-mapping-tools.org/6.5/_images/GMT_coverlogo.png
        :alt: GMT logo
        :align: center
+       :width: 300px
 
     By default, the GMT logo is 2 inches wide and 1 inch high and will be positioned
     relative to the current plot origin. The position can be changed by specifying the
@@ -67,20 +68,23 @@ def logo(  # noqa: PLR0913
         The **position_type** parameter can be one of the following:
 
         - ``"mapcoords"``: **position** is given as (*longitude*, *latitude*) in map
-          coordinates.
+          coordinates. For example, (120, -45) means placing the reference point at
+          120°E and 45°S in map coordinates.
         - ``"boxcoords"``: **position** is given as (*nx*, *ny*) in normalized
           coordinates, i.e., fractional coordinates between 0 and 1 in both the x and y
           directions. For example, (0, 0) is the lower-left corner and (1, 1) is the
           upper-right corner of the plot bounding box.
         - ``"plotcoords"``: **position** is given as (x, y) in plot coordinates, i.e.,
           the distances in inches, centimeters, or points from the lower left plot
-          origin.
+          origin. For example, ("1c", "2c") means placing the reference point 1 cm to
+          the right and 2 cm above the lower left plot origin.
         - ``"inside"`` or ``"outside"``: **position** is one of the nine
           :doc:`2-character justification codes </techref/justification_codes>`, meaning
           placing the reference point at specific locations, either inside or outside
-          the plot bounding box.
+          the plot bounding box. E.g., ``"TL"`` means placing the reference point at the
+          top left corner of the plot bounding box, either inside or outside the box.
     anchor
-        Anchor point of the magnetic rose, specified by one of the
+        Anchor point of the GMT logo, specified by one of the
         :doc:`2-character justification codes </techref/justification_codes>`.
         The default value depends on the **position_type** parameter.
 
@@ -129,7 +133,7 @@ def logo(  # noqa: PLR0913
     aliasdict = AliasSystem(
         D=[
             Alias(position, name="position", sep="/", size=2, prefix=_position_type),
-            Alias(anchor, name="justify", prefix="+j"),
+            Alias(anchor, name="anchor", prefix="+j"),
             Alias(anchor_offset, name="anchor_offset", prefix="+o", sep="/", size=2),
             Alias(height, name="height", prefix="+h"),
             Alias(width, name="width", prefix="+w"),
diff --git a/pygmt/tests/test_logo.py b/pygmt/tests/test_logo.py
index b75c6c05641..c7691095e53 100644
--- a/pygmt/tests/test_logo.py
+++ b/pygmt/tests/test_logo.py
@@ -4,6 +4,7 @@
 
 import pytest
 from pygmt import Figure
+from pygmt.exceptions import GMTInvalidInput
 
 
 @pytest.mark.benchmark
@@ -32,3 +33,12 @@ def test_logo_on_a_map():
         box=True,
     )
     return fig
+
+
+def test_logo_width_and_height():
+    """
+    Test that an error is raised when both width and height are specified.
+    """
+    fig = Figure()
+    with pytest.raises(GMTInvalidInput):
+        fig.logo(width="5c", height="5c")

From d19959ec383c6d640c28a5e4de9317f905889a0c Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 12 Sep 2025 12:43:36 +0800
Subject: [PATCH 08/25] Improve docstrings

---
 pygmt/src/logo.py | 56 +++++++++++++++++++++++------------------------
 1 file changed, 27 insertions(+), 29 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index dfca512973b..8487391bcab 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -57,45 +57,41 @@ def logo(  # noqa: PLR0913
 
     Parameters
     ----------
-    {projection}
-    {region}
     position/position_type
-        Specify the reference point on the plot for the GMT logo. The reference point
-        can be specified in five different ways, which is selected by the
-        **position_type** parameter. The actual reference point is then given by the
-        coordinates or code specified by the **position** parameter.
-
-        The **position_type** parameter can be one of the following:
-
-        - ``"mapcoords"``: **position** is given as (*longitude*, *latitude*) in map
-          coordinates. For example, (120, -45) means placing the reference point at
-          120°E and 45°S in map coordinates.
-        - ``"boxcoords"``: **position** is given as (*nx*, *ny*) in normalized
-          coordinates, i.e., fractional coordinates between 0 and 1 in both the x and y
-          directions. For example, (0, 0) is the lower-left corner and (1, 1) is the
+        Specify the reference point on the plot for the GMT logo. The method of
+        defining the the reference point is controlled by **position_type**, and the
+        exact location is set by **position**.
+
+        The **position_type** parameter can take one of the following values:
+
+        - ``"mapcoords"``: **position** is specified as (*longitude*, *latitude*) in map
+          coordinates. Example: (120, -45) places the reference point at 120°E, 45°S.
+        - ``"boxcoords"``: **position** is specified as (*nx*, *ny*) in normalized
+          coordinates, i.e., fractional values between 0 and 1 along the x- and y-axes.
+          Example: (0, 0) corresponds to the lower-left corner, and (1, 1) to the
           upper-right corner of the plot bounding box.
-        - ``"plotcoords"``: **position** is given as (x, y) in plot coordinates, i.e.,
-          the distances in inches, centimeters, or points from the lower left plot
-          origin. For example, ("1c", "2c") means placing the reference point 1 cm to
-          the right and 2 cm above the lower left plot origin.
+        - ``"plotcoords"``: **position** is specified as (*x*, *y*) in plot coordinates,
+          i.e., distances from the lower-left plot origin given in inches, centimeters,
+          or points. Example: ("1c", "2c") places the reference point 1 cm to the right
+          and 2 cm above the plot origin.
         - ``"inside"`` or ``"outside"``: **position** is one of the nine
-          :doc:`2-character justification codes </techref/justification_codes>`, meaning
-          placing the reference point at specific locations, either inside or outside
-          the plot bounding box. E.g., ``"TL"`` means placing the reference point at the
-          top left corner of the plot bounding box, either inside or outside the box.
+          :doc:two-character justification codes </techref/justification_codes>,
+          indicating a specific location relative to the plot bounding box. Example:
+          ``"TL"`` places the reference point at the top-left corner, either inside or
+          outside the bounding box.
     anchor
-        Anchor point of the GMT logo, specified by one of the
+        Specify the anchor point of the GMT logo, using one of the
         :doc:`2-character justification codes </techref/justification_codes>`.
-        The default value depends on the **position_type** parameter.
+        The default value depends on **position_type**.
 
         - ``position_type="inside"``: **anchor** defaults to the same as **position**.
         - ``position_type="outside"``: **anchor** defaults to the mirror opposite of
           **position**.
         - Otherwise, **anchor** defaults to ``"MC"`` (middle center).
     anchor_offset
-        *offset* or (*offset_x*, *offset_y*).
-        Offset the anchor point by *offset_x* and *offset_y*. If a single value *offset*
-        is given, *offset_y* = *offset_x* = *offset*.
+        Specifies an offset for the anchor point as *offset* or
+        (*offset_x*, *offset_y*). If a single value *offset* is given, both *offset_x*
+        and *offset_y* are set to *offset*.
     width/height
         Width or height of the GMT logo. Since the aspect ratio is fixed, only one of
         the two can be specified.
@@ -110,6 +106,8 @@ def logo(  # noqa: PLR0913
           [Default]
         - **n** to skip the label placement
         - **u** to place the URL to the GMT site
+    {projection}
+    {region}
     {verbose}
     {panel}
     {transparency}
@@ -121,7 +119,7 @@ def logo(  # noqa: PLR0913
         msg = "Cannot specify both width and height."
         raise GMTInvalidInput(msg)
 
-    # Mapping position_type to GMT shorthand.
+    # Mapping position_type to GMT single-letter code.
     _position_type = {
         "mapcoords": "g",
         "boxcoords": "n",

From f8f418b2710207ff8cc84f666b4e99f449936a8f Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sun, 14 Sep 2025 21:00:47 +0800
Subject: [PATCH 09/25] Backward compatibility

---
 pygmt/src/logo.py        | 14 ++++++++++++++
 pygmt/tests/test_logo.py | 28 ++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 8487391bcab..0d7c6d3de94 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -128,6 +128,20 @@ def logo(  # noqa: PLR0913
         "outside": "J",
     }[position_type]
 
+    # Prior PyGMT v0.17.0, 'position' was aliased to the -D option.
+    # For backward compatibility, we need to check if users pass a string with the GMT
+    # CLI syntax to 'position', i.e., a string starting with one of the leading
+    # single-letter or contains modifiers with "+".
+    if isinstance(position, str) and (position[0] in "gnxjJ" or "+" in position):
+        if any(v is not None for v in (anchor, anchor_offset, height, width)):
+            msg = (
+                "Parameter 'position' is given with a raw GMT CLI syntax, and conflicts "
+                "with other parameters (anchor, anchor_offset, height, width). "
+                "Please refer to the documentation for the recommended usage."
+            )
+            raise GMTInvalidInput(msg)
+        _position_type = ""  # Unset _position_type to an empty string.
+
     aliasdict = AliasSystem(
         D=[
             Alias(position, name="position", sep="/", size=2, prefix=_position_type),
diff --git a/pygmt/tests/test_logo.py b/pygmt/tests/test_logo.py
index c7691095e53..457304f96a3 100644
--- a/pygmt/tests/test_logo.py
+++ b/pygmt/tests/test_logo.py
@@ -35,6 +35,34 @@ def test_logo_on_a_map():
     return fig
 
 
+@pytest.mark.mpl_image_compare(filename="test_logo_position_deprecated_syntax.png")
+def test_logo_position():
+    """
+    Test that the new group of parameters works as expected.
+    """
+    fig = Figure()
+    fig.basemap(region=[-90, -70, 0, 20], projection="M15c", frame=True)
+    fig.logo(position="TL", position_type="inside")
+    fig.logo(position="TR", position_type="inside", width="7.5c")
+    fig.logo(position=(6, 0), width="7.5c")
+    fig.logo(position=(0, 0))
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_logo_position_deprecated_syntax():
+    """
+    Test that passing the deprecated GMT CLI syntax string to 'position' works.
+    """
+    fig = Figure()
+    fig.basemap(region=[-90, -70, 0, 20], projection="M15c", frame=True)
+    fig.logo(position="jTL")
+    fig.logo(position="jTR+w7.5c")
+    fig.logo(position="6/0+w7.5c")
+    fig.logo(position="0/0")  # This is actually the new syntax.
+    return fig
+
+
 def test_logo_width_and_height():
     """
     Test that an error is raised when both width and height are specified.

From df50342bd899a211fab51dcc43c5e632661e9b29 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Mon, 15 Sep 2025 14:40:42 +0800
Subject: [PATCH 10/25] Improve Figure.logo tests

---
 .../baseline/test_logo_position_type.png.dvc  |  5 ++++
 pygmt/tests/test_logo.py                      | 24 +++++++++++--------
 2 files changed, 19 insertions(+), 10 deletions(-)
 create mode 100644 pygmt/tests/baseline/test_logo_position_type.png.dvc

diff --git a/pygmt/tests/baseline/test_logo_position_type.png.dvc b/pygmt/tests/baseline/test_logo_position_type.png.dvc
new file mode 100644
index 00000000000..a1ea8c1a191
--- /dev/null
+++ b/pygmt/tests/baseline/test_logo_position_type.png.dvc
@@ -0,0 +1,5 @@
+outs:
+- md5: 9b9d740219df9edb298dbc49e7ef1351
+  size: 232635
+  hash: md5
+  path: test_logo_position_type.png
diff --git a/pygmt/tests/test_logo.py b/pygmt/tests/test_logo.py
index 457304f96a3..c9bcacfd17d 100644
--- a/pygmt/tests/test_logo.py
+++ b/pygmt/tests/test_logo.py
@@ -35,21 +35,23 @@ def test_logo_on_a_map():
     return fig
 
 
-@pytest.mark.mpl_image_compare(filename="test_logo_position_deprecated_syntax.png")
-def test_logo_position():
+@pytest.mark.mpl_image_compare
+def test_logo_position_type():
     """
     Test that the new group of parameters works as expected.
     """
     fig = Figure()
     fig.basemap(region=[-90, -70, 0, 20], projection="M15c", frame=True)
-    fig.logo(position="TL", position_type="inside")
-    fig.logo(position="TR", position_type="inside", width="7.5c")
-    fig.logo(position=(6, 0), width="7.5c")
-    fig.logo(position=(0, 0))
+    fig.logo(position_type="inside", position="TL")
+    fig.logo(position_type="outside", position="TR")
+    fig.logo(position_type="mapcoords", position=(-80, 15))
+    fig.logo(position_type="boxcoords", position=(0, 0.5))
+    fig.logo(position_type="plotcoords", position=("2c", "0c"), width="5c")
+    fig.logo(position=("8c", "0c"))  # Default position_type is "plotcoords".
     return fig
 
 
-@pytest.mark.mpl_image_compare
+@pytest.mark.mpl_image_compare(filename="test_logo_position_type.png")
 def test_logo_position_deprecated_syntax():
     """
     Test that passing the deprecated GMT CLI syntax string to 'position' works.
@@ -57,9 +59,11 @@ def test_logo_position_deprecated_syntax():
     fig = Figure()
     fig.basemap(region=[-90, -70, 0, 20], projection="M15c", frame=True)
     fig.logo(position="jTL")
-    fig.logo(position="jTR+w7.5c")
-    fig.logo(position="6/0+w7.5c")
-    fig.logo(position="0/0")  # This is actually the new syntax.
+    fig.logo(position="JTR")
+    fig.logo(position="g-80/15")
+    fig.logo(position="n0/0.5")
+    fig.logo(position="x2c/0c+w5c")
+    fig.logo(position="8c/0c")
     return fig
 
 

From 8699d9aceca9ab49358f2394c3ddd0c328f3cf86 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Mon, 15 Sep 2025 15:07:32 +0800
Subject: [PATCH 11/25] Add a test for mixed syntax

---
 pygmt/tests/test_logo.py | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/pygmt/tests/test_logo.py b/pygmt/tests/test_logo.py
index c9bcacfd17d..2d39c52c534 100644
--- a/pygmt/tests/test_logo.py
+++ b/pygmt/tests/test_logo.py
@@ -74,3 +74,14 @@ def test_logo_width_and_height():
     fig = Figure()
     with pytest.raises(GMTInvalidInput):
         fig.logo(width="5c", height="5c")
+
+
+def test_logo_position_mixed_syntax():
+    """
+    Test that an error is raised when mixing new and deprecated syntax in 'position'.
+    """
+    fig = Figure()
+    with pytest.raises(GMTInvalidInput):
+        fig.logo(position="jTL", width="5c")
+    with pytest.raises(GMTInvalidInput):
+        fig.logo(position="jTL", anchor="BR")

From 5e02d22c3c5d82b91b07592d5fe71730e87b875b Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 15 Oct 2025 12:26:12 +0800
Subject: [PATCH 12/25] Update docstrings

---
 pygmt/src/logo.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 9425c61ee95..0c47751c4d2 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -63,11 +63,11 @@ def logo(  # noqa: PLR0913
 
     Parameters
     ----------
-    position/position_type
-        Specify the reference point on the plot for the GMT logo. The method of
-        defining the the reference point is controlled by **position_type**, and the
-        exact location is set by **position**.
-
+    position
+        Specify the reference point on the plot for the GMT logo. The method of defining
+        the reference point is controlled by **position_type**, and the exact location 
+        is set by **position**.
+    position_type
         The **position_type** parameter can take one of the following values:
 
         - ``"mapcoords"``: **position** is specified as (*longitude*, *latitude*) in map

From 75682649ec356a922a84eea4762111ffe0652e41 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 15 Oct 2025 13:10:14 +0800
Subject: [PATCH 13/25] Fix formatting

---
 pygmt/src/logo.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 0c47751c4d2..3e5f4191e84 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -65,7 +65,7 @@ def logo(  # noqa: PLR0913
     ----------
     position
         Specify the reference point on the plot for the GMT logo. The method of defining
-        the reference point is controlled by **position_type**, and the exact location 
+        the reference point is controlled by **position_type**, and the exact location
         is set by **position**.
     position_type
         The **position_type** parameter can take one of the following values:

From 43d08a0960e29f1db1b6876b1d0bf7bd23404848 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 15 Oct 2025 13:16:08 +0800
Subject: [PATCH 14/25] Fix docstrings

---
 pygmt/src/logo.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 3e5f4191e84..e97dd06bd45 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -51,8 +51,12 @@ def logo(  # noqa: PLR0913
 
     Full GMT docs at :gmt-docs:`gmtlogo.html`.
 
-    {aliases}
-       - D = position/position_type/anchor/anchor_offset/width/height
+    **Aliases:**
+
+    .. hlist::
+       :columns: 3
+
+       - D = position/position_type, **+j**: anchor, **+o**: anchor_offset, **+w**: width, **+h**:height
        - F = box
        - J = projection
        - R = region

From 91b6b258fba7a1cd04b6ff97a145cda1530ba7b0 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 15 Oct 2025 14:00:11 +0800
Subject: [PATCH 15/25] Fix long docstrings

---
 pygmt/src/logo.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index e97dd06bd45..9ef29b08507 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -53,10 +53,15 @@ def logo(  # noqa: PLR0913
 
     **Aliases:**
 
+    .. hlist::
+       :columns: 1
+
+       - D = position/position_type, **+j**: anchor, **+o**: anchor_offset,
+         **+w**: width, **+h**:height
+
     .. hlist::
        :columns: 3
 
-       - D = position/position_type, **+j**: anchor, **+o**: anchor_offset, **+w**: width, **+h**:height
        - F = box
        - J = projection
        - R = region

From 6d3dc9bb78bc31fb6fb3e30b0bccde6273c6ff32 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 16 Oct 2025 16:33:27 +0800
Subject: [PATCH 16/25] Fix docstrings

---
 pygmt/src/logo.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 9ef29b08507..cb26be33dec 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -38,7 +38,7 @@ def logo(  # noqa: PLR0913
     r"""
     Plot the GMT logo.
 
-    .. figure:: https://docs.generic-mapping-tools.org/6.5/_images/GMT_coverlogo.png
+    .. figure:: https://docs.generic-mapping-tools.org/6.6/_images/GMT_coverlogo.png
        :alt: GMT logo
        :align: center
        :width: 300px
@@ -57,8 +57,7 @@ def logo(  # noqa: PLR0913
        :columns: 1
 
        - D = position/position_type, **+j**: anchor, **+o**: anchor_offset,
-         **+w**: width, **+h**:height
-
+         **+w**: width, **+h**: height
     .. hlist::
        :columns: 3
 

From 62e62747af39e20105281225e7c97729798da8ed Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 16 Oct 2025 16:35:14 +0800
Subject: [PATCH 17/25] Fix docstrings

---
 pygmt/src/logo.py | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index cb26be33dec..8ff6f7d5d58 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -73,22 +73,23 @@ def logo(  # noqa: PLR0913
     ----------
     position
         Specify the reference point on the plot for the GMT logo. The method of defining
-        the reference point is controlled by **position_type**, and the exact location
-        is set by **position**.
+        the reference point is controlled by ``position_type``, and the exact location
+        is set by ``position``.
     position_type
-        The **position_type** parameter can take one of the following values:
+        Specify the type of coordinates used to define the reference point. It can be
+        one of the following values:
 
-        - ``"mapcoords"``: **position** is specified as (*longitude*, *latitude*) in map
+        - ``"mapcoords"``: ``position`` is specified as (*longitude*, *latitude*) in map
           coordinates. Example: (120, -45) places the reference point at 120°E, 45°S.
-        - ``"boxcoords"``: **position** is specified as (*nx*, *ny*) in normalized
+        - ``"boxcoords"``: ``position`` is specified as (*nx*, *ny*) in normalized
           coordinates, i.e., fractional values between 0 and 1 along the x- and y-axes.
           Example: (0, 0) corresponds to the lower-left corner, and (1, 1) to the
           upper-right corner of the plot bounding box.
-        - ``"plotcoords"``: **position** is specified as (*x*, *y*) in plot coordinates,
+        - ``"plotcoords"``: ``position`` is specified as (*x*, *y*) in plot coordinates,
           i.e., distances from the lower-left plot origin given in inches, centimeters,
           or points. Example: ("1c", "2c") places the reference point 1 cm to the right
           and 2 cm above the plot origin.
-        - ``"inside"`` or ``"outside"``: **position** is one of the nine
+        - ``"inside"`` or ``"outside"``: ``position`` is one of the nine
           :doc:two-character justification codes </techref/justification_codes>,
           indicating a specific location relative to the plot bounding box. Example:
           ``"TL"`` places the reference point at the top-left corner, either inside or
@@ -106,7 +107,8 @@ def logo(  # noqa: PLR0913
         Specifies an offset for the anchor point as *offset* or
         (*offset_x*, *offset_y*). If a single value *offset* is given, both *offset_x*
         and *offset_y* are set to *offset*.
-    width/height
+    width
+    height
         Width or height of the GMT logo. Since the aspect ratio is fixed, only one of
         the two can be specified.
     box

From e3d14d509b00c43569b0d43af4e3b6551a6c56d7 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 16 Oct 2025 16:38:54 +0800
Subject: [PATCH 18/25] Fix docstrings

---
 pygmt/src/logo.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 8ff6f7d5d58..ef57964b641 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -97,12 +97,12 @@ def logo(  # noqa: PLR0913
     anchor
         Specify the anchor point of the GMT logo, using one of the
         :doc:`2-character justification codes </techref/justification_codes>`.
-        The default value depends on **position_type**.
+        The default value depends on ``position_type``.
 
-        - ``position_type="inside"``: **anchor** defaults to the same as **position**.
-        - ``position_type="outside"``: **anchor** defaults to the mirror opposite of
-          **position**.
-        - Otherwise, **anchor** defaults to ``"MC"`` (middle center).
+        - ``position_type="inside"``: ``anchor`` defaults to the same as ``position``.
+        - ``position_type="outside"``: ``anchor`` defaults to the mirror opposite of
+          ``position``.
+        - Otherwise, ``anchor`` defaults to ``"MC"`` (middle center).
     anchor_offset
         Specifies an offset for the anchor point as *offset* or
         (*offset_x*, *offset_y*). If a single value *offset* is given, both *offset_x*

From e73dc9ed2bcd4dc3656cfda43e277f68927dffbf Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 16 Oct 2025 16:40:22 +0800
Subject: [PATCH 19/25] Fix comments

---
 pygmt/src/logo.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index ef57964b641..f0119ec176c 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -147,7 +147,7 @@ def logo(  # noqa: PLR0913
     # Prior PyGMT v0.17.0, 'position' was aliased to the -D option.
     # For backward compatibility, we need to check if users pass a string with the GMT
     # CLI syntax to 'position', i.e., a string starting with one of the leading
-    # single-letter or contains modifiers with "+".
+    # single-letter codes or contains modifiers with "+".
     if isinstance(position, str) and (position[0] in "gnxjJ" or "+" in position):
         if any(v is not None for v in (anchor, anchor_offset, height, width)):
             msg = (

From e77993b91e7ae4825a75acd5bca4684320ebf833 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 16 Oct 2025 18:19:21 +0800
Subject: [PATCH 20/25] Fix docstrings

---
 pygmt/src/logo.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index f0119ec176c..379f7507456 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -90,13 +90,13 @@ def logo(  # noqa: PLR0913
           or points. Example: ("1c", "2c") places the reference point 1 cm to the right
           and 2 cm above the plot origin.
         - ``"inside"`` or ``"outside"``: ``position`` is one of the nine
-          :doc:two-character justification codes </techref/justification_codes>,
+          :doc:two-character justification codes </techref/justification_codes.md>,
           indicating a specific location relative to the plot bounding box. Example:
           ``"TL"`` places the reference point at the top-left corner, either inside or
           outside the bounding box.
     anchor
         Specify the anchor point of the GMT logo, using one of the
-        :doc:`2-character justification codes </techref/justification_codes>`.
+        :doc:`2-character justification codes </techref/justification_codes.md>`.
         The default value depends on ``position_type``.
 
         - ``position_type="inside"``: ``anchor`` defaults to the same as ``position``.

From 66f9c4d9ab31475987b3dd99fc31c1376c660053 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 16 Oct 2025 18:37:55 +0800
Subject: [PATCH 21/25] Fix docstrings

---
 pygmt/src/logo.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 379f7507456..c10e21bba15 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -90,13 +90,13 @@ def logo(  # noqa: PLR0913
           or points. Example: ("1c", "2c") places the reference point 1 cm to the right
           and 2 cm above the plot origin.
         - ``"inside"`` or ``"outside"``: ``position`` is one of the nine
-          :doc:two-character justification codes </techref/justification_codes.md>,
+          :doc:`two-character justification codes </techref/justification_codes>`,
           indicating a specific location relative to the plot bounding box. Example:
           ``"TL"`` places the reference point at the top-left corner, either inside or
           outside the bounding box.
     anchor
         Specify the anchor point of the GMT logo, using one of the
-        :doc:`2-character justification codes </techref/justification_codes.md>`.
+        :doc:`2-character justification codes </techref/justification_codes>`.
         The default value depends on ``position_type``.
 
         - ``position_type="inside"``: ``anchor`` defaults to the same as ``position``.

From fb9547881b00f3c475963f8451d857bd2796fa45 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 18 Oct 2025 16:10:45 +0800
Subject: [PATCH 22/25] Fix offset to anchor_offset in the Figure.inset doctest

---
 pygmt/src/inset.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pygmt/src/inset.py b/pygmt/src/inset.py
index 749875c7728..48cc56084b6 100644
--- a/pygmt/src/inset.py
+++ b/pygmt/src/inset.py
@@ -127,7 +127,7 @@ def inset(
     ...     )
     ...
     >>> # Map elements outside the "with" statement are plotted in the main figure
-    >>> fig.logo(position="BR", position_type="inside", offset=0.2, width="3c")
+    >>> fig.logo(position="BR", position_type="inside", anchor_offset=0.2, width="3c")
     >>> fig.show()
     """
     self._activate_figure()

From 51fe97657053a464ba330728db83c973e68dd7cc Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Tue, 21 Oct 2025 17:00:12 +0800
Subject: [PATCH 23/25] Improve the handling of deprecation position parameter

---
 pygmt/src/logo.py | 49 +++++++++++++++++++++++++++++------------------
 1 file changed, 30 insertions(+), 19 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index c10e21bba15..b6f146f0c48 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -130,37 +130,48 @@ def logo(  # noqa: PLR0913
     """
     self._activate_figure()
 
+    # Prior PyGMT v0.17.0, 'position' was aliased to the -D option. For backward
+    # compatibility, need to check if users pass a string with the GMT CLI syntax to
+    # 'position', i.e., a string starting with one of the codes "g", "n", "x", "j", "J",
+    # or contains modifiers with "+".
+    _is_deprecated_position = isinstance(position, str) and (
+        position.startswith(("g", "n", "x", "j", "J")) or "+" in position
+    )
+
+    if _is_deprecated_position and any(
+        v is not None for v in (anchor, anchor_offset, height, width)
+    ):
+        msg = (
+            "Parameter 'position' is given with a raw GMT CLI syntax, and conflicts "
+            "with parameters 'anchor', 'anchor_offset', 'height', and 'width'. "
+            "Please refer to the documentation for the recommended usage."
+        )
+        raise GMTInvalidInput(msg)
+
     # width and height are mutually exclusive.
     if width is not None and height is not None:
         msg = "Cannot specify both width and height."
         raise GMTInvalidInput(msg)
 
-    # Mapping position_type to GMT single-letter code.
-    _position_type = {
+    _position_types = {
         "mapcoords": "g",
         "boxcoords": "n",
         "plotcoords": "x",
         "inside": "j",
         "outside": "J",
-    }[position_type]
-
-    # Prior PyGMT v0.17.0, 'position' was aliased to the -D option.
-    # For backward compatibility, we need to check if users pass a string with the GMT
-    # CLI syntax to 'position', i.e., a string starting with one of the leading
-    # single-letter codes or contains modifiers with "+".
-    if isinstance(position, str) and (position[0] in "gnxjJ" or "+" in position):
-        if any(v is not None for v in (anchor, anchor_offset, height, width)):
-            msg = (
-                "Parameter 'position' is given with a raw GMT CLI syntax, and conflicts "
-                "with other parameters (anchor, anchor_offset, height, width). "
-                "Please refer to the documentation for the recommended usage."
-            )
-            raise GMTInvalidInput(msg)
-        _position_type = ""  # Unset _position_type to an empty string.
+    }
 
     aliasdict = AliasSystem(
-        D=[
-            Alias(position, name="position", sep="/", size=2, prefix=_position_type),
+        D=Alias(position, name="position")
+        if _is_deprecated_position
+        else [
+            Alias(
+                position,
+                name="position",
+                sep="/",
+                size=2,
+                prefix=_position_types[position_type],
+            ),
             Alias(anchor, name="anchor", prefix="+j"),
             Alias(anchor_offset, name="anchor_offset", prefix="+o", sep="/", size=2),
             Alias(height, name="height", prefix="+h"),

From 573e950c96aadf9056130cc01a6439319b7def63 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 12 Nov 2025 13:25:43 +0800
Subject: [PATCH 24/25] Fix docstrings in tests

---
 pygmt/tests/test_logo.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pygmt/tests/test_logo.py b/pygmt/tests/test_logo.py
index 2d39c52c534..6ebf7943655 100644
--- a/pygmt/tests/test_logo.py
+++ b/pygmt/tests/test_logo.py
@@ -38,7 +38,7 @@ def test_logo_on_a_map():
 @pytest.mark.mpl_image_compare
 def test_logo_position_type():
     """
-    Test that the new group of parameters works as expected.
+    Test that different position types work as expected.
     """
     fig = Figure()
     fig.basemap(region=[-90, -70, 0, 20], projection="M15c", frame=True)

From 173e7a4ad74ead3de1f4ff9a5b105ec592a97e1d Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 12 Nov 2025 13:29:53 +0800
Subject: [PATCH 25/25] Shorten the docstrings

---
 pygmt/src/logo.py | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 5d3f5ebf154..08dfd6430f3 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -80,24 +80,22 @@ def logo(  # noqa: PLR0913
         one of the following values:
 
         - ``"mapcoords"``: ``position`` is specified as (*longitude*, *latitude*) in map
-          coordinates. Example: (120, -45) places the reference point at 120°E, 45°S.
+          coordinates.
         - ``"boxcoords"``: ``position`` is specified as (*nx*, *ny*) in normalized
           coordinates, i.e., fractional values between 0 and 1 along the x- and y-axes.
-          Example: (0, 0) corresponds to the lower-left corner, and (1, 1) to the
-          upper-right corner of the plot bounding box.
         - ``"plotcoords"``: ``position`` is specified as (*x*, *y*) in plot coordinates,
           i.e., distances from the lower-left plot origin given in inches, centimeters,
-          or points. Example: ("1c", "2c") places the reference point 1 cm to the right
-          and 2 cm above the plot origin.
+          or points.
         - ``"inside"`` or ``"outside"``: ``position`` is one of the nine
           :doc:`two-character justification codes </techref/justification_codes>`,
-          indicating a specific location relative to the plot bounding box. Example:
-          ``"TL"`` places the reference point at the top-left corner, either inside or
-          outside the bounding box.
+          indicating a specific location relative to the plot bounding box.
+
+        Refer to :doc:`/techref/reference_anchor_points` for details about the
+        positioning.
     anchor
         Specify the anchor point of the GMT logo, using one of the
-        :doc:`2-character justification codes </techref/justification_codes>`.
-        The default value depends on ``position_type``.
+        :doc:`2-character justification codes </techref/justification_codes>`. The
+        default value depends on ``position_type``.
 
         - ``position_type="inside"``: ``anchor`` defaults to the same as ``position``.
         - ``position_type="outside"``: ``anchor`` defaults to the mirror opposite of