@task decorator causes Sphinx autodoc to lose fuction signature

[mattaustin]

When using the @task decorator in a fabfile, Sphinx autodoc does not generate the function signature. The docstring is passed correctly, but the args and kwargs are lost.

Some unsuccessful workarounds were attempted at http://stackoverflow.com/questions/8845195/using-sphinx-autodoc-for-a-fabfile, but no solution was found.

This also looks like it could be similar to an issue reported in 2009 regarding the @needs_host decorator, which I found on the fab-user mailing list: http://lists.gnu.org/archive/html/fab-user/2009-09/msg00026.html

[bitprophet]

That 2009 issue is #103. There's also #421, though that deals with the docstring instead, and with doctest and not Sphinx autodoc.

A solution to #103 probably wouldn't solve this outright because @task involves a wrapped/delegate class and not just a nested or decorated function object.

As in both cases, though, you should be able to work around it for now by manually specifying the function signature in your Sphinx doc. The StackOverflow link mentioned this too, but it's not clear if you've tried that specific approach yet :)

[mattaustin]

Thanks Jeff. I should have clarified, that by 'unsuccessful workarounds' I meant for the automatic document generation. Yes, I'm currently manually specifying the function signature, which is great and certainly much better than nothing! Just wanted to make sure this issue was logged in the appropriate place for future reference. Thanks.

[bitprophet]

Glad to hear it, and yes, it's a shitty workaround but better than nothing ;) I just wanted to make sure you knew to give that a shot. Thanks for filing the ticket, it's appreciated!

[bitprophet]

This should be the same problem that was worked around for Fab internals in #748. @task already preserves a handle on the wrapped function as .wrapped, so all that should be needed is to cargo cult the change #748 made to docs/conf.py, into one's own conf.py.

I will see if I can come up with a useful abstraction of that. Thinking a function you could import into your conf.py that takes a module object, discovers all WrappedCallableTask objects attached to it, and replaces it with .wrapped (this last bit is again what #748 does).

This approach basically negates the need to have the __doc__/__module__/etc preservation stuff in @task, but I might as well leave those in place for people who don't want to use this newer approach for some reason.

[bitprophet]

@mattaustin I bring you unwrap_tasks()

EDIT: Oh, I should add a usage example there. Herpaderp. WIll do in a sec.

[bitprophet]

Example added + expanded to allow toggling "JUST the tasks please" behavior. Works for now.

[mattaustin]

@bitprophet Fantastic, will check this out over the weekend. Thanks very much!