sphinx-doc / sphinx-doc/sphinx

autodoc: Add support for PEP 613 - Explicit Type Alias

Open
#8,934 7 comments 32 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

domains:py extensions:autodoc type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.
PEP 613 introduces a new type to help with static type checking called TypeAlias. It's expected to be released in the typing module in Python 3.10, and currently available (at least in 3.9, have not verified prior versions) as part of the typing_extensions module.

The intent is to explicitly mark a variable as a type alias. e.g.

OptIntStr: TypeAlias = Optional[int, str]

Currently, the default behaviour of autodoc is to expand type aliases in the output for the signatures it encounters.
To prevent this behaviour we need to explicitly add the type aliases to autodoc_type_aliases. It works, but it's tedious and feels redundant.

One way Sphinx can take advantage of the TypeAlias annotation would be to auto-populate autodoc_type_aliases as autodoc encounters these explicit type aliases. If there's a more straightforward way of doing it, even better.

Describe the solution you'd like
Somehow use TypeAlias to produce the same results that are currently achieved by populating autodoc_type_aliases, without having to redundantly add items to it in config.py.

Describe alternatives you've considered
The alternative already exists (autodoc_type_aliases). TypeAlias is a new feature in Python, and I think this is a useful way for Sphinx to take advantage of it.

Additional context
Large-scale use of TypeAlias is not likely to happen anytime soon because mypy doesn't support it yet (as of 0.812). However, I don't see this as a reason to not implement it. It just means time can be taken to come up with good ideas and implementations.

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

Start with the existing autodoc_type_aliases configuration in config.py and review the PEP 613 TypeAlias behavior described in the issue. Determine how autodoc currently expands aliases and define how automatic handling should match the existing configuration. Done means explicit TypeAlias annotations produce the intended documentation without redundant config.py entries, with appropriate tests added.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.