New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

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

Comments

Projects
None yet
2 participants
@mattaustin

mattaustin commented Feb 26, 2012

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

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Feb 26, 2012

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

Member

bitprophet commented Feb 26, 2012

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

@ghost ghost assigned bitprophet Feb 26, 2012

@mattaustin

This comment has been minimized.

Show comment
Hide comment
@mattaustin

mattaustin Feb 27, 2012

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.

mattaustin commented Feb 27, 2012

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

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Feb 27, 2012

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!

Member

bitprophet commented Feb 27, 2012

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 comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Nov 1, 2012

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.

Member

bitprophet commented Nov 1, 2012

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 closed this in 97d9b56 Nov 1, 2012

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Nov 1, 2012

Member

@mattaustin I bring you unwrap_tasks()

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

Member

bitprophet commented Nov 1, 2012

@mattaustin I bring you unwrap_tasks()

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

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Nov 1, 2012

Member

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

Member

bitprophet commented Nov 1, 2012

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

@mattaustin

This comment has been minimized.

Show comment
Hide comment
@mattaustin

mattaustin Nov 1, 2012

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

mattaustin commented Nov 1, 2012

@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