Consistently list all common options alphabetically at the end of docstrings

[seisman]

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.

[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.

[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.