Autodoc fails to handle descriptors with instance attribute access

Anonymous avatarAnonymous created an issue

First and foremost, here is my motivation: I would like to be able to document descriptors with "instance attribute access" with Sphinx's autodoc.

As an example, when I write something like this:

from django.db import models

class Person(models.Model):
    """Store data about humans."""
    #: Image that represents the person.
    avatar = models.ImageField()

Then I would like the "avatar" attribute and the docstring "Image that represents the person" to be shown in Sphinx documentation using autodoc.

It does not work...

Django's models use descriptors for some fields, such as django.db.models.fields.files.ImageField. Accessing Person.avatar raises AttributeError: The 'avatar' attribute can only be accessed from Person instances..

The AttributeError is raised in descriptor's __get__() method: https://github.com/django/django/blob/31e6d58d46894ca35080b4eab7967e4c6aae82d4/django/db/models/fields/files.py#L157

This behaviour seems in accordance with descriptors get() definition. I understand that raising an AttributeError is a feature.

In such a situation, Sphinx's autodoc fails to handle the avatar attribute, reports a warning and does not display the avatar attribute with docstring in documentation.

How could we get documentation for this kind of descriptors? Is it a Sphinx issue? Can developers change the descriptor implementation to make it compatible with Sphinx?

Some additional notes and references:

Comments (5)

  1. Sean Bell

    For anyone that's interested, I have a workaround for this issue. You can monkey patch the offending Django source code in your conf.py.

    Add this to your Sphinx conf.py after setting up the Django environment:

    from django.db.models.fields.files import FileDescriptor
    FileDescriptor.__get__ = lambda self, *args, **kwargs: self
    
  2. Log in to comment
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.