Sphinx and Decorated Methods

Sphinx does not always correctly handle decorated methods. To ensure a method’s call signature appears correctly in the docs, use functools.wraps in the definition of the decorator. This will ensure that metadata associated with the function or method, such as the docstring, are correctly applied to the decorated function.

For example, if you have decorator that looks like this:

    import functools

    def mydecorator(f):
        @functools.wraps(f)
        def wrapped(*args, **kwargs):
            print "Before decorated function"
            r = f(*args, **kwargs)
            print "After decorated function"
            return r
        return wrapped

and a method that looks like this and has the decorator applied to it:

    @mydecorator
    def compute_partials(self, inputs, partials):
        """
        Compute sub-jacobian parts / factorization.

        Parameters
        ----------
        inputs : Vector
            unscaled, dimensional input variables read via inputs[key]
        partials : Jacobian
            sub-jac components written to partials[output_name, input_name]
        """

        pass

The generated documentation will correctly document the inputs and partials arguments. Without it, the documented arguments would be *args and **kwargs, the arguments of the decorator itself.