#11817: Use sage_getdoc in sage interpreter when doing "?"
------------------------------------------------+---------------------------
Reporter: SimonKing | Owner: jason
Type: enhancement | Status:
positive_review
Priority: major | Milestone: sage-5.1
Component: misc | Resolution:
Keywords: sage_getdoc format embedding | Work issues:
Report Upstream: N/A | Reviewers: Volker Braun
Authors: Simon King | Merged in:
Dependencies: #11815 | Stopgaps:
------------------------------------------------+---------------------------
Changes (by vbraun):
* status: needs_review => positive_review
* reviewer: => Volker Braun
* milestone: sage-5.0 => sage-5.1
Old description:
> 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`.
New description:
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`.
Apply [attachment:trac11817_question_mark_using_sage_getdoc.2.patch]
--
Comment:
Patch doesn't apply to sage-5.0.rc0 because some docstring issue. Since
its a trivial change I uploaded a rediffed patch.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/11817#comment:5>
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.
