Hyperlink to parameters in docstrings using sphinx-paramlinks

[weiji14]

Description of the desired feature

To make it easier to reference the parameters of PyGMT functions (e.g. pen in plot), here's an idea to make all those parameters clickable with a permalink! This can be done using sphinx-paramlinks.

Pros:

• Can directly reference a parameter now using e.g. https://pygmt-dev--2131.org.readthedocs.build/en/2131/api/generated/pygmt.Figure.plot.html#pygmt.Figure.plot.params.pen

Cons:

• Huge maintenance burden to rewrite all the docstrings to use the :paramref: directive
• May or may not make it harder for new contributors to write docstrings when wrapping a new module
• The sphinx-paramlinks extension doesn't look well maintained (last commit 31 May 2022), though there are supposedly 300+ users

There's a proof of concept PR at #2131 to show how the implementation looks like.

Are you willing to help implement and maintain this feature? Discuss on whether the pain is worth it :slightly_smiling_face:

Vote :+1: for yes, :-1: for no

If we do go ahead, the concrete steps would be to:

• [ ] Add sphinx-paramlinks package to conda-forge (optional, but nice to have)
• [ ] Update coding standards at https://github.com/GenericMappingTools/pygmt/blob/v0.7.0/doc/contributing.md#standards-for-example-code
• [ ] <insert long list of PyGMT functions whose docstrings need to be rewriten>

[seisman]

Looks great!

[maxrjones]

I like the look as well but am hesitant to rely on an experimental extension that would require a fair amount of work to drop.

[seisman]

I'm closing the issue as the sphinx-paramlinks extension is not actively maintained. The latest tag (https://github.com/sqlalchemyorg/sphinx-paramlinks/tags) was created one year ago and there is only one commit in the recent year.

Feel free to reopen it if there are any more updates on the extension or any new ideas.