#9976: Decorated functions/methods have generic signature in documentation
--------------------------------+-------------------------------------------
Reporter: jsrn | Owner: jsrn
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: Simon King | Merged:
Work_issues: |
--------------------------------+-------------------------------------------
Comment(by SimonKing):
I think I got it to work.
I inserted at the end of sage/misc/latex.py:
{{{
from sage.misc.cachefunc import cached_function
def test1():
"This is a docstring for test1"
pass
test2 = cached_function(test1)
@cached_function
def test3():
"This is a docstring for test3"
pass
class TestClass:
"Some class documentation"
def _sage_doc_(self):
return "Some instance definition"
def __call__(self):
return 1
TestInstance = TestClass()
}}}
Then, I changed one line in doc/common/sage_autodoc.py, namely in
`FunctionDocumenter.can_document_member()`: Instead of returning
{{{
return isinstance(member, (FunctionType, BuiltinFunctionType))
}}}
it should return
{{{
return isinstance(member, (FunctionType, BuiltinFunctionType)) or
(isclassinstance(member) and
_sage_getdoc_unformatted(member)!=_sage_getdoc_unformatted(member.__class__))
}}}
Then, in the reference page for sage/misc/latex.py, I find
{{{
class sage.misc.latex.TestClass¶
Some class documentation
sage.misc.latex.TestInstance()¶
Some instance definition
}}}
and
{{{
sage.misc.latex.test1()¶
This is a docstring for test1
sage.misc.latex.test2()¶
This is a docstring for test1
sage.misc.latex.test3()¶
This is a docstring for test3
}}}
`test2 = cached_function(test1)` is not the recommended way of creating a
cached function: It should be used as in the definition of test3. So, I
think it is ok that the documentation of test1 appears twice. The above is
just what we want, right?
I am preparing a patch now, and posting in a few minutes.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:138>
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.
