sphinx-doc / sphinx-doc/sphinx

autodoc confuses constructor parameter typehint with class attribute typehint

Open
#11,207 4 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc
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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.