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
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__()
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.
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.
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
In
config.py
, addAdd python module
samplecode/__init__.py
to root directory, with content of__init__.py
beingContent of
index.rst
to build the docs, run
You will then notice that the output in
index.html
includes "instance_attr" for both classes, even though this is an inherited member forBar
and should not be included.Environment Information
Sphinx extensions
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.