How can I document a function which takes a function as a parameter with Sphinx?

问题

Let's say I have a class which looks something like this:

class FunctionCaller:
    def __init__(self):
        """A class which can be used to call different functions which take the same
        parameters

        """
        self.f = lambda a,b: (a,b)

    def setF(self, new_f):
        """Set the function to call

        :param new_f: The new function this object should call
        :type new_f: func(:class:`.SomeClass`, :class:`int`)
        """
        self.f = new_f

    def callF(self, a, b):
        """Call the function this object currently contains

        :param a: Some value
        :param b: Some other value
        """
        return self.f(a,b)

class SomeClass:
    """Some class which does nothing
    """
    pass

For example (ignoring the fact that this might be bad coding style), let's assume that the function that the FunctionCaller is going to be calling expects to take SomeClass as its first parameter, and an int as its second. I'd like the documentation to display links to both of those things. The way I've defined it in the example works, but it doesn't look very good.

Is there a way that I can use the :type: specifier to indicate that the parameter is a function?

回答1:

Is there a way that I can use the :type: specifier to indicate that the parameter is a function?

You could specify types.FunctionType as the type, I suppose. But I'd suggest that you just explain how it works:

def setF(self, new_f):
     """Set the function to call

     :param new_f: The new function this object should call.

     The new function takes two positional parameters: the first of
     type :class:`.SomeClass` and the second of type :class:`int`.
     """
     self.f = new_f

来源：https://stackoverflow.com/questions/33469924/how-can-i-document-a-function-which-takes-a-function-as-a-parameter-with-sphinx

标签

python

python-sphinx