#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):
> 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.
I think this leads to a long religious discussion on when to stop
servicing and when to start putting restrictions on the freedom of writing
code. One can do pretty sick things in Python, and there are both
arguments for and against allowing/encouraging doing these things in a
large system like Sage; and one of the "mechanisms" of
controlling/limiting this could be via service functions like
sage_getargspec. BUT: I definitely agree that the precedence already in
sage_getargspec is to be as open-minded as possible, so your code and
bugfix is an enhancement on the current trend. (one could always this
religious discussion to sage-devel, probably leading to a long, pointless
discussion with little outcome ;-) )
>
> > 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 ...`.
I thought so too, but it doesn't seem like that. Possibly, like Make, the
docbuilder will look for whether the source files changed OR the result
files are gone. If either is true, it rebuilds. If trying to rebuild just
one or few file's documentation, it is a lot easier just touching the
files.
> 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.
Cool. Docbuilding....
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:116>
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.
