sphinx-doc / sphinx-doc/sphinx
autodoc: Add support for PEP 613 - Explicit Type Alias
Nobody has claimed this yet.
- 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
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
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