Type annotations appearing as invalid cross-reference

[zaneselvans]

Describe the bug

After upgrading from Sphinx 8.2.3 to 9.0.4 my documentation build started showing warnings like these:

/Users/zane/code/catalyst/pudl/docs/autoapi/pudl/extract/extractor/index.rst:270: WARNING: more than one target found for cross-reference 'type': pudl.metadata.classes.Field.type, pudl.metadata.descriptions.ResourceTrait.type [ref.python]
/Users/zane/code/catalyst/pudl/docs/autoapi/pudl/extract/extractor/index.rst:285: WARNING: more than one target found for cross-reference 'type': pudl.metadata.classes.Field.type, pudl.metadata.descriptions.ResourceTrait.type [ref.python]
/Users/zane/code/catalyst/pudl/docs/autoapi/pudl/helpers/index.rst:1087: WARNING: more than one target found for cross-reference 'type': pudl.metadata.classes.Field.type, pudl.metadata.descriptions.ResourceTrait.type [ref.python]
/Users/zane/code/catalyst/pudl/docs/autoapi/pudl/metadata/classes/index.rst:408: WARNING: more than one target found for cross-reference 'type': pudl.metadata.classes.Field.type, pudl.metadata.descriptions.ResourceTrait.type [ref.python]
/Users/zane/code/catalyst/pudl/docs/autoapi/pudl/metadata/constants/index.rst:51: WARNING: more than one target found for cross-reference 'type': pudl.metadata.classes.Field.type, pudl.metadata.descriptions.ResourceTrait.type [ref.python]
/Users/zane/code/catalyst/pudl/docs/autoapi/pudl/metadata/constants/index.rst:56: WARNING: more than one target found for cross-reference 'type': pudl.metadata.classes.Field.type, pudl.metadata.descriptions.ResourceTrait.type [ref.python]
/Users/zane/code/catalyst/pudl/docs/autoapi/pudl/transform/ferc1/index.rst:3953: WARNING: more than one target found for cross-reference 'type': pudl.metadata.classes.Field.type, pudl.metadata.descriptions.ResourceTrait.type [ref.python]

All of the instances where the warnings are coming up seem to be cases where there's a type annotation in a function definition like type[GenericType] e.g. in factory functions. And then I just happen to have another completely unrelated class Field with an attribute type that is somehow getting tangled up with the type annotations.

The problem comes up while the API documentation is being built by sphinx-autoapi. I don't know whether this is really a Sphinx issue, or if it's a sphinx-autoapi issue, but it works fine on Sphinx 8.2.3 and fails on 9.0.4, so it seems to be coming up now because of a change in Sphinx, and I see there's a lot of other API documentation changes happening now so I thought I'd report it.

How to Reproduce

Code and configuration that can reproduce the behavior...

__init__.py module to be documented

"""Minimal package to reproduce Sphinx type annotation bug."""

from typing import Literal


class Field:
    """A class with a 'type' attribute."""
    
    type: Literal["string", "integer", "boolean"]
    """The data type of this field."""
    
    def __init__(self, type: str):
        self.type = type


class ResourceTrait:
    """Another class with a 'type' attribute."""
    
    type: str
    """Category code for this trait."""
    
    def __init__(self, type: str):
        self.type = type


class GenericExtractor:
    """Base class for extractors."""
    
    def extract(self):
        """Extract data."""
        pass


def factory_function(extractor_cls: type[GenericExtractor], name: str) -> object:
    """A factory function that takes a class as parameter.
    
    Args:
        extractor_cls: Class of type GenericExtractor used to extract data.
        name: Name of the dataset.
    
    Returns:
        An instance of the extractor.
    """
    return extractor_cls()

conf.py Sphinx config

"""Minimal Sphinx configuration to reproduce the bug."""

import sys
from pathlib import Path

# Add the src directory to the path
sys.path.insert(0, str(Path(__file__).parent.parent / "src"))

project = "Sphinx Type Bug Reproducer"
extensions = [
    "autoapi.extension",
]

# AutoAPI configuration
autoapi_type = "python"
autoapi_dirs = ["../src/mypackage"]
autoapi_keep_files = True

html_theme = "alabaster"

index.rst

Sphinx Type Bug Reproducer
==========================

This minimal example demonstrates a bug in Sphinx 9.0 where ``type[ClassName]``
annotations in function signatures are incorrectly treated as cross-references
to class attributes also named ``type``.

The warning appears when:

1. Multiple classes have an attribute named ``type`` (e.g., ``Field.type``, ``ResourceTrait.type``)
2. A function uses Python's built-in ``type`` in a type annotation like ``type[GenericExtractor]``
3. Sphinx tries to resolve ``type`` as a cross-reference and finds multiple targets

Expected behavior: Sphinx should recognize that ``type[ClassName]`` is Python's
built-in type syntax, not a reference to an attribute.

API Documentation
-----------------

.. toctree::
   :maxdepth: 2
   
   autoapi/index

Environment Information

Platform:              darwin; (macOS-26.2-arm64-arm-64bit-Mach-O)
Python version:        3.14.2 (main, Dec  5 2025, 16:49:16) [Clang 17.0.0 (clang-1700.4.4.1)])
Python implementation: CPython
Sphinx version:        9.0.4
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.2


Only dependencies are:

"sphinx>=9",
"sphinx-autoapi",

Sphinx extensions

["autoapi.extension"]

Additional context

No response