py:class reference target not found: requests_oauthlib.oauth1_auth.OAuth1

Describe the bug

I'm using the requests_oauthlib package and I am annotating my code with type hints. So, I have a function that returns OAuth1, which is imported. mypy does not complain about it, but when I make the docs I get the error

path.to.my.function:1: WARNING: py:class reference target not found: requests_oauthlib.oauth1_auth.OAuth1

I've tried to add the following intersphinx_mapping, but it doesn't solve the problem.

intersphinx_mapping = {
    ...
    'requests_oauthlib': (
        'https://requests-oauthlib.readthedocs.io/en/v1.3.1',
        None,
    ),
}

Here are the docs for the OAuth1 class: https://requests-oauthlib.readthedocs.io/en/v1.3.1/api.html#oauth-1-0, so I don't get why I am getting this error.

If you also look at the class OAuth1, it's a docstring too.

How to Reproduce

Just create a function that returns OAuth1. Before that, import the class as follows from requests_oauthlib import OAuth1 (or from requests_oauthlib.oauth1_auth import OAuth1 - it doesn't matter). See below for the packages that I have installed. Python 3.8.13

@property
def function(self) -> OAuth1:
    return OAuth1(...)

Environment Information

requests-oauthlib             1.3.1      OAuthlib authentication support for Requests.
...
sphinx                        5.3.0      Python documentation generator
sphinx-autodoc-typehints      1.23.0     Type hints (PEP 484) support for the Sphinx autodoc extension
sphinx-rtd-theme              1.2.2      Read the Docs theme for Sphinx
sphinxcontrib-applehelp       1.0.2      sphinxcontrib-applehelp is a sphinx extension which outputs Apple help books
sphinxcontrib-devhelp         1.0.2      sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp document.
sphinxcontrib-htmlhelp        2.0.0      sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files
sphinxcontrib-jquery          4.1        Extension to include jQuery on newer Sphinx releases
sphinxcontrib-jsmath          1.0.1      A sphinx extension which renders display math in HTML via JavaScript
sphinxcontrib-qthelp          1.0.3      sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp document.
sphinxcontrib-serializinghtml 1.1.5      sphinxcontrib-serializinghtml is a sphinx extension which outputs "serialized" HTML files (json and pickle).

Sphinx extensions

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.intersphinx',
    'sphinx.ext.autosectionlabel',
    'sphinx_autodoc_typehints',
]

Additional context

No response

Ah yes, I know of this issue. I've also stumbled upon this kind of issue when using my local sources. Here, the reference Sphinx is trying is requests_oauthlib.oauth1_auth.OAuth1. However, the intersphinx mappings actually contains only the entry requests_oauthlib.OAuth1 probably because it's been exported from the requests_oauthlib.oauth1_authmodule. I think we have similar issues when importing return type annotations in a if TYPE_CHECKING block by the way (but not sure whether it's an issue on master).

The way I fixed this is by defining which reference should be resolved to which "real" item and used a SphinxPostTransform for that. I am pretty sure that this issue is already reported amongst the 1k2 opened issues (if not I'd be very surprised) but we'll need to do something for that. I know that I've commented something on that topic some months ago as well related to the way that warned references are emitted.

EDIT: I self-assigned the issue but I don't think I'll be able to fix it soon (or as a matter of fact, the whole issue with autodoc + non-trivial imports). I think the PR adding canonical names to every autodoc RST generated content may fix this but I am not entirely sure.

sphinx-doc / sphinx