Skip to content

Autodoc does not support if TYPE_CHECKING imports #11225

@provinzkraut

Description

@provinzkraut

Describe the bug

When using imports in a if TYPE_CHECKING block, autodoc often fails to resolve the reference. It's not entirely clear to me when this is the case, since sometimes it seems to work and sometimes it does not.

Running the provided example will fail to resolve the reference for timedelta and issue the following warning about it:

/***/thing.py:docstring of thing.foo:1: WARNING: py:class reference target not found: timedelta

How to Reproduce

thing.py

from __future__ import annotations

from typing import TYPE_CHECKING


if TYPE_CHECKING:
    from datetime import timedelta


def foo(bar: timedelta) -> None:
    pass

conf.py

project = "thing"
copyright = "2023, a"
author = "a"

nitpicky = True
extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx"]

intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
}

html_theme = "alabaster"

index.rst

thing
=====

.. automodule:: thing
    :members:

Environment Information

Platform:              linux; (Linux-5.19.0-35-generic-x86_64-with-glibc2.35)
Python version:        3.11.0 (main, Oct 29 2022, 14:21:10) [GCC 11.3.0])
Python implementation: CPython
Sphinx version:        5.3.0
Docutils version:      0.19
Jinja2 version:        3.1.2

Sphinx extensions

["sphinx.ext.autodoc", "sphinx.ext.intersphinx"]

Additional context

No response

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions