First of all, sorry for the terrible word-wrapping in my previous post; it seems Google groups wraps at less than 80 characters.
On Sep 23, 2:57 pm, Jason Grout <jason-s...@creativetrax.com> wrote: > On 9/23/10 7:13 AM, Johan S. R. Nielsen wrote: > > > > > 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. > > In the case of an @options decorator, it would be really cool if the > function signature could be modified to show the options, or in the case > of a @suboptions decorator, show the suboptions. Is there an easy way > to have a decorator change the signature in the docs? For example, > could we make a _sage_signature attribute that the decorator could > change, and use that for the docs? > > Thanks, > > Jason Thats a very nice extension; I guess all sorts of uses for this could be imagined. With the current patch, there is no easy way for the signature to be changed. One would have to define a new function with the appropriate signature inside the decorator and assign to _sage_decorating, as _sage_decorating contains only a reference to a callable. Originally, I wanted to use a _sage_signature like you suggest instead, but the problem was in constructing such a signature. The most practical thing would probably be to construct a signature as a named tuple such as that returned by inspect.getargspec and then let Sphinx format this to text. However, as can be seen by the code in doc.common.sage_autodoc.py surrounding my patches, it takes Sphinx quite a bit of logic to extract the signature, and I wanted to avoid having to copy that. Especially references to custom C-function signature-extractors scared me a bit. There is, of course, the possibility to have both custom attributes, and let _sage_signature override _sage_decorating in case both are defined. It still leaves the problem of having to construct these signatures in the general case. I think the idea is good, but I'm not completely sure how to do it elegantly. 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
