Improve decorators @use_alias/@fmt_docstrings to list non-aliased aliases (#3965)

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

Author: seisman

pygmt/helpers/decorators.py

@@ -450,7 +450,9 @@ def fmt_docstring(module_func):
         aliases.append("   :columns: 3\n")
         for arg in sorted(module_func.aliases):
             alias = module_func.aliases[arg]
-            aliases.append(f"   - {arg} = {alias}")
+            # Trailing dash means it's not aliased but should be listed.
+            # Remove the trailing dash if it exists.
+            aliases.append(f"   - {arg} = {alias.rstrip('-')}")
         filler_text["aliases"] = "\n".join(aliases)
 
     filler_text["table-classes"] = (
@@ -484,6 +486,9 @@ def _insert_alias(module_func, default_value=None):
     kwargs_param = wrapped_params.pop(-1)
     # Add new parameters from aliases
     for alias in module_func.aliases.values():
+        if alias.endswith("-"):
+            # Trailing dash means it's not aliased but should be listed.
+            continue
         if alias not in sig.parameters:
             new_param = Parameter(
                 alias, kind=Parameter.KEYWORD_ONLY, default=default_value
@@ -548,6 +553,31 @@ def new_module(*args, **kwargs):
             New module that parses and replaces the registered aliases.
             """
             for short_param, long_alias in aliases.items():
+                if long_alias.endswith("-"):
+                    _long_alias = long_alias.rstrip("-")
+                    # Trailing dash means it's not aliased but should be listed.
+                    _alias_list = _long_alias.split("/")
+                    if (
+                        any(_alias in kwargs for _alias in _alias_list)
+                        and short_param in kwargs
+                    ):  # Both long- and short- forms are given.
+                        msg = (
+                            f"Parameters in short-form ({short_param}) and "
+                            f"long-form ({_long_alias}) can't coexist."
+                        )
+                        raise GMTInvalidInput(msg)
+                    if short_param in kwargs:  # Only short-alias is given
+                        if len(_alias_list) > 1:  # Aliased to multiple long-forms
+                            msg = (
+                                f"Short-form parameter ({short_param}) is not "
+                                f"recognized. Use long-form parameter(s) "
+                                f"'{_long_alias}' instead."
+                            )
+                            raise GMTInvalidInput(msg)
+                        # If there is only one long-form parameter, use it.
+                        kwargs[_long_alias] = kwargs.pop(short_param)
+                    continue
+
                 if long_alias in kwargs and short_param in kwargs:
                     msg = (
                         f"Parameters in short-form ({short_param}) and "

pygmt/src/coast.py

@@ -23,6 +23,7 @@
     A="area_thresh",
     B="frame",
     C="lakes",
+    D="resolution-",
     E="dcw",
     F="box",
     G="land",

pygmt/src/grdclip.py

@@ -23,7 +23,9 @@
 # TODO(PyGMT>=0.19.0): Remove the deprecated "new" parameter.
 @fmt_docstring
 @deprecate_parameter("new", "replace", "v0.15.0", remove_version="v0.19.0")
-@use_alias(R="region", V="verbose")
+@use_alias(
+    R="region", Sa="above-", Sb="below-", Si="between-", Sr="replace-", V="verbose"
+)
 @kwargs_to_strings(R="sequence")
 def grdclip(
     grid: PathLike | xr.DataArray,

pygmt/src/grdfill.py

@@ -109,7 +109,14 @@ def _parse_fill_mode(
 # TODO(PyGMT>=0.19.0): Remove the deprecated 'no_data' parameter.
 # TODO(PyGMT>=0.19.0): Remove the deprecated 'mode' parameter.
 @deprecate_parameter("no_data", "hole", "v0.15.0", remove_version="v0.19.0")
-@use_alias(N="hole", R="region", V="verbose", f="coltypes")
+@use_alias(
+    A="constantfill/gridfill/neighborfill/splinefill/mode-",
+    L="inquire-",
+    N="hole",
+    R="region",
+    V="verbose",
+    f="coltypes",
+)
 @kwargs_to_strings(R="sequence")
 def grdfill(
     grid: PathLike | xr.DataArray,

pygmt/src/grdlandmask.py

@@ -17,6 +17,7 @@
 @fmt_docstring
 @use_alias(
     A="area_thresh",
+    D="resolution-",
     E="bordervalues",
     I="spacing",
     N="maskvalues",

pygmt/src/meca.py

@@ -123,6 +123,7 @@ def _auto_offset(spec) -> bool:
     L="outline",
     N="no_clip",
     R="region",
+    S="scale/convention/component-",
     T="nodal",
     V="verbose",
     W="pen",

pygmt/src/select.py

@@ -24,6 +24,7 @@
 @use_alias(
     A="area_thresh",
     C="dist2pt",
+    D="resolution-",
     F="polygon",
     G="gridmask",
     I="reverse",

pygmt/src/solar.py

@@ -18,6 +18,7 @@
     G="fill",
     J="projection",
     R="region",
+    T="terminator/terminator_datetime-",
     V="verbose",
     W="pen",
     c="panel",

pygmt/src/ternary.py

@@ -14,6 +14,7 @@
     B="frame",
     C="cmap",
     G="fill",
+    L="alabel/blabel/clabel-",
     JX="width",
     R="region",
     S="style",

pygmt/src/text.py

@@ -27,6 +27,7 @@
     B="frame",
     C="clearance",
     D="offset",
+    F="position/angle/font/justify-",
     G="fill",
     N="no_clip",
     V="verbose",