sphinx-doc / sphinx-doc/sphinx

[4.x] TypeVars rendered fullly qualified

Open
#8,994 4 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

Trying Sphinx 4.0 (from master branch, commit c817c206265f545529b5fabe43fdf162bbc9bea2) I noticed that TypeVars are now rendered fully.qualified.T instead of just T like they used to in Sphinx 3.x.

To Reproduce

I'm using the following code in the example below (though with _E -> E, but that's not pertinent):

https://github.com/pytest-dev/pytest/blob/146eda93e7baf621475aef07be2c7b153f6acf03/src/_pytest/python_api.py#L577

Expected behavior

I think that for TypeVars specifically, for the vast majority of cases, it is better to only use the short name, even though it could cause an ambiguity.

Your project

https://github.com/pytest-dev/pytest

Screenshots

Before:

before

After:

after

Environment info

  • OS: Linux
  • Python version: 3.9.2
  • Sphinx version: 4.0.0 (master branch) commit c817c206265f545529b5fabe43fdf162bbc9bea2
  • Sphinx extensions:
extensions = [
    "pallets_sphinx_themes",
    "pygments_pytest",
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.intersphinx",
    "sphinx.ext.todo",
    "sphinx.ext.viewcode",
    "sphinx_removed_in",
    "sphinxcontrib_trio",
]

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 rendering change using the linked pytest example with Sphinx 4.x and compare it with Sphinx 3.x. Trace the autodoc or type-rendering entry point responsible for TypeVar names; done means TypeVars render as their short names rather than fully qualified names without regressing other type displays.

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
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.