Skip to content

Reference target not found when using generic typed parameters #13731

@moi90

Description

@moi90

Describe the bug

Given the following class:

from __future__ import annotations

from pathlib import Path


class ImageSet:
    pass

class Repository[M: ImageSet]:
    def __init__(
        self,
        member_type: type[M],
        root: str | Path,
        path: str | Path,
        settings,
        inclusion_patterns: list[str] | None = None,
        exclusion_patterns: list[str] | None = None,
    ) -> None:
        ...

I get the following errors:

$ sphinx-build -M html "docs/source" "docs/build" --fail-on-warning --nitpicky

.../src/sphinx_bug/__init__.py:docstring of sphinx_bug.Repository:1: WARNING: py:class reference target not found: Path [ref.class]
.../src/sphinx_bug/__init__.py:docstring of sphinx_bug.Repository:1: WARNING: py:class reference target not found: Path [ref.class]

Only if I remove the type annotation for member_type, the compilation succeeds:

class Repository[M: ImageSet]:
    def __init__(
        self,
        member_type,
        root: str | Path,
        path: str | Path,
        settings,
        inclusion_patterns: list[str] | None = None,
        exclusion_patterns: list[str] | None = None,
    ) -> None:
        ...

It seems that the use of class-bound type aliases triggers this behavior.

How to Reproduce

sphinx_bug/__init__.py:

from __future__ import annotations

from pathlib import Path


class ImageSet:
    pass

class Repository[M: ImageSet]:
    def __init__(
        self,
        member_type: type[M],
        root: str | Path,
        path: str | Path,
        settings,
        inclusion_patterns: list[str] | None = None,
        exclusion_patterns: list[str] | None = None,
    ) -> None:
        ...

index.rst:

.. automodule:: sphinx_bug
   :members:

conf.py:

extensions = [
    "sphinx.ext.autodoc",
]

nitpick_ignore = {
    ("py:class", "M"),
}

Environment Information

Platform:              linux; (Linux-6.11.0-29-generic-x86_64-with-glibc2.39)
Python version:        3.13.4 (main, Jun  4 2025, 17:37:06) [Clang 20.1.4 ])
Python implementation: CPython
Sphinx version:        8.2.3
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.2

Sphinx extensions

extensions = [
    "sphinx.ext.autodoc",
]

Additional context

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions