Hi
> I find the generic version of the function definitions less than
> satisfactory. I'd guess it would be had to make Sphinx pickup the
> more detailed info in these situations? I'd also guess the decorators
> could maybe manipulate the docstring and inject some information based
> on the arguments of the decorator? Either way, could the effect of
> these decorators on the documentation be improved?
I agree that this is completely unacceptable. I have created Trac 9976
and
written a patch for Sage's custom version of Sphinx. This essentially
checks if
a function/method to be documented is a decorator by looking for the
attribute
"_sage_decorating". If a function/method is actually a decorated
version of
another callable, then this callable should be referenced to in
_sage_decorating. With my patch, Sphinx then constructs the signature
from this
callable instead.
All decorators (on documented functions/methods) should then set this
attribute; in particular, sage_wraps does so (with my patch), and I
guess that
every decorator aimed at documented functions/methods should use
sage_wraps.
Ideally, noone should therefore again have to know about this
workaround.
This seems to work for every function and method I have looked at.
However, it
is a bit tedious to force Sphinx to do the rebuild. It seems that you
have to
manually touch all py-files, do a complete rebuild (sage -ba) and then
rebuild
the documentation.
I hope that you agree this solution is sensible.
Simon King wrote:
> Why is this? For my group cohomology spkg, I wrote some decorator
> "temporary_result" that caches methods of a ring approximation (i.e.,
> generators and relations are only known out to a certain degree), but
> clears the cache if more generators or relations are found in higher
> degree.
>
> So, in the code, I have, e.g.:
> @temporary_result
> def poincare_series(self):
> """
> Return the Poincar\\'e series...
> ...
> """
> ...
>
> "poincare_series" DOES appear in the package's manual (see
>
http://sage.math.washington.edu/home/SimonKing/Cohomology/cohomology....).
The problem is not that the functions won't appear but that they will
have the
signature (argument list) of the decorator; for decorators which can
decorate a
function with any argument, this will often be the generic signature
"<function-name>(*args, **kwargs)". In your case, your method does not
take any
arguments (except for self), and neither does the decorator, so you
will see no
difference in the documentation.
> Moreover, the decorator also manages to decorate the given docstring,
> so that it becomes
> Temporarily cached method: Return the Poincar’e series...
>
> The decorator is a callable class, and a decorated method is an
> instance of this class. This instance can apparently borrow the name
> and the docstring (even adding a modification) from the method.
>
> Since the decorators in Sage (more precisely: the cached method
> decorator) were my source of inspiration, I am surprised that
> @CachedFunction is problematic for the documentation.
The docstring and name is inherited by the decorator by using Python's
"wraps"
decorator inside the decorator; isn't that what you did? We need a
similar
mechanism for inheriting the signature. My patch does this by
requiring
decorators to set the attribute _sage_decorating, which is
automatically done
by using Sage's "sage.misc.decorators.sage_wraps" decorator (see also
Trac
#9907).
Cheers,
Johan