Propagate docstring from decorated function in FunctionTask

[ghisvail]

I would like to provide documentation (with doctests) for a FunctionTask, like:

@task
@annotate({"return": {"sum": int}})
def add(x: int, y: int):
    """Add x to y.

    Examples
    ----------
    >>> task = add(x=1, y=2)
    >>> result = task()
    >>> result.output.sum
    3
    """
    return a + b

Similar to what we have been doing with interfaces implemented with ShellCommandTask.

This does not work however, since the docstring of the wrapped function is not propagated to the FunctionTask class. So far, I have implemented one wrapped function per Python module and used the module's docstring for this purpose.

I wonder whether we could propagate this docstring so that each FunctionTask can have its own documentation.

Unless there is already a feature to achieve this that I totally missed.

[effigies]

So it seems there's something odd with our current implementation, and I don't understand why wraps is not propagating the docstring, but I think we can do the following:

from functools import wraps, partial

def task(func):
    from pydra.engine.task import FunctionTask
    return wraps(func)(partial(FunctionTask, func=func))

Testing that, I get:

In [23]: @task
    ...: def add(x: int, y: int):
    ...:     """Add x to y.
    ...: 
    ...:     Examples
    ...:     ----------
    ...:     >>> task = add(x=1, y=2)
    ...:     >>> result = task()
    ...:     >>> result.output.sum
    ...:     3
    ...:     """
    ...:     return a + b
    ...: 

In [24]: add
Out[24]: functools.partial(<class 'pydra.engine.task.FunctionTask'>, func=<function add at 0x7f866f6d16c0>)

In [25]: ?add
Signature:       add(x: int, y: int)
Call signature:  add(*args, **kwargs)
Type:            partial
String form:     functools.partial(<class 'pydra.engine.task.FunctionTask'>, func=<function add at 0x7f866f6d16c0>)
File:            ~/<ipython-input-23-5216aed9f9b2>
Docstring:      
Add x to y.

Examples
----------
>>> task = add(x=1, y=2)
>>> result = task()
>>> result.output.sum
3
Class docstring:
partial(func, *args, **keywords) - new function with partial application
of the given arguments and keywords.

[tclose]

implemented in #768