Opened 8 years ago

Last modified 4 years ago

#11817 closed enhancement

Use sage_getdoc in sage interpreter when doing "?" — at Initial Version

Reported by: SimonKing Owned by: jason
Priority: major Milestone: sage-5.1
Component: misc Keywords: sage_getdoc format embedding
Cc: vbraun Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: #11815 Stopgaps:

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.

Change History (0)

Note: See TracTickets for help on using tickets.