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

Use 3rd party "decorator" module to fix introspection for decorated functions #103

Closed
bitprophet opened this Issue Aug 19, 2011 · 8 comments

Comments

Projects
None yet
3 participants
@bitprophet
Member

bitprophet commented Aug 19, 2011

Description

Some internal functions are decorated by @needs_host or other decorators, and thus lose their ability to be introspected, including by Sphinx autodoc. This makes me sad.

Thankfully, the decorator module has ways to work around this, and looks quite useful. It will add another external dependency but I don't think that's enough of a drawback to be a big concern.

See also an email to me from Matt Wilson dated 2009-09-09 about @needs_host, which is where he informed me about the module in question.


Originally submitted by Jeff Forcier (bitprophet) on 2009-11-11 at 11:49pm EST

@ghost ghost assigned bitprophet Aug 19, 2011

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Aug 19, 2011

Member

Jeff Forcier (bitprophet) posted:


On the one hand, I do hate the broken autodoc. On the other, I don't think a tertiary release is the time to add new dependencies. Bumping this to 1.0.


on 2010-05-27 at 08:33pm EDT

Member

bitprophet commented Aug 19, 2011

Jeff Forcier (bitprophet) posted:


On the one hand, I do hate the broken autodoc. On the other, I don't think a tertiary release is the time to add new dependencies. Bumping this to 1.0.


on 2010-05-27 at 08:33pm EDT

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Aug 19, 2011

Member

Axel Rutz (aexl) posted:


use functools.wraps


on 2010-07-10 at 07:53pm EDT

Member

bitprophet commented Aug 19, 2011

Axel Rutz (aexl) posted:


use functools.wraps


on 2010-07-10 at 07:53pm EDT

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Aug 19, 2011

Member

Jeff Forcier (bitprophet) posted:


We're already using @wraps, this is something different that it cannot solve by itself, unfortunately.


on 2010-07-11 at 09:30pm EDT

Member

bitprophet commented Aug 19, 2011

Jeff Forcier (bitprophet) posted:


We're already using @wraps, this is something different that it cannot solve by itself, unfortunately.


on 2010-07-11 at 09:30pm EDT

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Feb 29, 2012

Member

Bumping to 2.x since it adds a new external dependency.

Member

bitprophet commented Feb 29, 2012

Bumping to 2.x since it adds a new external dependency.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Nov 12, 2012

Member

I can confirm that this works well for the intended use case -- I am using it in a work related codebase in the exact same manner.

Torn on whether to add it to Fab before 2.x -- on the one hand it represents a wholly new dependency, which is arguably backwards incompat. On the other hand, we've had to change the SSH lib dependency back and forth a few times, which is arguably as (if not more) disruptive, so there is precedent.

Member

bitprophet commented Nov 12, 2012

I can confirm that this works well for the intended use case -- I am using it in a work related codebase in the exact same manner.

Torn on whether to add it to Fab before 2.x -- on the one hand it represents a wholly new dependency, which is arguably backwards incompat. On the other hand, we've had to change the SSH lib dependency back and forth a few times, which is arguably as (if not more) disruptive, so there is precedent.

@markstos

This comment has been minimized.

Show comment
Hide comment
@markstos

markstos Apr 11, 2016

May I humbly suggest that if the auto-documentation was desired in 2011 still isn't working yet, perhaps it's time for an alternate approach to improving the docs? Manual documentation (gasp!) or another doc-generator that parses documentation in a template?

Here it is 5 years later and the docs still aren't clear on which positional argument to put() is which (#1452). That seems like a basic thing to address. Even some clearer examples would do the trick in that case:

 put('/path/to/local/file.jpg','/path/on/remote/server/file.png');

Instead, the current example provides no clue to which arg is which:

put('bin/project.zip', '/tmp/project.zip')

Without waiting for a big-picture fix so targeted improvements like this could be helpful.

markstos commented Apr 11, 2016

May I humbly suggest that if the auto-documentation was desired in 2011 still isn't working yet, perhaps it's time for an alternate approach to improving the docs? Manual documentation (gasp!) or another doc-generator that parses documentation in a template?

Here it is 5 years later and the docs still aren't clear on which positional argument to put() is which (#1452). That seems like a basic thing to address. Even some clearer examples would do the trick in that case:

 put('/path/to/local/file.jpg','/path/on/remote/server/file.png');

Instead, the current example provides no clue to which arg is which:

put('bin/project.zip', '/tmp/project.zip')

Without waiting for a big-picture fix so targeted improvements like this could be helpful.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jul 16, 2018

Member

I think this is handled for 2.0 and Invoke via http://invocations.readthedocs.io/en/latest/api/autodoc.html (made during pyinvoke/invoke#520).

It's not 100% ideal but solves the primary case of wanting Sphinx docs for @task-decorated APIs.

Note that this is (AFAIK) distinct from pyinvoke/invoke#555 re: decorator ordering issues.

Member

bitprophet commented Jul 16, 2018

I think this is handled for 2.0 and Invoke via http://invocations.readthedocs.io/en/latest/api/autodoc.html (made during pyinvoke/invoke#520).

It's not 100% ideal but solves the primary case of wanting Sphinx docs for @task-decorated APIs.

Note that this is (AFAIK) distinct from pyinvoke/invoke#555 re: decorator ordering issues.

@bitprophet bitprophet closed this Jul 16, 2018

@lsh-0

This comment has been minimized.

Show comment
Hide comment
@lsh-0

lsh-0 Jul 19, 2018

has this made it into a release? I'm still seeing broken behaviour in Invoke 1.1.0/Fabric 2.2.1

lsh-0 commented Jul 19, 2018

has this made it into a release? I'm still seeing broken behaviour in Invoke 1.1.0/Fabric 2.2.1

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