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`

.

**Note:**See TracTickets for help on using tickets.