sphinx-doc / sphinx-doc/sphinx
autodoc confuses constructor parameter typehint with class attribute typehint
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
The following script
class MyClass:
"An instance of this class holds a list.\n\n:param r: the list as a string"
l: list
def __init__(self,r:str): self.l = list(r)
produces the following doc, as expected:
An instance of this class holds a list.
Parameters * r (str): the list as a string
Now, if I just change the name of the class attribute (and name it the same as the parameter), then Sphinx gets confused.
class MyClass:
"An instance of this class holds a list.\n\n:param r: the list as a string"
r: list
def __init__(self,r:str): self.r = list(r)
produces the following doc, where the parameter is shown as having the type of the attribute with same name:
An instance of this class holds a list.
Parameters * r (list): the list as a string
Having a class attribute and a constructor parameter with the same name but not exactly the same type is quite common. For example, the parameter could be of type Optional[T] and the attribute of type T, with a default value being assigned in the constructor.
How to Reproduce
In index.rst:
.. toctree::
:maxdepth: 2
:caption: Contents:
.. automodule:: TEST
:members:
:member-order: bysource
:show-inheritance:
In conf.py:
extensions = ['sphinx.ext.autodoc','sphinx.ext.viewcode']
autodoc_typehints = 'description'
Environment Information
Platform: linux; (Linux-6.1.12-100.fc36.x86_64-x86_64-with-glibc2.35)
Python version: 3.10.9 | packaged by conda-forge | (main, Feb 2 2023, 20:20:04) [GCC 11.3.0])
Python implementation: CPython
Sphinx version: 6.1.3
Docutils version: 0.18.1
Jinja2 version: 3.1.2
Pygments version: 2.14.0
Sphinx extensions
No response
Additional context
No response
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 Python reproducer and the index.rst and conf.py settings, especially automodule and autodoc_typehints = 'description'. Run the example with matching class-attribute and constructor-parameter names, then trace autodoc's type-hint handling. Done means the constructor parameter is documented as str rather than inheriting the class attribute's list type.
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
- 45/100