Automodule interprets the definition of descriptor types as attributes

[shimizukawa]

1. Create a descriptor type in a module

2. create a document with

    .. automodule:: <module>
       :members:
       :show-inheritance:
   

Expected: documents the class as a class, documents its members and shows its inheritance
Observed: documents the class as an attribute, just shows its docstring

Problem source

AttributeDocumenter has a higher priority than ClassDocumenter and if the member being checked (in can_document_member) is a descriptor all other checks are ignored

Partial solution

put the isdatatesc check under not isinstance(parent, ModuleDocumenter) somehow: descriptors don't work at the module-level (save through shenanigans of explicitly creating a ModuleType subclass and shoving it into sys.modules by hand)

Issue remaining

defining a descriptor type as an inner class will still be incorrectly documented as an attribute

Alternative solution

Add not isinstance(member, class_types) in the decision tree for isdatadesc

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1526
• Originally reported by: masklinn
• Originally created at: 2014-08-04T10:39:39.357

[shimizukawa]

From Kevin Norris on 2014-09-11 03:03:36+00:00

I don't see this under 1.2.3. I believe https://bitbucket.org/birkenfeld/sphinx/pull-request/107 may have fixed it.

However, I do see a slightly more complex bug. If the descriptor type has a metaclass (like, say, abc.ABCMeta), the issue reappears. This is apparently because the pull request compares the __name__ of the type() of the thing being documented (i.e. member) to (among other things) "type". Since metaclasses can have arbitrary names, it is not at all obvious how this approach can be generalized. I'd recommend replacing the string compare with a isinstance(member, type) check or something similar.

[shimizukawa]

Original issue was fixed at sphinx-1.2.3 release.
And now additionally reported issue also fixed by #1843.