-
-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Closed
Closed
Copy link
Milestone
Description
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 (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
conf.py
import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
html_theme = 'sphinx_rtd_theme'
templates_path = ['_templates']
html_static_path = ['_static']
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx_rtd_theme'
]
napoleon_google_docstring = True
napoleon_numpy_docstring = False
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = True
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = True
napoleon_use_admonition_for_notes = True
napoleon_use_admonition_for_references = False
napoleon_use_ivar = True
napoleon_use_keyword = True
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_preprocess_types = False
napoleon_type_aliases = None
napoleon_attr_annotations = False
autodoc_default_options = {
'members': True,
'undoc-members': False,
'show-inheritance': True,
'member-order': 'bysource',
'ignore-module-all': True,
}
add_module_names = False
add_function_parentheses = True
autoclass_content = 'class'
autodoc_class_signature = "mixed"
autodoc_typehints = 'signature'
autodoc_preserve_defaults = True
autodoc_typehints_description_target="all"
example.rst
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.
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
