CODEWITHSUNDEEP
pythonpython-sphinxpython-decoratorsautodoc
koala
koala

Reputation: 119

Why does sphinx autodoc output a decorator's docstring when there are two decorators in a method?

Using sphinx autodoc I want to generate documentation for the method that has @classproperty and @classmethod decorators. Instead of the method's documentation I get @classmethod's documentation. If I delete any of the decorators everything works properly. Class code is structured like below:

class Example(object):
    @classproperty
    @classmethod
    def example_method(cls):
       """Method description"""
       pass

Classproperty decorator:

class classproperty(property):
    def __get__(self, obj, type=None):
        return self.fget.__get__(None, type)()

And I am generating the documentation using:

.. autoclass:: Example
    :members:

Upvotes: 2

Views: 1442

Answers (1)

Fausto Morales
Fausto Morales

Reputation: 193

From the Sphinx documentation,

Note

If you document decorated functions or methods, keep in mind that autodoc retrieves its docstrings by importing the module and inspecting the doc attribute of the given function or method. That means that if a decorator replaces the decorated function with another, it must copy the original doc to the new function.

From Python 2.5, functools.wraps() can be used to create well-behaved decorating functions.

So I think the problem here is that your decorator is dropping the docstring when it wraps the function. wraps should be able to help with this.

You could follow the pattern from the Python documentation on the subject. For your use case, you might do:

from functools import wraps

def classpropertymethod(f):
    @wraps(f)
    def wrapper(*args, **kwargs):
        return classproperty(classmethod(f(*args, **kwargs)))
    return wrapper

@classpropertymethod
def example_method(cls):
    """Method description"""
    pass

This should get the docstring from example_method passed through correctly.

Upvotes: 2

Related Questions