DOC: Improve link to the GMT documentation

[seisman]

Address #3881.

For comparison:

• Old version: https://www.pygmt.org/v0.15.0/api/generated/pygmt.grdfill.html
• New version: https://pygmt-dev--3944.org.readthedocs.build/en/3944/api/generated/pygmt.grdfill.html

Old	New version 1
New version 2	New version 3

[seisman]

I'll apply the same changes to other wrappers if approved.

[yvonnefroehlich]

For me this change looks good in the docs.

[seisman]

Ping @michaelgrund and @weiji14 for comments before I make changes.

Actually, I'd still like to rephrase the sentence so the links appear on one line, but I haven’t found a good solution yet.

[yvonnefroehlich]

Hm. If it should fit into one line, maye we can put the link to the docs within the grdfill.
Not sure, if the link works in this way or the full URL is required.

Suggested change

	.. note::
	Wraps the GMT module ``grdfill``.
	The GMT documentation is at :gmt-docs:`grdfill.html`.
	.. note::
	Wraps the GMT module [``grdfill``](:gmt-docs:`grdfill.html`).

[seisman]

I'm not sure if your solution works, but the one below is shorter and should work. This way, the URL isn't explicitly shown, so readers might not realize that it links to the GMT documentation. Is it OK?

Suggested change

	.. note::
	Wraps the GMT module ``grdfill``.
	The GMT documentation is at :gmt-docs:`grdfill.html`.
	Wraps the GMT module :gmt-docs:`grdfill <grdfill.html>`.

[weiji14]

The note:: admonition stands out a bit too much. Perhaps just reword Full option list at ... to Full GMT docs at ..., similar to @ezevazquez's suggestion at #3881 (comment)?

[seisman]

The note:: admonition stands out a bit too much.

I agree.

Perhaps just reword Full option list at ... to Full GMT docs at ...

I prefer to explicitly mention the name of the GMT module, since the function/method names may differ from the module names. What about the one below?

[weiji14]

since the function/method names may differ from the module names

I thought we usually use the same method name as upstream GMT? Different ones I can find are:

• https://www.pygmt.org/v0.15.0/api/generated/pygmt.Figure.set_panel.html (upstream uses gmt subplot set), and that page is missing the upstream doc link btw.
• https://www.pygmt.org/dev/api/generated/pygmt.which.html#pygmt.which (upstream uses gmtwhich)

The names seem to follow closely enough that we don't need to repeat the name really.

[seisman]

We have methods like hlines/vlines and will have methods like scatter (#3602 ) and choropleth (#2798), which wrap plot. I guess we still need to link to plot in these methods.

[weiji14]

We have methods like hlines/vlines and will have methods like scatter (#3602 ) and choropleth (#2798), which wrap plot. I guess we still need to link to plot in these methods.

For those convenience methods, then yes, it makes sense to use "Wraps GMT module scatter, with full docs at :gmt-docs:plot.html". But for most other ones, probably ok to use just "Full GMT docs at ..."?

[seisman]

OK. I've changed it to "Full GMT docs at ...". Will apply the same changes to other files when getting at least two approvals.

Edit: I've applied the changes to all files.