#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 SimonKing):
Replying to [comment:111 jsrn]:
> I think there is still problems because you don't consider escaped
quotes.
Right. I have to think about that.
> I wish there was some other way than (re)implementing an almost full
expression parser for this :-S
Indeed.
> 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.
I don't think so.
In some cases, `sage_getargspec` has to rely on source code. Here I am not
talking about decorators and other fancy stuff (these can have
`_sage_argspec_`), but about ordinary functions and methods. Also I am not
talking about the output of some obscure `_sage_src_` method, but about
actual source files.
Hence, `sage_getargspec` should be able to correctly parse anything that
is valid code in Python or Cython.
> Btw, deleting the folder devel/sage/doc/output and running {{./sage
-docbuild all html}} seems to rebuild the entire documentation from
scratch.
But "from scratch", it will be only for those parts that were recently
rebuilt. So, when you want to re-build documentation of a file, you should
touch it, do `sage -b`, and then `sage -docbuild ...`.
> 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?
I don't think so.
At `sage/functions/transcendental.py` in line 166, I see that the doc
string starts with """, not with r""". Hence, it is not a raw string. But
then, in the latex example in line 183, the "\right" will be interpreted
as a line break "\r" followed by "ight". You can see this if you do
{{{
sage: sage.functions.transcendental.Function_zetaderiv?
}}}
So, it is neither your nor my fault. But in a few seconds, I will upload a
new version of my doc fixes patch.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:113>
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.
