sphinx-doc / sphinx-doc/sphinx
Autodoc parameter types in parameter list not resolving for TypeVar or aliases
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
When specifying code like:
from __future__ import annotations
from typing import Generic, TypeVar, Union
#: A variable
X = Union[str, int]
#: Another variable
Y = TypeVar("Y")
class Z:
"""A class we pass as an arg"""
class Bar(Generic[Y]):
"""The class we want
:param X x: an arg
:param Y y: another arg
:param Z z: a third arg
"""
def __init__(self, x: X, y: Y, z: Z) -> None:
self.x = x
self.y = y
self.z = z
def foo(self) -> Y:
return self.y
The parameter z or Bar.__init__ is linked correctly in both the signature and the parameter list, but x and y are not resolved in the parameter list.
The console output is:
<unknown>:1: WARNING: py:obj reference target not found: typing.Union
sphinx-autodoc-types-issue-demo/mycode.py:docstring of mycode.Bar:: WARNING: py:class reference target not found: X
sphinx-autodoc-types-issue-demo/mycode.py:docstring of mycode.Bar:: WARNING: py:class reference target not found: Y
How to Reproduce
$ git clone https://github.com/thomascobb/sphinx-autodoc-types-issue-demo.git
$ cd sphinx-autodoc-types-issue-demo
$ pip sphinx
$ sphinx-build docs html
$ firefox html/index.html
Expected behavior
I would like to see the links for x and y to appear like that of z in the parameter list of Bar, linking to the aliases defined further up the docs
Your project
https://github.com/thomascobb/sphinx-autodoc-types-issue-demo
Screenshots

NOTE X and Y in the parameter list (black) have no links, while Z (blue) has correctly generated a link
OS
Linux
Python version
3.7
Sphinx version
4.2.0
Sphinx extensions
sphinx.ext.autodoc
Extra tools
firefox
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the issue with the sphinx-autodoc-types-issue-demo project, using docs, mycode.py, and the sphinx.ext.autodoc extension. Inspect how autodoc resolves parameter-list types for the X alias and Y TypeVar, then verify that both links appear like the existing Z link without the reported warnings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100