#11817: Use sage_getdoc in sage interpreter when doing "?"
---------------------------+------------------------------------------------
Reporter: SimonKing | Owner: jason
Type: enhancement | Status: new
Priority: major | Milestone: sage-4.7.2
Component: misc | Keywords: sage_getdoc format embedding
Work_issues: | Upstream: N/A
Reviewer: | Author:
Merged: | Dependencies: #11815
---------------------------+------------------------------------------------
The purpose of this ticket is to fix two bugs.
'''__First problem__'''
Theere is a bug in `sage.misc.sagedoc.format`, that ironically makes that
`format?` does not show the documentation of `format`.
{{{
sage: from sage.misc.sagedoc import format
sage: format.__doc__
'\n Format Sage documentation ``s`` for viewing with IPython.\n\n
This calls ``detex`` on ``s`` to convert LaTeX commands to plain\n
text, and if ``s`` contains a string of the form "<<<obj>>>",\n then it
replaces it with the docstring for "obj".\n\n INPUT:\n\n - ``s`` -
string\n - ``embedded`` - boolean (optional, default False)\n\n
OUTPUT: string\n\n Set ``embedded`` equal to True if formatting for use
in the\n notebook; this just gets passed as an argument to
``detex``.\n\n EXAMPLES::\n\n sage: from sage.misc.sagedoc
import format\n sage:
identity_matrix(2).rook_vector.__doc__[115:184]\n \'Let `A` be a
general `m` by `n`\\n (0,1)-matrix with `m \\\\le n`. \'\n
sage: format(identity_matrix(2).rook_vector.__doc__[115:184])\n
\'Let A be a general m by n\\n (0,1)-matrix with m <= n.\\n\'\n\n If
the first line of the string is \'nodetex\', remove \'nodetex\' but\n
don\'t modify any TeX commands::\n \n sage: format("nodetex\\n`x
\\\\geq y`")\n \'\\n`x \\\\geq y`\'\n\n Testing a string
enclosed in triple angle brackets::\n\n sage:
format(\'<<<identity_matrix\')\n \'<<<identity_matrix\\n\'\n
sage: format(\'identity_matrix>>>\')\n \'identity_matrix>>>\\n\'\n
sage: format(\'<<<identity_matrix>>>\')[:28]\n \'Definition:
identity_matrix(\'\n '
sage: format?
Type: function
Base Class: <type 'function'>
String Form: <function format at 0xcc8a28>
Namespace: Interactive
File: /mnt/local/king/SAGE/broken/local/lib/python2.6/site-
packages/sage/misc/sagedoc.py
Definition: format(s, embedded=False)
Docstring:
<no docstring>
}}}
The problem is that the doc string contains `<<<obj>>>`, which means that
it is attempted to find and insert documentation for `obj` (which does not
exist).
'''__Suggestion__'''
Introduce a new directive `noreplace`, that avoids replacement of
`<<<obj>>>`. Or perhaps a better suggestion: Catch the error, and do not
replace if there is an error.
'''__Second problem__'''
If sage.misc.sagedoc.my_doc is applied to an object with a `_sage_doc_`
method then it uses it, without formatting. That means: No tex code is
turned into ascii art, and embedding information is not stripped.
'''__Suggestion__'''
Consequently use `sage.misc.sageinspect.sage_getdoc`.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/11817>
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.
