Intersphinx cross-referencing does not work naively

[leofang]

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]

cc @steff456

[rgommers]

We should fix this, the signatures part should be removed.

[steff456]

I've been trying to fix this issue without major luck. I'll give it another check to see if I can remove the signatures and also shorten the amount of writing in a cross reference.

[asmeurer]

Why don't we just rename signatures to array_api?

[leofang]

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

[leofang]

@kgryte Is there a way we can "backport" the fix #430 to v2021? It only fixed the draft version but not the latest (or 2021.12) version. Try comparing the outputs and you'll see:

python -m sphinx.ext.intersphinx https://data-apis.org/array-api/draft/objects.inv
python -m sphinx.ext.intersphinx https://data-apis.org/array-api/latest/objects.inv
python -m sphinx.ext.intersphinx https://data-apis.org/array-api/2021.12/objects.inv

[kgryte]

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

[rgommers]

I believe this was fixed, the intersphinx content seems consistent across all versions and signatures isn't present:

% python -m sphinx.ext.intersphinx https://data-apis.org/array-api/2022.12/objects.inv | rg arange
	array_api.arange                         API_specification/generated/array_api.arange.html#array_api.arange
	API_specification/generated/array_api.arange arange                                  : API_specification/generated/array_api.arange.html

% python -m sphinx.ext.intersphinx https://data-apis.org/array-api/2021.12/objects.inv | rg arange
	array_api.arange                         API_specification/generated/array_api.arange.html#array_api.arange
	API_specification/generated/array_api.arange arange                                  : API_specification/generated/array_api.arange.html

% python -m sphinx.ext.intersphinx https://data-apis.org/array-api/latest/objects.inv | rg arange
	array_api.arange                         API_specification/generated/array_api.arange.html#array_api.arange
	API_specification/generated/array_api.arange arange                                  : API_specification/generated/array_api.arange.html

% python -m sphinx.ext.intersphinx https://data-apis.org/array-api/draft/objects.inv | rg arange
	array_api.arange                         API_specification/generated/array_api.arange.html#array_api.arange
	API_specification/generated/array_api.arange arange                                  : API_specification/generated/array_api.arange.html

So I'll close this - thanks all!