> 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
written a patch for Sage's custom version of Sphinx. This essentially
a function/method to be documented is a decorator by looking for the
"_sage_decorating". If a function/method is actually a decorated
another callable, then this callable should be referenced to in
_sage_decorating. With my patch, Sphinx then constructs the signature
All decorators (on documented functions/methods) should then set this
attribute; in particular, sage_wraps does so (with my patch), and I
every decorator aimed at documented functions/methods should use
Ideally, noone should therefore again have to know about this
This seems to work for every function and method I have looked at.
is a bit tedious to force Sphinx to do the rebuild. It seems that you
manually touch all py-files, do a complete rebuild (sage -ba) and then
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
> So, in the code, I have, e.g.:
> def poincare_series(self):
> Return the Poincar\\'e series...
> "poincare_series" DOES appear in the package's manual (see
The problem is not that the functions won't appear but that they will
signature (argument list) of the decorator; for decorators which can
function with any argument, this will often be the generic signature
"<function-name>(*args, **kwargs)". In your case, your method does not
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
decorator inside the decorator; isn't that what you did? We need a
mechanism for inheriting the signature. My patch does this by
decorators to set the attribute _sage_decorating, which is
by using Sage's "sage.misc.decorators.sage_wraps" decorator (see also