Skip to content

Render TypeVars as text in restify#14504

Open
gaborbernat wants to merge 1 commit into
sphinx-doc:masterfrom
gaborbernat:fix-restify-typevar
Open

Render TypeVars as text in restify#14504
gaborbernat wants to merge 1 commit into
sphinx-doc:masterfrom
gaborbernat:fix-restify-typevar

Conversation

@gaborbernat

Copy link
Copy Markdown
Contributor

Fixes #14502.

restify() emits a :py:obj: cross-reference for a TypeVar, whereas stringify_annotation() renders TypeVars as plain text. A TypeVar is not a documentable target, so that reference is never resolvable. With show-inheritance, documenting a class that derives from Generic[_T] (where _T is an undocumented, e.g. private, type variable) therefore fails a nitpicky / -W build:

py:obj reference target not found: mod._T [ref.obj]

This renders TypeVars by name in restify() too, making it consistent with stringify_annotation() and removing the dangling reference. The existing test_restify_type_hints_typevars assertions are updated to the text rendering, and a regression note is added to CHANGES.rst.

Minimal reproducer (passes after this change):

# mod.py
from typing import Generic, TypeVar
_T = TypeVar("_T")
class Foo(Generic[_T]):
    """A generic class with a private TypeVar."""
# conf.py
extensions = ["sphinx.ext.autodoc"]
nitpicky = True
autodoc_default_options = {"members": True, "show-inheritance": True}
.. automodule:: mod
   :members:

@gaborbernat gaborbernat force-pushed the fix-restify-typevar branch 3 times, most recently from 7c32d9d to fa3d857 Compare June 26, 2026 17:36
restify() emitted a py:obj cross-reference for a TypeVar. A bare TypeVar
is usually not a documentable target, so with show-inheritance a class
deriving from Generic[_T] (with an undocumented type variable) produced a
nitpicky/-W failure:

    py:obj reference target not found: mod._T [ref.obj]

Render a TypeVar as its ``TypeVar(name, ...)`` definition instead: the
class links to typing, and the name links only when it is itself
documented (or available via intersphinx), otherwise falling back to text
via a new missing-reference handler in the Python domain.

Closes sphinx-doc#14502
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

autodoc show-inheritance emits dangling py:obj xref for a TypeVar in a Generic[...] base (nitpicky)

2 participants