#9976: Decorated functions/methods have generic signature in documentation
-----------------------------+----------------------------------------------
Reporter: jsrn | Owner: mvngu
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-4.6
Component: documentation | Keywords: sphinx, documentation
Author: jsrn | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
-----------------------------+----------------------------------------------
Comment(by jsrn):
Now I've finished, cleaned up and tested an alternative patch. It is a
slightly more invasive change to the Sphinx autodoc algorithm, and it is a
little less intuitive than the other, but it makes it easier for
decorators to change the signature of the wrapped function (currently,
only @option and @suboption uses this).
In the other patch we used the attribute _sage_decorating which returns
the wrapped function to tell Sphinx that it should behave specially, but
in the new patch, the decorating callable should now instead define an
attribute _sage_getargspec. This should be a function returning an argspec
(an argspec is an python.inspect.ArgSpec tuple as returned by
python.inspect.getargspec -- basically describing the elements of a
function's signature) with the help of an "argspec-retrieving function"
taken as argument. This recursive way of doing things is for avoiding the
logic within Sphinx of getting the argspec for various types of functions
(e.g. Python, Cython or built-in). When Sphinx is asked to format the
signature of a function, and that function defines _sage_getargspec, it
formats in a standard way whatever _sage_getargspec(getter) returns, where
getter is basically itself (that is, the Sphinx function currently being
asked to find the argspec of some function).
So for example, @option defines an _sage_getargspec which takes Sphinx's
own argspec-finding function -- let's call that getter.
_sage_getargspec(getter) then uses getter on the wrapped function, getting
the function's original argspec. To this, it adds the options given as
arguments to the decorator. This is then returned to Sphinx which formats
it and outputs that as the signature for the decorated function.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:2>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
