docformatter v1.6.0 is incompatible with black

[seisman]

docformatter v1.6.0 was released a few hours ago, and it breaks our "Style Checks" workflow (e.g., https://github.com/GenericMappingTools/pygmt/actions/runs/4605939608/jobs/8138625848?pr=2474).

There is an existing issue report that docformatter v1.6.0 is incompatible with black (PyCQA/docformatter#94).

Here is an example that docformatter v1.6.0 doesn't work with our codes:

Just run:

$ docformatter --in-place pygmt/helpers/decorators.py

The diff is:

diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py
index 95a3c29db..15cdc527a 100644
--- a/pygmt/helpers/decorators.py
+++ b/pygmt/helpers/decorators.py
@@ -476,7 +476,6 @@ def _insert_alias(module_func, default_value=None):
     """
     Function to insert PyGMT long aliases into the signature of a method.
     """
-
     # Get current signature and parameters
     sig = signature(module_func)
     wrapped_params = list(sig.parameters.values())
@@ -536,12 +535,10 @@ def use_alias(**aliases):
     pygmt.exceptions.GMTInvalidInput:
         Parameters in short-form (J) and long-form (projection) can't coexist.
     """
-
     def alias_decorator(module_func):
         """
         Decorator that replaces the aliases for arguments.
         """
-
         @functools.wraps(module_func)
         def new_module(*args, **kwargs):
             """
@@ -710,7 +707,6 @@ def kwargs_to_strings(**conversions):
         """
         The decorator that creates our new function with the conversions.
         """
-
         @functools.wraps(module_func)
         def new_module(*args, **kwargs):
             """
@@ -791,13 +787,11 @@ def deprecate_parameter(oldname, newname, deprecate_version, remove_version):
     ...     module(data="table.txt", size=5.0, sizes=4.0)
     ...
     """
-
     def deprecator(module_func):
         """
         The decorator that creates the new function to work with both old and
         new parameters.
         """
-
         @functools.wraps(module_func)
         def new_module(*args, **kwargs):
             """

If we run black pygmt/helpers/decorators.py, we will see that black reverts some changes of docformatter. After running black, the diff is:

diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py
index 95a3c29db..49c008932 100644
--- a/pygmt/helpers/decorators.py
+++ b/pygmt/helpers/decorators.py
@@ -476,7 +476,6 @@ def _insert_alias(module_func, default_value=None):
     """
     Function to insert PyGMT long aliases into the signature of a method.
     """
-
     # Get current signature and parameters
     sig = signature(module_func)
     wrapped_params = list(sig.parameters.values())

I think we need to pin docformatter to <1.6.0, agree?

[michaelgrund]

Agree!