Intersphinx cross-referencing does not work naively

I am improving CuPy’s documentation and hit this issue…

Let’s say I want to reference arange from the array API. Ideally, I would expect this should work out of box:

# conf.py
# ...
intersphinx_mapping = {
    ...
    'array_api': ('https://data-apis.org/array-api/2021.12/', None),
    ...
}
# ...

and in anywhere (rst files or docstrings) I could just do

:func:`array_api.arange`

to link to arange. Unfortunately, this does not work, nor does the global version (removing the array_api prefix). Instead I must do this following due to this repo’s structure:

:func:`signatures.creation_functions.arange`

This is quite confusing and counter-intuitive. I could work with it, but I am wondering if we could do better, say re-organizing the Python stub files such that array_api.arange works, so opening this issue to collect feedbacks and suggestions.

[kgryte]

@leofang Yes, this should be possible. Will see what I can do.

[leofang]

Also in __init__.py we need to import all functions to provide a flat namespace (except for the extension modules).