TYP: Add type hints and improve docstrings of load_tile_map function

[seisman]

Preview: https://pygmt-dev--3087.org.readthedocs.build/en/3087/api/generated/pygmt.datasets.load_tile_map.html#pygmt.datasets.load_tile_map

[yvonnefroehlich]

Now there are two sections, Return type and Returns, and the returned object is written in italic instead of bold style. I personally prefer the current documentation version, as I think the returned object and its data type should be stated together (analogous to the parameters).

current docs	updated docs

[seisman]

Need to check if sphinx-autodoc-typehint provides an option to control the behavior. https://github.com/tox-dev/sphinx-autodoc-typehints#options

[seisman]

I don't think sphinx-autodoc-typehint provides such an option, so there is little we can do unless we decide not to add type hints for the return values.

[weiji14]

There was a napoleon_use_rtype = True option that was tried in #937. Does it work here, or is that what sphinx-autodoc-typehint is using?

[weiji14]

Can you try napoleon_preprocess_types = True as suggested at sphinx-doc/sphinx#9394?

[seisman]

napoleon_use_rtype = True incorrectly parses raster as the return type:

napoleon_preprocess_types = True and napoleon_use_rtype = False is not bad:

[seisman]

https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_preprocess_types

napoleon_preprocess_types
True to convert the type definitions in the docstrings as references. Defaults to False.

When setting napoleon_preprocess_types = True, raster is parsed as type definitions, so it's rendered the same way as the return type DataArray. Strictly speaking, it's still incorrect.

Actually, the name of the returned value should not appear in the NumPy-style docstrings (see https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy). I.e., we should change

    Returns
    -------
    raster
        Georeferenced 3-D data array of RGB values.

to

    Returns
    -------
        Georeferenced 3-D data array of RGB values.

[weiji14]

Actually, the name of the returned value should not appear in the NumPy-style docstrings (see https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy). I.e., we should change

It looks like they are using something like

    Returns
    -------
    xr.DataArray
        Georeferenced 3-D data array of RGB values.

[seisman]

That version doesn't have type hints for the return value.

[seisman]

Some related discussions:

• automatic type inference for napoleon numpy style sphinx-doc/sphinx#7077
• Fix napoleon handling of numpy docstrings with no explicitly provided return type tox-dev/sphinx-autodoc-typehints#311
• Support type annotations in Returns and Yields sections numpy/numpydoc#356

[seisman]

I'm merging this PR. The style issue of the function return value/type should be addressed separately (if there is a good solution).