(Say that subject three times fast.) I'm looking at a ticket whose main purpose is to apply the @rename_keyword decorator in lots of places, outside of the plot module, where it was first employed.
When I build the HTML version of the reference manual, it would appear these functions are now listed simply and universally as foo(*args, **kwds) and any automatic information about the exact nature of the real arguments is lost. If the docstrings were to list this information carefully, at least it would be there, but the docstrings are not always so careful. I believe there is a similar behavior with the @options decorator, though I have not investigated as thoroughly. Again, these options are not always listed in the docstring. I think this explains why sometimes it hard to tell just what plotting options are available. In the case of @rename_keyword there is automatically a deprecation warning. So someday, the decorator will be pulled and the documentation will go back to a more informative version. 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? Rob -- 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
