DOC: Add gallery example for using EPSG codes

[yvonnefroehlich]

Description of proposed changes

This PR aims to add a gallery example showing the usage of EPSG codes with the projection parameter.
At the moment the example is listed in the gallery under "Maps and map elements"; Edit "Projections".

Fixes #2004

Preview:

• https://pygmt-dev--3973.org.readthedocs.build/en/3973/techref/projections.html
• https://pygmt-dev--3973.org.readthedocs.build/en/3973/projections/index.html#projections
• https://pygmt-dev--3973.org.readthedocs.build/en/3973/projections/epsg/epsg_codes.html

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash command is:

• /format: automatically format and lint the code

[yvonnefroehlich]

Recently building the Docs for windows started failing with:

embedding documentation hyperlinks for projections... [ 97%] polar.html
embedding documentation hyperlinks for projections... [100%] sg_execution_times.html

build succeeded.

The HTML pages are in _build\html.
make: *** [Makefile:35: html] Error 2816
make: Leaving directory 'D:/a/pygmt/pygmt/doc'
Error: Process completed with exit code 2.

[seisman]

Recently building the Docs for windows started failing with:

embedding documentation hyperlinks for projections... [ 97%] polar.html
embedding documentation hyperlinks for projections... [100%] sg_execution_times.html

build succeeded.

The HTML pages are in _build\html.
make: *** [Makefile:35: html] Error 2816
make: Leaving directory 'D:/a/pygmt/pygmt/doc'
Error: Process completed with exit code 2.

Yes, looking at the CI build history at https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_docs.yml?query=branch%3Amain, it started to fail since #3932

[seisman]

What about mentioning EPSG codes on the following two pages: https://pygmt-dev--3973.org.readthedocs.build/en/3973/projections/index.html and https://pygmt-dev--3973.org.readthedocs.build/en/3973/techref/projections.html

[yvonnefroehlich]

/format

[yvonnefroehlich]

/format

[yvonnefroehlich]

What about mentioning EPSG codes on the following two pages: https://pygmt-dev--3973.org.readthedocs.build/en/3973/projections/index.html and https://pygmt-dev--3973.org.readthedocs.build/en/3973/techref/projections.html

Now I moved the EPSG example to the end of the projection gallery, and mention using EPSG codes a the beginning of both projection files.

[seisman]

What about mentioning EPSG codes on the following two pages: https://pygmt-dev--3973.org.readthedocs.build/en/3973/projections/index.html and https://pygmt-dev--3973.org.readthedocs.build/en/3973/techref/projections.html

Now I moved the EPSG example to the end of the projection gallery, and mention using EPSG codes a the beginning of both projection files.

The current documentation gives me the impression that all EPSG codes are supported, but I'm not sure if GMT supports all EPSG codes...

[yvonnefroehlich]

What about mentioning EPSG codes on the following two pages: https://pygmt-dev--3973.org.readthedocs.build/en/3973/projections/index.html and https://pygmt-dev--3973.org.readthedocs.build/en/3973/techref/projections.html

Now I moved the EPSG example to the end of the projection gallery, and mention using EPSG codes a the beginning of both projection files.

The current documentation gives me the impression that all EPSG codes are supported, but I'm not sure if GMT supports all EPSG codes...

Hm. I am also unsure here. Actually, I was hoping to find a table that gives an overview of these EPSG codes...
This is what I found in the GMT docs (https://docs.generic-mapping-tools.org/dev/gmt.html):

Using EPSG codes is also possible. For example -JEPSG:4326 sets the WGS-84 system.

[seisman]

What about mentioning EPSG codes on the following two pages: https://pygmt-dev--3973.org.readthedocs.build/en/3973/projections/index.html and https://pygmt-dev--3973.org.readthedocs.build/en/3973/techref/projections.html

Now I moved the EPSG example to the end of the projection gallery, and mention using EPSG codes a the beginning of both projection files.

The current documentation gives me the impression that all EPSG codes are supported, but I'm not sure if GMT supports all EPSG codes...

Hm. I am also unsure here. Actually, I was hoping to find a table that gives an overview of these EPSG codes... This is what I found in the GMT docs (https://docs.generic-mapping-tools.org/dev/gmt.html):

Using EPSG codes is also possible. For example -JEPSG:4326 sets the WGS-84 system.

It seems only a few EPSG codes are supported. For example, the following command gives nothing:

gmt coast -R90/130/20/50 -JEPSG:4490/10c -Baf -W -Glightblue -pdf map

[seisman]

I prefer to keep this PR unmerged until we figure out which EPSG codes GMT supports.

[yvonnefroehlich]

I prefer to keep this PR unmerged until we figure out which EPSG codes GMT supports.

Agree, this should be clear to the users. No worries, we can move this PR to a later release. Probably we also have to update the upstream GMt docs first.