Remote datasets: Include images of the official documentation in API reference

[yvonnefroehlich]

Description of proposed changes

This PR aims to include images of the remote datasets in the API reference by adding the links to the images showen at https://www.generic-mapping-tools.org/remote-datasets/.

Fixes #2325

Preview:

• https://pygmt-dev--2728.org.readthedocs.build/en/2728/api/index.html#datasets
• https://pygmt-dev--2728.org.readthedocs.build/en/2728/api/generated/pygmt.datasets.load_earth_magnetic_anomaly.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.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

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

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[yvonnefroehlich]

Some questions:

• For now, I placed the images just above the Parameters section. Or do people prefer another position? Maybe above the Refer to xyz sentence?
• There are two magnetic datasets: EMAG2 (https://www.generic-mapping-tools.org/remote-datasets/earth-mag.html) and WDMAM (https://www.generic-mapping-tools.org/remote-datasets/earth-wdmam.html). Do we want to add both figures side by side in a tabular manner?
• Do we also want to add the image for earth_mask (https://www.generic-mapping-tools.org/remote-datasets/earth-mask.html) even though the used categorical colormap is not defined as a GMT default colormap?

[seisman]

• For now, I placed the images just above the Parameters section. Or do people prefer another position? Maybe above the Refer to xyz sentence?

I prefer to put the images at the top, just below the "Load xxx dataset in various resolutions" sentence, because the images are more eye-catching than the long description.

I also prefer to make the images slightly smaller. I usually use a relative width like width: 80% which is 80% of the content width rather than an absolute width like width: 700px.

• There are two magnetic datasets: EMAG2 (https://www.generic-mapping-tools.org/remote-datasets/earth-mag.html) and WDMAM (https://www.generic-mapping-tools.org/remote-datasets/earth-wdmam.html). Do we want to add both figures side by side in a tabular manner?

They look quite different in some places. A side-by-side table sounds a good idea.

• Do we also want to add the image for earth_mask (https://www.generic-mapping-tools.org/remote-datasets/earth-mask.html) even though the used categorical colormap is not defined as a GMT default colormap?

I think the colormap really doesn't matter much for earth_mask.
Unlike other images, the earth_mask image has a frame and annotations, which doesn't look good. I think we should open an upstream issue to fix it.

[yvonnefroehlich]

I prefer to put the images at the top, just below the "Load xxx dataset in various resolutions" sentence, because the images are more eye-catching than the long description.

That's fine with me and is done in commit fdfa599.

I also prefer to make the images slightly smaller. I usually use a relative width like width: 80% which is 80% of the content width rather than an absolute width like width: 700px.

Using a relative width is also fine with me.
However, there seem to be no big difference in the size of the images between using 700 px and 80 %.
Update: I changed the remaining images to use a relative width in commit 8c0b986.

• There are two magnetic datasets: EMAG2 (https://www.generic-mapping-tools.org/remote-datasets/earth-mag.html) and WDMAM (https://www.generic-mapping-tools.org/remote-datasets/earth-wdmam.html). Do we want to add both figures side by side in a tabular manner?

They look quite different in some places. A side-by-side table sounds a good idea.

A table containing the images for the magnetic datasets is added in commits 111b0c1, 9fb1f13, and 8399c28.

• Do we also want to add the image for earth_mask (https://www.generic-mapping-tools.org/remote-datasets/earth-mask.html) even though the used categorical colormap is not defined as a GMT default colormap?

I think the colormap really doesn't matter much for earth_mask. Unlike other images, the earth_mask image has a frame and annotations, which doesn't look good. I think we should open an upstream issue to fix it.

Yeah, I was also wondering about the annotated frame and think this image should be consistent with the images for the other datasets.

[seisman]

The following warning is from pylint:

pygmt/datasets/earth_magnetic_anomaly.py:30:0: C0301: Line too long (102/100) (line-too-long)

and the following warning is from pycodestyle:

pygmt/datasets/earth_magnetic_anomaly.py:28:80: W505 doc line too long (119 > 79 characters) [pycodestyle]

It seems we have two tools that check line length. Maybe we should disable one?

BTW, the following code can disable both warnings but itself is too long:

# pylint: disable=line-too-long # noqa: W505

[yvonnefroehlich]

The following warning is from pylint:

pygmt/datasets/earth_magnetic_anomaly.py:30:0: C0301: Line too long (102/100) (line-too-long)

and the following warning is from pycodestyle:

pygmt/datasets/earth_magnetic_anomaly.py:28:80: W505 doc line too long (119 > 79 characters) [pycodestyle]

It seems we have two tools that check line length. Maybe we should disable one?

BTW, the following code can disable both warnings but itself is too long:

# pylint: disable=line-too-long # noqa: W505

If we us a tool setting a limit of < 79 signs, I do not see the need or sense of having an additional tool for checking for < 100 signs. So, if we would decide to not use pylint's limit < 100 anymore, we would only have the limit < 79 from pycodestyle and this warning could be disabled via # noqa: W505. Then it should be possible to have the link in one line, correct?

[yvonnefroehlich]

• Do we also want to add the image for earth_mask (https://www.generic-mapping-tools.org/remote-datasets/earth-mask.html) even though the used categorical colormap is not defined as a GMT default colormap?

I think the colormap really doesn't matter much for earth_mask. Unlike other images, the earth_mask image has a frame and annotations, which doesn't look good. I think we should open an upstream issue to fix it.

Yeah, I was also wondering about the annotated frame and think this image should be consistent with the images for the other datasets.

I opened an issue regarding removing the annotated fancy frame at GenericMappingTools/remote-datasets#83.

[seisman]

The following warning is from pylint:

pygmt/datasets/earth_magnetic_anomaly.py:30:0: C0301: Line too long (102/100) (line-too-long)

and the following warning is from pycodestyle:

pygmt/datasets/earth_magnetic_anomaly.py:28:80: W505 doc line too long (119 > 79 characters) [pycodestyle]

It seems we have two tools that check line length. Maybe we should disable one?
BTW, the following code can disable both warnings but itself is too long:

# pylint: disable=line-too-long # noqa: W505

If we us a tool setting a limit of < 79 signs, I do not see the need or sense of having an additional tool for checking for < 100 signs. So, if we would decide to not use pylint's limit < 100 anymore, we would only have the limit < 79 from pycodestyle and this warning could be disabled via # noqa: W505. Then it should be possible to have the link in one line, correct?

Done in PR #2735.

[seisman]

PR #2735 has been merged, now it's possible to write like:

.. figure:: https://long/path/to/image.png # noqa: W505

[seisman]

@yvonnefroehlich See GenericMappingTools/remote-datasets#89 for the upstream changes of image names.