#9976: Decorated functions/methods have generic signature in documentation
-----------------------------+----------------------------------------------
Reporter: jsrn | Owner: mvngu
Type: enhancement | Status: needs_work
Priority: major | Milestone: sage-4.7
Component: documentation | Keywords: sphinx, documentation
Author: jsrn | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
-----------------------------+----------------------------------------------
Changes (by jsrn):
* status: needs_review => needs_work
Comment:
Replying to [comment:15 SimonKing]:
> How is the documentation of a class, method etc. actually obtained?
There is a method `get_doc` in sage_autodoc.py, but it was not called
when I expected it.
That is indeed surprising; I would have thought that was constructing the
documentation. You are aware that there are two get_doc functions: one in
the Documenter class (which is the father of all documenters), and the
overwritten in the ClassLevelDocumenter subclass? So if you were
monitoring Documenter's get_doc but were for the documentation of a method
or attribute, you would not see the call (I'm compiling, so I can't test
myself just now).
>
> Could it by the the work is done by the method `find_attr_docs()` of
`sphinx.pycode.ModuleAnalyzer`? That would be bad, because certainly it is
ignorant to methods such as `_sage_doc_()`!
>
> By consequence, if one has a method that is decorated by a cython class
(something that I plan for the cached_method decorator) then the
documentation will be that of the cython class, not that of the decorated
method.
>
> So, could it be that we have to replace `sphinx.pycode.ModuleAnalyzer`?
I hope not. For this ticket, I originally only looked at where the
argument string was formatted and that is in sage_autodoc.py.
ModuleAnalyzer is (only?) called on line 624 (unpatched) with the
following comment: "try to also get a source code analyzer for attribute
docs". If what you are suggesting above is true, we should be able to wrap
these lines with some exceptions in the cases where a _sage_doc attribute
has been set on the object.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:17>
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.
