sphinx-doc / sphinx-doc/sphinx

Autodoc parameter types in parameter list not resolving for TypeVar or aliases

Open
#9,705 1 comment 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc type:bug
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

image

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.