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
Hi Jason Ok, I succeeded in writing a slightly less intuitive version of the patch which allows for something like the suggested for the @options and @suboptions decorators. For example, the Sphinx-built argument line for the function sage.plot.contour_plot.contour_plot becomes sage.plot.contour_plot.contour_plot(f, xrange, yrange, axes=False, linestyles=None, frame=True, labels=False, plot_points=100, linewidths=None, colorbar=False, contours=None, fill=True, **options) However, this does not fix everything at once. For example, the function sage.plot.contour_plot.implicit_plot accepts two arguments which are defaulted to None (linewidth and linestyle), so the author did not care to add them to the options-decorator. Therefore, they will not show up in any documentation. If this sounds like what you wanted, I can clean up the code, test it some more and add a new patch to #9976. 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
