#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 SimonKing):
* status: needs_work => needs_review
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
> 9976-inspection_of_cython_v2.patch 9976_doc_fixes.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 9976_doc_fixes.patch
--
Comment:
I went for a different solution:
In sage_getargspec, if the object is no method or class but a class
instance (which is the case for decorated methods), then the source code
is taken, the definition is extracted, and then analyzed with
`_sage_getargspec_from_ast`. That approach will both work on Cython and
Python code, but to be on the safe side, I use `_sage_getargspec_cython`
if an error occurs.
With that, we have (doctested)
{{{
sage: P.<x,y> = QQ[]
sage: I = P*[x,y]
sage: sage_getargspec(I.groebner_basis)
ArgSpec(args=['self', 'algorithm', 'deg_bound', 'mult_bound', 'prot'],
varargs='args', keywords='kwds', defaults=('', None, None, False))
sage: cython("cpdef int foo(x,y) except -1: return 1")
sage: sage.misc.sageinspect.sage_getargspec(foo)
ArgSpec(args=['x', 'y'], varargs=None, keywords=None, defaults=None)
}}}
And the documentation of groebner_basis looks fine.
Of course, due to missing rights, I can not replace your patch version 2,
but I have replaced my patch version 1. It contains your additions,
though. Hence:
Apply trac_9976_decorated_generic_sigs_alternative.patch
9976-inspection_of_cython.patch 9976_doc_fixes.patch
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:72>
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.
