sphinx-doc / sphinx-doc/sphinx

Autodoc includes inherited and undocumented attributes if extensions make use of ``AttributeDocumenter.import_object``

Open
#12,920 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

When an extension makes use of AttributeDocumenter.import_object and a parent exists, this then calls .update_annotations and overwrites the __annotations__ of the parent.
This happens (or can happen?) before the import mechanics (e.g. importer.py:get_class_members) get the various members of a class, and as a result too many attributes may be included.

The original bug report for this is https://github.com/Chilipp/autodocsumm/issues/95. A nice example is given there.
Autodocsumm needs to call .import_objects to do some additional checks on the object.

I have tried to trace this further than the original bug report. Being not very familiar with the Sphinx codebase, this is not trivial, so my explanation above may not be entirely correct.

In my opinion, the solution would probably be to not modify the original __annotations__ but rather store the discovered annotations separately.

On the other hand, if this turns out to not be a bug, a workaround needs to be found in autodocsumm.

I'd like some guidance here and maybe I can submit a PR or fix this in autodocsumm alternatively.

How to Reproduce
pip install sphinx autodocsumm
sphinx-quickstart --no-sep --project test --author me -l en -r 0.0.1

In config.py, add

extensions = [
    'autodocsumm',
    'sphinx.ext.autodoc',
]

Add python module samplecode/__init__.py to root directory, with content of __init__.py being

class Foo:
    """
    Foo is a class that does not inherit from anything
    """

    classattr: str = "MyClassAttr"
    """
    This is a class attribute
    """

    def __init__(self):
        self.instance_attr: str = "MyInstanceAttr"
        """
        This is an instance attribute
        """

        self.typed_instance_attr: str = "MyTypedAttrNoDocs"


class Bar(Foo):
    """
    Bar is a class that inherits from Foo
    """

    def __init__(self):
        self.other_instance_attr: str = "MyOtherInstanceAttr"
        """
        This is annother instance attribute
        """

        super().__init__()

Content of index.rst

test-docs documentation
=======================


.. automodule:: samplecode
   :members:
   :autosummary:

to build the docs, run

python -m sphinx -M html . _build

You will then notice that the output in index.html includes "instance_attr" for both classes, even though this is an inherited member for Bar and should not be included.

Environment Information
Platform:              win32; (Windows-10-10.0.19044-SP0)
Python version:        3.12.1 (tags/v3.12.1:2305ca5, Dec  7 2023, 22:03:25) [MSC v.1937 64 bit (AMD64)])
Python implementation: CPython
Sphinx version:        7.4.7
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0
Sphinx extensions
[
    'autodocsumm',
    'sphinx.ext.autodoc',
]
Additional context

The original issue also mentions that undocumented attributes are included. I'm failing to reproduce that part currently. But I had managed to reproduce it previously.

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

Reproduce the example with autodocsumm and inspect AttributeDocumenter.import_object alongside importer.py:get_class_members, focusing on when parent annotations is updated. Done means the build no longer includes inherited or undocumented attributes incorrectly, while the documented attribute behavior remains correct.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.