Fix unclickable external types in reference API docs

[sfmig]

Describe the bug
In the API docs, some of the types that link to external documentation are missing. This happens when in the docstrings we specify the type without spelling out the full module path, for example:

• np.ndarray rather numpy.ndarray (example)
• xr.DataArray rather than xarray.DataArray (for example here with reference_vector)

Additionally shapely classes and methods are not linkable in the API docs (example - not sure if there are more?)

Additional context
It would be nice to search the API docs for these errors, and fix them to make sure the types are referenced correctly and are clickable.

For shapely, I think we would need to add the relevant URL to the intersphinx_mapping dict in conf.py and use the right syntax (maybe :mod:shapely. Geometry ?)

[Nayan-100]

Hi, I’d like to work on this issue.
Please assign it to me if it’s available. Thanks!

[adamltyson]

Hi @Nayan-100 we typically don't assign issues other than to core developers. If you would like to work on this, please raise a PR and link to this issue. Feel free to reach out here or on Zulip if you have any questions about tackling this.

[lochhh]

We are already using sphinx-autodoc-typehints

movement/docs/requirements.txt

Line 9 in 9811fa9

sphinx-autodoc-typehints

which means we should not need to have the types in the parameter docstrings, as long as the functions are type-hinted. The following example (from https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html), would correctly generate "clickable" external types:

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    The return type must be duplicated in the docstring to comply
    with the NumPy docstring style.

    Parameters
    ----------
    param1
        The first parameter.
    param2
        The second parameter.

    Returns
    -------
    bool
        True if successful, False otherwise.

    """

So the scope for this issue could be changed to adopting the above style instead of correcting the types.

[niksirbi]

which means we should not need to have the types in the parameter docstrings, as long as the functions are type-hinted.

Oh Wow, this is fantastic news @lochhh, I wasn't aware.