@task decorator causes Sphinx autodoc to lose fuction signature #569

Closed
mattaustin opened this Issue Feb 26, 2012 · 7 comments

Projects

None yet

2 participants

@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
Member

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 :)

@bitprophet bitprophet was assigned Feb 26, 2012
@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
Member

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 bitprophet closed this Nov 1, 2012
@bitprophet bitprophet reopened this Nov 1, 2012
@bitprophet
Member

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 bitprophet added a commit that closed this issue Nov 1, 2012
@bitprophet bitprophet Add docs helper for + Sphinx autodoc.
Also clean up related docstrings re: interlinks n such.

Fixes #569
97d9b56
@bitprophet bitprophet closed this in 97d9b56 Nov 1, 2012
@bitprophet
Member

@mattaustin I bring you unwrap_tasks()

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

@bitprophet
Member

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment