#9976: Decorated functions/methods have generic signature in documentation
-----------------------------------------------------+----------------------
Reporter: jsrn | Owner: jsrn
Type: enhancement | Status: needs_work
Priority: major | Milestone: sage-4.7
Component: documentation | Keywords: sphinx,
documentation, cython inspection
Author: jsrn, Simon King | Upstream: N/A
Reviewer: Simon King | Merged:
Work_issues: Cosmetical changes, indirect doctests |
-----------------------------------------------------+----------------------
Comment(by jsrn):
Replying to [comment:108 SimonKing]:
> The new patch version improves parsing of arguments a lot.
>
> It provides a function
`sage.misc.sageinspect._grep_first_pair_of_parentheses`, that is used to
find the first matching pair of parentheses without being fooled by
parentheses inside string variables. In other words, it finds the sub-
string of a function definition that provides its arguments.
I think there is still problems because you don't consider escaped quotes.
For example, putting a single escaped ' in a string argument causes an
error:
{{{
sage: sage: cython('def foo(x, a=\'\\\')"\', b={not (2+1==3):\'bar\'}):
return')
sage: sage: print sage.misc.sageinspect.sage_getsource(foo)
def foo(x, a='\')"', b={not (2+1==3):'bar'}): return
sage: sage: sage.misc.sageinspect.sage_getargspec(foo)
ValueError
...
ValueError: Could not parse cython argspec
}}}
I wish there was some other way than (re)implementing an almost full
expression parser for this :-S
> I don't think so. If I am not mistaken, these lines (and a similar set
of lines in a different place) will be used in different cases as well.
And since it is not particularly difficult to extend the functionality of
the SageArgSpecVisitor, I think we should aim for sufficient generality.
When compiling all documentation, the _grep-function is only called from
sage_getarcspec on the CachedMethod or RequireField decorators. After
these are (eventually) patched, I think it would be a good idea if
sage_getargspec threw an error in this case: for then a code author would
know he did something which is essentially wrong. It seems you are right
that the grep-function is called from the _cython-function on several
methods (apparently, Python methods within Cython source files, but I am
not sure).
Btw, deleting the folder devel/sage/doc/output and running {{./sage
-docbuild all html}} seems to rebuild the entire documentation from
scratch. This produces a lot of warnings! They are all like this:
{{{
/home/jsrn/sage-dev/local/lib/python2.6/site-
packages/sage/functions/transcendental.py:docstring of
sage.functions.transcendental.Function_zetaderiv:18: (WARNING/2) Block
quote ends without a blank line; unexpected unindent.
}}}
Did I do something wrong?
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:111>
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.
