Expand documentation linking in CONTRIBUTING.md

[willschlitzer]

This PR adds an explanation for linking PyGMT methods and GMT documentation using the Sphinx build in the contributing guide.

[willschlitzer]

I regularly find myself having to look through files I've previously worked on to remind myself how to link to PyGMT and GMT pages, and think it is used enough to be added to the contributing guide. A few questions before I mark this ready for review:

1. How do I link to a generic PyGMT documentation (such as a tutorial or gallery page) page in the Sphinx build? I would like to include that as well.
2. Should the contributing guide include some examples of links? Someone may be confused by how to modify something like :class:package.module.class to be usable, but understand that something like :meth:pygmt.Figure.grdcontour links to grdconour and only requires minor modification to link to where they want.

[michaelgrund]

I regularly find myself having to look through files I've previously worked on to remind myself how to link to PyGMT and GMT pages, and think it is used enough to be added to the contributing guide. A few questions before I mark this ready for review:

1. How do I link to a generic PyGMT documentation (such as a tutorial or gallery page) page in the Sphinx build? I would like to include that as well.

2. Should the contributing guide include some examples of links? Someone may be confused by how to modify something like `` :class:`package.module.class` `` to be usable, but understand that something like `` :meth:`pygmt.Figure.grdcontour` `` links to grdconour and only requires minor modification to link to where they want.

Great idea, recently came exactly across the issues you mentioned @willschlitzer , especially how to format links that they are displayed correctly (or really point to the desired page/subpoint).

[seisman]

@willschlitzer This PR looks good. Is it ready for review (and merge)?

[willschlitzer]

@seisman How do I link to other pygmt pages in the same way we can link to GMT docs? I know you've told me in the past, but I was going through old PRs and couldn't find it.

Also, I think the contributing guide should have example links in addition to the formats; do you think that's a good idea?

[seisman]

How do I link to other pygmt pages in the same way we can link to GMT docs? I know you've told me in the past, but I was going through old PRs and couldn't find it.

You can link to a file, using

:doc:`Any Link Text </path/to/the/file>`

For example, :doc:Install instructions </install> links to https://www.pygmt.org/dev/install.html

I think the contributing guide should have example links in addition to the formats; do you think that's a good idea?

Yes, that would be better.

[seisman]

@willschlitzer Don't forget @weiji14's #802 (comment)

There's also :gmt-term: linking to gmt.conf. See e.g.

pygmt/pygmt/mathops.py

Line 50 in 2aa4aab

:gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` from the

[seisman]

See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-syntax

If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text.

We're not using ~ in the documentation. Is it useful? If it is, we should also document it.

[vercel]

@willschlitzer is attempting to deploy a commit to the Generic Mapping Tools Team on Vercel.

A member of the Team first needs to authorize it.