intersphinx looks for implementation modules

This is a widespread issue caused by the pattern of defining objects in private module and then exposing them to the final user by importing them in the top-level __init__.py, vs. how intersphinx works.

Exact same issue in different projects:

• https://github.com/aio-libs/aiohttp/issues/3714
• https://jira.mongodb.org/browse/MOTOR-338
• https://github.com/tkem/cachetools/issues/178
• https://github.com/AmphoraInc/xarray_mongodb/pull/22
• https://github.com/jonathanslenders/asyncio-redis/issues/143

If a project

1. uses xarray, intersphinx, and autodoc
2. subclasses any of the classes exposed by xarray/__init__.py and documents the new class with the :show-inheritance: flag
3. Starting from Sphinx 3, has any of the above classes anywhere in a type annotation

Then Sphinx emits a warning and fails to create a hyperlink, because intersphinx uses the __module__ attribute to look up the object in objects.inv, but __module__ points to the implementation module while objects.inv points to the top-level xarray module.

Workaround

In conf.py:

import xarray
xarray.DataArray.__module__ = "xarray"

Solution

Put the above hack in xarray/__init__.py

Start in xarray/init.py, where public objects are exposed, and compare that behavior with the conf.py workaround described in the issue. Reproduce the Sphinx intersphinx warning for an affected type annotation and verify that the documented public objects resolve to hyperlinks without the warning.