sphinx-doc / sphinx-doc/sphinx
autodoc_typehints="description" doesn't fully resolve constructor type hints from type comments
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
When autodoc_typehints="description", type hint comments for classes aren't fully resolved, even with autoclass_content="both".
To Reproduce
Create module.py with these contents:
from typing import Optional
Maybe = Optional
class MaybeInt(object):
""":param value: The value to hold"""
def __init__(self, value):
# type: (Maybe[int]) -> None
self.value = value
def get_value(self):
# type: () -> Maybe[int]
""":return: The held value"""
return self.value
Create index.rst with these contents:
.. automodule:: module
:members:
Generate docs twice in plain text format twice, once with autodoc_typehints="description" and once with autodoc_typehints="signature".
python3.8 -msphinx -aE -C -b text -D 'extensions=sphinx.ext.autodoc' -D autoclass_content=both -D autodoc_typehints=description . description
python3.8 -msphinx -aE -C -b text -D 'extensions=sphinx.ext.autodoc' -D autoclass_content=both -D autodoc_typehints=signature . signature
And note that signature/index.txt has:
class module.MaybeInt(value)
Parameters:
**value** (*Maybe**[**int**]*) -- The value to hold
Return type:
None
get_value()
Returns:
The held value
Return type:
Optional[int]
In the case of the return type from get_value, the Maybe was resolved by typing.get_type_hints to be Optional. In the case of the parameter to the constructor, the Maybe was not able to be resolved.
When autodoc_typehints="signature", both were successfully resolved to Optional.
Expected behavior
Type hints should be fully resolved.
Environment info
- OS: Linux
- Python version: 3.8.5
- Sphinx version: 3.2.1
- Sphinx extensions: sphinx.ext.autodoc
Additional context
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 by reproducing the issue with the provided module.py, index.rst, and Sphinx commands, then trace the autodoc handling for constructor type comments under autodoc_typehints="description". Done means the constructor parameter type resolves Maybe to Optional consistently with the signature output.
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
- 48/100