Add a decorator to raise a FutureWarning when positional arguments are passed for functions that changed parameter orders

[seisman]

Description of proposed changes

See #1479 (comment) for discussions.

This PR adds a decorator to raise a warning when the order of parameters are changed and users are passing positional arguments.

Usage:

@fmt_docstring
@deprecate_parameter("sizes", "sizes", "v0.4.0", remove_version="v0.6.0")
@check_data_input_order("v0.5.0", remove_version="v0.7.0")
@use_alias(...)
@kwargs_to_strings(...)
def plot(self, data=None, x=None, y=None, ....):
    pass

Address #1479.

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[seisman]

@GenericMappingTools/pygmt-maintainers Need to review/merge this PR before we can change the order of input parameters (e.g., #1547, #1546).

[michaelgrund]

@GenericMappingTools/pygmt-maintainers Need to review/merge this PR before we can change the order of input parameters (e.g., #1547, #1546).

Sorry, totally overlooked this PR before opening #1547 and #1546.

[michaelgrund]

Looks good to me!

[weiji14]

I realize that this is a temporary decorator, which might not have much use after PyGMT v0.7.0, but should we:

1. Add a usage note for @check_data_input_order at https://github.com/GenericMappingTools/pygmt/blob/main/doc/maintenance.md#backwards-compatibility-and-deprecation-policy
2. Add a note in the docstring of this decorator function to say that this function can be removed after PyGMT v0.7.0?

[seisman]

I realize that this is a temporary decorator, which might not have much use after PyGMT v0.7.0, but should we:

1. Add a usage note for @check_data_input_order at main/doc/maintenance.md#backwards-compatibility-and-deprecation-policy

I prefer not to add the usage, because it's likely that no one will use this decorator again after we finish issue #1479 (definitely before v0.5.0 release).

2. Add a note in the docstring of this decorator function to say that this function can be removed after PyGMT v0.7.0?

Yes, it sounds good.

[weiji14]

Ok to merge once you fix the lint issue. Some whitespace I think.

[seisman]

The decorator works well for non-plotting modules, but doesn't work for plotting modules (e.g., #1548, #1547), because for plotting modules, the first argument is self, thus, the length of the args array is at least 1.

Perhaps we have to check if the function is plotting or non-plotting.