more than one target found for cross-reference warning appeared after upgrading to sphinx==5.2.3 and sphinx-autoapi>=2.0.0

[SamWilsn]

Hey! Our build is popping up a new warning after upgrading to the latest sphinx and autoapi.

/home/sam/Code/specs/autoapi_mre/doc/autoapi/file3/index.rst:33:more than one target found for cross-reference 'Transaction': file1.Transaction, file2.Transaction

Here's the setup:

file1.py

class Transaction:
    pass

file2.py

class Transaction:
    pass

file3.py

from typing import Union

Transaction = Union[int, str]


def foo(x: Transaction):
    pass

conf.py

project = "MRE"
copyright = "2021, Foo"
author = "Foo"

extensions = [
    "autoapi.extension",
]

autoapi_type = "python"
autoapi_dirs = ["../mre"]

templates_path = ["_templates"]

highlight_language = "python3"

add_module_names = False

autodoc_typehints = "signature"

exclude_patterns = []

html_theme = "alabaster"
html_static_path = []

Repro

You can find the whole repro here: https://github.com/SamWilsn/autoapi-mre

Build with: tox -e doc.

[AWhetter]

Thank you so much for providing a reproducible case. This helped greatly.

The issue here is partly AutoAPI's fault and partly Sphinx's.
AutoAPI documents file3 something like this:

.. py:data:: Transaction

.. py:function:: foo(x: Transaction)

However xrefs in a type annotation can only be resolved to a class (https://github.com/sphinx-doc/sphinx/blob/d3c91f951255c6729a53e38c895ddc0af036b5b9/sphinx/domains/python.py#L105-L257). So Sphinx then tries to resolve the xref in foos signature to one of the classes define in file1 or file2.

However there's no correct way to document a type alias currently (sphinx-doc/sphinx#7896). So while AutoAPI could document the type alias as a class to get the xref to resolve, it's not really correct to do so. Really we should get a type alias directive added to Sphinx so that we can document type aliases correctly.