Document conventions for ordering aliases and arguments in contributing.md

[maxrjones]

Description of the desired feature

Most of the PyGMT modules order aliases and arguments alphabetically by the GMT short option. I think it would be helpful to add this convention (if it is decided) to the contributing guidelines under example code standards.

Are you willing to help implement and maintain this feature? Yes

[maxrjones]

I did not find a conversation that settled on this convention in a quick search of past issues (apologies if I missed this). While alphabetically by short option is easily readable for the aliases section of the docs, I actually think that it makes it hard to find things in the parameters section. I would find it easier to read the docs if parameters was alphabetically by alias/long-option.

[weiji14]

I did not find a conversation that settled on this convention in a quick search of past issues (apologies if I missed this).

Yes, things are a bit inconsistent, and I don't think we've spelt this out in any previous issue, so thanks for raising this to our attention!

While alphabetically by short option is easily readable for the aliases section of the docs

Agree on this, I think the code line at

pygmt/pygmt/helpers/decorators.py

Line 206 in 805f533

for arg in sorted(module_func.aliases):

sorts things under the "Aliases:" section.

... I actually think that it makes it hard to find things in the parameters section. I would find it easier to read the docs if parameters was alphabetically by alias/long-option.

We can discuss a bit more about sorting alphabetically. A couple of points to consider:

• Required arguments should come first (e.g. x/y/z in pygmt.surface shouldn't be placed near the end).
• There are some modules where we use common_options (those with {V}, {XY}, {c}, {p}, {t} etc). These are usually not so important arguments. How do we want to sort those? Keep them at the end or sort them alphabetically in line with the rest? E.g. colorbar:

  pygmt/pygmt/src/colorbar.py

  Lines 98 to 102 in 805f533

  	{V}
  	{XY}
  	{c}
  	{p}
  	{t}

Of course, it's hard for someone starting out to know what is 'important' or not (i.e. very subjective). So maybe we can find a balance somehow so that new users can jump in without having to familiarize themselves too much with the GMT world.

[willschlitzer]

Should we add a separate section in contributing.md about writing the docstrings for a module (where this ordering convention would go)?

[maxrjones]

Should we add a separate section in contributing.md about writing the docstrings for a module (where this ordering convention would go)?

I'm part-way through adding a section with general instructions for wrapping a module (https://github.com/GenericMappingTools/pygmt/commits/wrap-module-instructions). That would be a good place to put the convention, but I will not include them in the PR from that branch so that any necessary discussion could happen separately.

[yvonnefroehlich]

I think the list of aliases is mainly relevant for PyGMT users coming from GMT. To easily find the alias corresponding to a single letter, an alphabetical order is helpful.

About the order within the parameter section, I have to think in more detail. So far, I would say the required parameters should be listed at the beginning.