Navigation Menu

Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
electric-coder opened this issue Feb 10, 2022 · 1 comment

Comments

@electric-coder
Copy link

electric-coder commented Feb 10, 2022

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

@tk0miya
Copy link
Member

tk0miya commented Feb 11, 2022

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.

@tk0miya tk0miya added this to the 4.5.0 milestone Feb 11, 2022
tk0miya added a commit to tk0miya/sphinx that referenced this issue Feb 11, 2022
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
tk0miya added a commit that referenced this issue Feb 13, 2022
Fix #10181: napoleon_use_ivar adds unexpected prefix to vars
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Mar 16, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

2 participants