sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.55k stars 2.12k forks source link

Use of TypeVar results in "reference target not found" error #10974

Open hassec opened 1 year ago

hassec commented 1 year ago

Describe the bug

Simple example below. The TypeVar seems to get converted into py:data and thus we get an error when the type info in the signature or description tries to link to a py:class for it.

repro.py:docstring of repro.test:: WARNING: py:class reference target not found: repro.T

How to Reproduce

With the below files in a folder, run sphinx-build -Eanb html . build/

index.rst

Repro Warning
=============

.. automodule:: repro
   :members:
   :undoc-members:
   :show-inheritance:

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))
extensions = ["sphinx.ext.autodoc"]
autodoc_typehints = "both"

repro.py

from typing import TypeVar

T = TypeVar("T")
""" A Generic type """

def test(a: T) -> T:
    """A Test Function"""
    return a

Environment Information

Platform:              linux; (Linux-5.10.16.3-microsoft-standard-WSL2-x86_64-with-glibc2.31) 
Python version:        3.10.7 (main, Sep  6 2022, 21:51:06) [GCC 9.4.0]) 
Python implementation: CPython 
Sphinx version:        5.3.0 
Docutils version:      0.17.1
Jinja2 version:        3.1.2 

Sphinx extensions

autodoc

Additional context

No response

hassec commented 1 year ago

I think this is actually the same problem that is reported in #10785.

And more generally it seems that using something as a type hint that isn't documented as py:class: will always result in this error. This is also true for numpy.float64 which for example is documented as :py:attr: so intersphinx+type hinting leads to the same error.

jakkdl commented 2 months ago

I think this is actually the same problem that is reported in #10785.

And more generally it seems that using something as a type hint that isn't documented as py:class: will always result in this error. This is also true for numpy.float64 which for example is documented as :py:attr: so intersphinx+type hinting leads to the same error.

I am also hitting this with annotations using e.g. math.inf and types.FrameType which are set to :py:data:. There appears to be lots of objects in the standard library that are not possible to reference (w/o a workaround) for this reason.