Skip to content

napoleon prefixes instance attributes documented in class docstring with class name #10181

@electric-coder

Description

@electric-coder

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

ss_sphinx_bug

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

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions