You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Instance attributes are prefixed with the class name when they are documented in the class docstring using the sphinx-napoleon extension.
See the screenshot, the instance attribute two-arg is rendered as ~Example.two-arg. This is incorrect, because in Python only class attributes should be prefixed with the the class name (or cls). The ~tilde being included is also a bug.
How to Reproduce
class with docstring
class Example:
"""All documented in class docstring.
Args:
one_arg (int): documented in class docstring.
two_arg (str): documented in class docstring.
Attributes:
Example.attrib1 (str): documented in class docstring.
cls.attrib2 (int): documented in class docstring.
self.one_arg (int): documented in class docstring.
two_arg (str): documented in class docstring.
"""
attrib1 = "Text for test."
attrib2 = 1234
def __init__(self, one_arg: int, two_arg: str):
self.one_arg = one_arg
self.two_arg = two_arg
Attributes documented in class Example
========================================
.. automodule:: module_name
:members:
:no-undoc-members:
Expected behavior
Instance variables should implicitly be rendered only by their name (without self. nor the class name) - thus in the example it should be two-arg instead of ~Example.two-arg. This would allow to implicitly differentiate instance variables from class variables.
The prefixes were added to make a hyperlink for :ivar: role valid at #5129 (v2.0). But the hyperlink feature was removed at #5977 (v4.0). So the prefixing feature should also be removed.
Since 4.0, :ivar: items has not been rendered as hyperlinks. So any
modules, classes and tilda are now harmful. This removes the prefixing
filter for napoleon_use_ivar option.
refs: sphinx-doc#5129 and sphinx-doc#5977
Describe the bug
Instance attributes are prefixed with the class name when they are documented in the class docstring using the sphinx-napoleon extension.
See the screenshot, the instance attribute
two-arg
is rendered as~Example.two-arg
. This is incorrect, because in Python only class attributes should be prefixed with the the class name (orcls
). The~
tilde being included is also a bug.How to Reproduce
class with docstring
conf.py
example.rst
Expected behavior
Instance variables should implicitly be rendered only by their name (without
self.
nor the class name) - thus in the example it should betwo-arg
instead of~Example.two-arg
. This would allow to implicitly differentiate instance variables from class variables.Your project
Personal project
Screenshots
OS
Windows 10 Pro
Python version
3.9.0
Sphinx version
4.4.0
Sphinx extensions
autodoc, sphinx-napoleon
Extra tools
No response
Additional context
example.zip
The text was updated successfully, but these errors were encountered: