Standardize parameter ordering in function signature and docstrings for common options

[Copilot]

Parameter ordering was inconsistent across PyGMT functions, with common parameters appearing in different sequences in different files. This created cognitive overhead when navigating the codebase and made the API harder to learn.

Changes

Established canonical ordering:

• Uppercase: projection → zscale → zsize → region → frame → verbose
• Lowercase: alphabetically by GMT flag (a, b, c, d, e, f, g, h, i, l, n, o, p, r, s, t, w)

Updated 29 files:

• Function signatures: reordered parameters to match canonical sequence
• Docstrings: moved common parameters to end, ordered canonically
• Special case: basemap.py keeps projection/region/frame at start (primary parameters)

Example

Before:

def plot(
    projection: str | None = None,
    frame: str | bool = False,          # wrong position
    region: str | None = None,
    verbose: bool = False,
    transparency: float | None = None,  # t before p
    perspective: float | bool = False,
):

After:

def plot(
    projection: str | None = None,
    region: str | None = None,
    frame: str | bool = False,          # ✓
    verbose: bool = False,
    panel: int | bool = False,          # c
    perspective: float | bool = False,  # p
    transparency: float | None = None,  # t ✓
):

All 57 files with common parameters now follow canonical ordering.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Consistently list all common options alphabetically at the end of docstrings</issue_title>
<issue_description>GMT modules share many common options (e.g., -J, -R), and most PyGMT methods/functions provide corresponding common aliases (e.g., projection, region). At present, these aliases are listed inconsistently in docstrings and are often placed at the very beginning. I believe it would make more sense to group them at the end instead.

The reasons are:

• Upper-case GMT options (-B, -J, -R, -V) are not central to most individual modules. In typical plotting workflows, only the first plotting command needs to specify -J, -R, and -B.
• Users are generally already familiar with these common options and are more interested in learning about the parameters that are unique to a given function or method.

So, I propose the following:

• List all common options alphabetically at the end of docstrings, rather than interleaving them with module-specific parameters.
• Add a dedicated subsection (e.g., “Common Parameters”) to clearly separate shared options from parameters that are unique to each function or method. [Depending on if it looks better or worse]

This structure would improve readability, make docstrings more consistent across PyGMT, and help users focus on the parameters that matter most for a given module.
</issue_description>

<agent_instructions>There is already a PR #4286. Can you continue that PR?
</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@yvonnefroehlich > List all common options alphabetically at the end of docstrings, rather than interleaving them with module-specific parameters.

Agree on having a more consistent structure for the alias list, with focus on the function / method specific aliases and placing those at the beginning. For me it sounds good to group the common options and add them at the end.

Add a dedicated subsection (e.g., “Common Parameters”) to clearly separate shared options from parameters that are unique to each function or method. [Depending on if it looks better or worse]

we can just try it with one method and see how it looks.

@seisman > > Add a dedicated subsection (e.g., “Common Parameters”) to clearly separate shared options from parameters that are unique to each function or method. [Depending on if it looks better or worse] > > we can just try it with one method and see how it looks.

I've tried in PR #4286. It works well, but the type hints are not shown correctly.

</comment_new>
<comment_new>@seisman
For uppercase option flags, sorting the aliases by their corresponding single-letter option flags would give the order frame (-B), projection (-J), region (-R), and verbose (-V). However, I find it more intuitive to order them as projection (plus zscale/zsize for some methods), region, frame, and verbose.

I would suggest projection->region->frame->verbose for these uppercase option flags, and sort other common parameters by the alphabetical order of their corresponding lowercase option flags.

• Fixes Consistently list all common options alphabetically at the end of docstrings #4285

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.