vispy/vispy — pull request #566 by inclement (2014-09-13 01:35:14+00:00)
Title: Some functions are omitted from the sphinx doc

I mentioned this on the vispy gitter page...after looking into it, it seems the reason (at least in the case I noticed) is that methods with vispy's decorators do not preserve the `__doc__`, so sphinx doesn't know about their docstrings.

As far as I can tell, the standard basic fix is as in this PR, using `functools.wrap` (python2.5+) to preserve the docstring. This works and sphinx documents the decorated method. However, it gets the function signature wrong, and there doesn't seem to be a neat solution - the [decorator](http://micheles.googlecode.com/hg/decorator/documentation.html) module provides a replacement for `functools.wrap` that preserves this correctly, but is not in the stdlib. It's also possible to manually tell sphinx the correct docstring, but laborious and fragile to manually sync with the rst files. Stackoverflow reports a range of other hacks available...

So, I don't know what general solution you would want to use, but here's a report of the problem.