sphinx-doc / sphinx-doc/sphinx

Callables implementing descriptor protocol are documented as attributes

Open
#6,573 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Describe the bug

A callable that implements the descriptor protocol will be documented by autosummary as an attribute rather than a function. e.g.

class _MyFunction:
    def __call__(self):
        """Example function-like object"""
        print("Hello, world")

    def __get__(self, instance, owner):
        from functools import partial
        return partial(self.__call__, instance)

To Reproduce
From the root of the included project,

$ make -C docs html

docs/source/generated/autobugdemo.func.rst now contains the autosummary for the callable function, which is using autoattribute.

Expected behavior

I expect autofunction to be generated since it is a callable object.

Your project
sphinx-autofunc-bug.zip

Environment info

  • OS: Ubuntu Linux
  • Python version: 3.7.1
  • Sphinx version: 2.1.2
  • Sphinx extensions: sphinx.ext.autodoc, sphinx.ext.autosummary

Additional context
I am creating a function decorator that wraps the function in a callable object. This object must implement the descriptor protocol in order to correctly act like a method.

Sphinx does have checks for built in Function-like types (e.g. WrapperDescriptorType), but as far as I can tell there's no equivalent for user types. I think the relevant special casing is in isattributedescriptor

https://github.com/sphinx-doc/sphinx/blob/5d89c30dab810117421b6262362b1b45432c9f8e/sphinx/util/inspect.py#L171-L195

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

Start with sphinx/util/inspect.py, particularly isattributedescriptor, which the issue identifies as relevant to descriptor classification. Reproduce the behavior from the supplied project with make -C docs html and inspect docs/source/generated/autobugdemo.func.rst. Done means the callable descriptor is documented with autofunction rather than autoattribute.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.