DOC: Complete list of aliases

[seisman]

Addressing the 2nd point raised in issue #3881.

As we break complex options into multiple parameters, the current alias system no longer works, and the {aliases} placeholder in docstrings can't list these parameters anymore.

In issue #3881, I proposed to remove the list of aliases if the documentation on the PyGMT side is complete, but it seems people are against it, and the reasons sounds fair to me.

So, instead of removing the list of aliases, I guess we need to manually add the missing aliases back to the list.

Preview:

• https://pygmt-dev--3945.org.readthedocs.build/en/3945/api/generated/pygmt.grdfill.html
• https://pygmt-dev--3945.org.readthedocs.build/en/3945/api/generated/pygmt.grdclip.html

[seisman]

The {aliases} placeholder will be expanded to something like:

.. hlist:: 
   :columns: 3
   
   - R = region
   - J = projection

Currently, the solution is to add the missing aliases below the {aliases} placeholder. Does it look bad? Perhaps we should maintain the full list of aliases manually, i.e., remove the {aliases} placeholder and manually add all aliases.

[seisman]

Perhaps we should maintain the full list of aliases manually, i.e., remove the {aliases} placeholder and manually add all aliases.

See the changes in grdfill.py for another style.

[seisman]

Please see the changes in grdclip.py and grdfill.py for two ways to list the aliases. I guess we need to vote.

🚀 for the style in grdclip, ❤️ for the style in grdfill, or leave your comments about other solutions.

[seisman]

Ping @GenericMappingTools/pygmt-maintainers again for comments on this since some PRs are waiting for it.

I prefer the pygmt/src/grdfill.py style.

• Pros: Keep aliases sorted alphabetically
• Cons: Need to maintain the alias list manually, but I guess it's mostly a one-time job.