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 -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
