{"action":"created","issue":{"url":"https://api.github.com/repos/sphinx-doc/testing2/issues/1254","labels_url":"https://api.github.com/repos/sphinx-doc/testing2/issues/1254/labels{/name}","comments_url":"https://api.github.com/repos/sphinx-doc/testing2/issues/1254/comments","events_url":"https://api.github.com/repos/sphinx-doc/testing2/issues/1254/events","html_url":"https://github.com/sphinx-doc/testing2/issues/1254","id":53296749,"number":1254,"title":"Autodoc fails to handle descriptors with instance attribute access","user":{"login":"shimizukawa","id":151623,"avatar_url":"https://avatars.githubusercontent.com/u/151623?v=3","gravatar_id":"","url":"https://api.github.com/users/shimizukawa","html_url":"https://github.com/shimizukawa","followers_url":"https://api.github.com/users/shimizukawa/followers","following_url":"https://api.github.com/users/shimizukawa/following{/other_user}","gists_url":"https://api.github.com/users/shimizukawa/gists{/gist_id}","starred_url":"https://api.github.com/users/shimizukawa/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/shimizukawa/subscriptions","organizations_url":"https://api.github.com/users/shimizukawa/orgs","repos_url":"https://api.github.com/users/shimizukawa/repos","events_url":"https://api.github.com/users/shimizukawa/events{/privacy}","received_events_url":"https://api.github.com/users/shimizukawa/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/sphinx-doc/testing2/labels/bug","name":"bug","color":"fc2929"},{"url":"https://api.github.com/repos/sphinx-doc/testing2/labels/prio%3Alow","name":"prio:low","color":"FFFFFF"},{"url":"https://api.github.com/repos/sphinx-doc/testing2/labels/wontfix","name":"wontfix","color":"ffffff"}],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":6,"created_at":"2015-01-03T06:54:38Z","updated_at":"2015-01-03T06:54:45Z","closed_at":"2015-01-03T06:54:39Z","body":"First and foremost, here is my motivation: I would like to be able to document descriptors with \"instance attribute access\" with Sphinx's autodoc.\n\nAs an example, when I write something like this:\n\n```\n#!python\n\nfrom django.db import models\n\nclass Person(models.Model):\n    \"\"\"Store data about humans.\"\"\"\n    #: Image that represents the person.\n    avatar = models.ImageField()\n\n```\n\nThen I would like the \"avatar\" attribute and the docstring \"Image that represents the person\" to be shown in Sphinx documentation using autodoc.\n\nIt does not work...\n\nDjango'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.`.\n\nThe AttributeError is raised in descriptor's `__get__()` method: https://github.com/django/django/blob/31e6d58d46894ca35080b4eab7967e4c6aae82d4/django/db/models/fields/files.py#L157\n\nThis behaviour seems in accordance with [descriptors __get__() definition](http://docs.python.org/2/reference/datamodel.html#object.__get__).\nI understand that raising an AttributeError is a feature.\n\nIn 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.\n\n**How could we get documentation for this kind of descriptors?**\nIs it a Sphinx issue? Can developers change the descriptor implementation to make it compatible with Sphinx?\n\nSome additional notes and references:\n\n* Perhaps related to issue #238 or issue #1143\n* Django sometimes returns `self` instead of raising `AttributeError` when trying to access the attribute via the class. See [SingleRelatedObjectDescriptor](https://github.com/django/django/blob/c7d0ff0cad24dbf444f2e4b534377c3352c7aa98/django/db/models/fields/related.py#L182). I do not know why currently.\n* Initially [reported for django-modeltranslation](https://github.com/deschler/django-modeltranslation/pull/131), but the problem can be reproduced with Django's FileField and many custom Django fields (that use [django.db.models.fields.subclassing.Creator](https://github.com/django/django/blob/03d9566e0df45c72bffa99fe244a92f0279da56f/django/db/models/fields/subclassing.py#L24)). I mean, looks like raising an AttributeError is a feature.\n* Perhaps related to https://code.djangoproject.com/ticket/11353\n\n----------------------------------------\n- Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1254\n- Originally reported by: Anonymous\n- Originally created at: 2013-09-05T12:10:15.616\n"},"comment":{"url":"https://api.github.com/repos/sphinx-doc/testing2/issues/comments/68585787","html_url":"https://github.com/sphinx-doc/testing2/issues/1254#issuecomment-68585787","issue_url":"https://api.github.com/repos/sphinx-doc/testing2/issues/1254","id":68585787,"user":{"login":"shimizukawa","id":151623,"avatar_url":"https://avatars.githubusercontent.com/u/151623?v=3","gravatar_id":"","url":"https://api.github.com/users/shimizukawa","html_url":"https://github.com/shimizukawa","followers_url":"https://api.github.com/users/shimizukawa/followers","following_url":"https://api.github.com/users/shimizukawa/following{/other_user}","gists_url":"https://api.github.com/users/shimizukawa/gists{/gist_id}","starred_url":"https://api.github.com/users/shimizukawa/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/shimizukawa/subscriptions","organizations_url":"https://api.github.com/users/shimizukawa/orgs","repos_url":"https://api.github.com/users/shimizukawa/repos","events_url":"https://api.github.com/users/shimizukawa/events{/privacy}","received_events_url":"https://api.github.com/users/shimizukawa/received_events","type":"User","site_admin":false},"created_at":"2015-01-03T06:54:45Z","updated_at":"2015-01-03T06:54:45Z","body":"_From Takayuki Shimizukawa on 2014-05-20 16:28:42+00:00_\n\nIssue #1471 was marked as a duplicate of this issue."}}