#9976: Decorated functions/methods have generic signature in documentation
--------------------------------+-------------------------------------------
Reporter: jsrn | Owner: mvngu
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-4.7
Component: documentation | Keywords: sphinx, documentation, cython
inspection
Author: jsrn, Simon King | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
--------------------------------+-------------------------------------------
Changes (by newvalueoldvalue):
* keywords: sphinx, documentation => sphinx, documentation, cython
inspection
* status: needs_work => needs_review
* author: jsrn => jsrn, Simon King
Old description:
> Functions or methods that have been decorated by generic decorators such
> as sage.misc.decorators.options (moved from sage.misc.plot.options with
> Trac #9907) degrade documentation by reducing the signature for these
> callables to the generic "(*args, **kwargs)".
>
> See also the following sage.devel discussion:
> http://groups.google.com/group/sage-
> devel/browse_thread/thread/cbd888f0e60130ff/f533792113c45c2f
>
> Let's say that the advanced patch is the most useful and scalable. So
> ignore the first one and:
> Apply trac_9976_decorated_generic_sigs_alternative.patch
New description:
Functions or methods that have been decorated by generic decorators such
as sage.misc.decorators.options (moved from sage.misc.plot.options with
Trac #9907) degrade documentation by reducing the signature for these
callables to the generic "(*args, **kwargs)".
See also the following sage.devel discussion:
http://groups.google.com/group/sage-
devel/browse_thread/thread/cbd888f0e60130ff/f533792113c45c2f
Let's say that the advanced patch is the most useful and scalable. So
ignore the first one and:
Apply trac_9976_decorated_generic_sigs_alternative.patch
9976-inspection_of_cython.patch
--
Comment:
I added a patch that ought to be applied on top of the previous patch. In
`sage_autodoc.py`, it replaces calls to the `inspect` module by the
corresponding calls to the `sage.misc.sageinspect` module, and in
particular it uses `_sage_getdoct_unformatted` rather than asking for the
`__doc__` attribute.
Moreover, it makes `sage_getdoc` and friends a little more stable. Namely,
it catches the type error that resulted when calling `sage_getdoc` on a
class:
{{{
sage: class MyClass:
....: def _sage_doc_(self):
....: return "some doc"
....:
sage: sage.misc.sageinspect.sage_getdoc(MyClass())
'some doc\n'
sage: sage.misc.sageinspect.sage_getdoc(MyClass)
'' # This used to give a TypeError
}}}
Then, it also allows inspection of Cython code that is defined in an
interactive session. Its code is defined in a temporary file, thus, not in
the sage library tree. But the old algorithm would only try to find files
in the library tree.
{{{
sage: cython('''cpdef test_funct(x,y): return''')
sage: sage_getsourcelines(test_funct)
(['cpdef test_funct(x,y): return\n'], 6)
}}}
I am building the documentation from scratch. If it works then I can give
your patch a positive review. And I hope there will be a reviewer for my
patch as well... But careful, my patch modifies something in the sage
library, so, doc tests are needed.
For the patchbot:
Apply trac_9976_decorated_generic_sigs_alternative.patch
9976-inspection_of_cython.patch
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:20>
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.
