WIP: Add inline example for pygmt.datasets.list_sample_data

[maxrjones]

Description of proposed changes

This PR adds an inline example for pygmt.datasets.list_sample_data. It is a possible solution to #1774 and would be easier to maintain than table/list in the docstring since the output from the example could be easily updated.

It is listed as WIP because the style checks fail with line-too-long errors.

Addresses #1774

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 commands are:

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

[willschlitzer]

Should this list only 2-3 dataset names, and maybe use ... to indicate that this is an incomplete list? I don't want users to think the output in the example is the complete list.

   {'bathymetry': 'Table of ship bathymetric observations off Baja California',
    'fractures': 'Table of hypothetical fracture lengths and azimuths',
   ...
    'usgs_quakes': 'Table of global earthquakes from the USGS'}

[seisman]

See #1774. The idea of this PR is to better document the available sample data.

[maxrjones]

Yeah, the goal is to document the complete list. Not sure if this is the best way to do that though, I'm open to other ideas.

[seisman]

I still prefer a list in the load_sample_data function. The reasons are:

1. It's more likely that people will read the documentation of load_sample_data first, then realize that they need to read the list_sample_data documentation to know what datasets are available
2. Because the maximum length is 79 (or 80) for docstrings, a long description for a dataset must be split into two lines (e.g., description for mars_shape), otherwise the style check fails.

[maxrjones]

Are you proposing deprecating list_sample_data?

[seisman]

No, list_sample_data is still useful to show the available datasets in interactive presentations.

[maxrjones]

Superseded by #2342