#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:112 SimonKing]
> "#indirect doctest" makes the sage coverage script happy. Namely, if you
do "sage -coverage" on some file, it will complain if any function or
method appears to not being tested in its doc string. Hence, it will
complain if in the `__str__` method of `Foo` you just have `sage: print
Foo`, because there is no `__str__` visible. But when you do `sage: print
Foo # indirect doctest`, then you assert that the invisible method ''is''
actually tested.
>
> Note that `#indirect doctest` does ''not'' influence how the doctest is
executed. It really is just for the coverage script.
>
> And yes, I do think that having an indirect test is necessary, since
what we want is to enable `sage_getsource` and `sage_getargspec` -- there
is no point in demonstrating that a certain object has an attribute
`_sage_doc_`, because that is not what is supposed to be called by the
user. Mind that the tests in the documentation are, at the same time,
examples.
Ok, I get that. But as opposed to your __str__ example, the doc-
examples/tests of decorators.py are on class documentation or in the
sage_wraps function. Therefore, the coverage script will see that the
class/function in question are in the test; it doesn't know my intention
to test the _sage_src_ or _sage_argspec_ fields anyway.
>
> > Yup, done (I think). It seems that decorators.py does not appear in
the reference manual; shouldn't that be changed (other ticket)? Do you
know how?
>
> Probably it should be a different ticket.
>
> How to add it:
>
> There are some hand-written `.rst` files in doc/en/reference/. Probably
you want to edit `misc.rst`, and insert the line
> {{{
> sage/misc/decorators
> }}}
> right before `sage/misc/cachefunc`. I guess that would be a good place,
because `cachefunc` provides decorators (even though they do not inherit
from the stuff in `decorators.py`).
>
> And that should already be it - after `sage -docbuild reference html`,
it should be there.
Thanks. I'll possibly look into this.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:117>
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.
