Format Sage documentation for viewing with IPython and the notebook

AUTHORS:

  • William Stein (2005): initial version.
  • Nick Alexander (2007): nodetex functions
  • Nick Alexander (2008): search_src, search_def improvements
  • Martin Albrecht (2008-03-21): parse LaTeX description environments in sagedoc
  • John Palmieri (2009-04-11): fix for #5754 plus doctests
  • Dan Drake (2009-05-21): refactor search_* functions, use system ‘find’ instead of sage -grep
  • John Palmieri (2009-06-28): don’t use ‘find’ – use Python (os.walk, re.search) instead.
sage.misc.sagedoc._rmcmd(s, cmd, left='', right='')

Remove the LaTeX command cmd from the string s. This function is used by detex.

INPUT:

  • s - (string) string from which to remove the command
  • cmd - (string) command to be removed. This should be a command which takes a single argument, like ‘emph’ or ‘url’; the command is removed, but its argument is not.
  • left, right - (string, optional, default ‘’) add these strings at the left and right ends of the command. See the examples.

EXAMPLES:

sage: from sage.misc.sagedoc import _rmcmd
sage: _rmcmd('Check out \url{http://www.sagemath.org}.', 'url')
'Check out http://www.sagemath.org.'
sage: _rmcmd('Text in \emph{italics} looks like this.', 'emph', '*', '*')
'Text in *italics* looks like this.'
sage: _rmcmd('This is a \very{silly} example.', 'very', right='!?')
'This is a silly!? example.'
sage.misc.sagedoc._search_src_or_doc(what, string, extra1='', extra2='', extra3='', extra4='', extra5='', interact=True, path_re='', module='sage')

Search the Sage library or documentation for lines containing string and possibly some other terms. This function is used by search_src(), search_doc(), and search_def().

INPUT:

  • what: either 'src' or 'doc', according to whether you are searching the documentation or source code.
  • the rest of the input is the same as search_src(), search_doc(), and search_def().

OUTPUT:

If interact is False, a string containing the results; otherwise, there is no output and the results are presented according to whether you are using the notebook or command-line interface. In the command-line interface, each line of the results has the form filename:num:line of code, where num is the line number in filename and line of code is the line that matched your search terms.

EXAMPLES:

sage: from sage.misc.sagedoc import _search_src_or_doc
sage: print _search_src_or_doc('src', 'matrix\(', 'incidence_structures', 'self', '^combinat', interact=False) # random # long time
misc/sagedoc.py:        sage: _search_src_or_doc('src', 'matrix(', 'incidence_structures', 'self', '^combinat', interact=False)
combinat/designs/incidence_structures.py:        M1 = self.incidence_matrix()
combinat/designs/incidence_structures.py:        A = self.incidence_matrix()
combinat/designs/incidence_structures.py:        M = transpose(self.incidence_matrix())
combinat/designs/incidence_structures.py:    def incidence_matrix(self):
combinat/designs/incidence_structures.py:        A = self.incidence_matrix()
combinat/designs/incidence_structures.py:        A = self.incidence_matrix()
combinat/designs/incidence_structures.py:        #A = self.incidence_matrix()

TESTS:

The examples are nice, but marking them “random” means we’re not really testing if the function works, just that it completes. These tests aren’t perfect, but are reasonable.

sage: len(_search_src_or_doc('src', 'matrix\(', 'incidence_structures', 'self', 'combinat', interact=False).splitlines()) > 1
True

sage: 'abvar/homology' in _search_src_or_doc('doc', 'homology', 'variety', interact=False)
True

sage: 'divisors' in _search_src_or_doc('src', '^ *def prime', interact=False)
True
sage.misc.sagedoc.detex(s, embedded=False)

This strips LaTeX commands from a string; it is used by the format function to process docstrings for display from the command line interface.

INPUT:

  • s - string
  • embedded - boolean (optional, default False)

If embedded is False, then do the replacements in both math_substitutes and nonmath_substitutes. If True, then only do nonmath_substitutes.

OUTPUT: string

EXAMPLES:

sage: from sage.misc.sagedoc import detex
sage: detex(r'Some math: `n \geq k`.  A website: \url{sagemath.org}.')
'Some math: `n >= k`.  A website: sagemath.org.'
sage: detex(r'More math: `x \mapsto y`.  {\bf Bold face}.')
'More math: `x  |-->  y`.  { Bold face}.'
sage: detex(r'`a, b, c, \ldots, z`')
'`a, b, c, ..., z`'
sage: detex(r'`a, b, c, \ldots, z`', embedded=True)
'`a, b, c, \\\\ldots, z`'
sage.misc.sagedoc.format(s, embedded=False)

Format Sage documentation s for viewing with IPython.

This calls detex on s to convert LaTeX commands to plain text, and if s contains a string of the form “<<<obj>>>”, then it replaces it with the docstring for “obj”.

INPUT:

  • s - string
  • embedded - boolean (optional, default False)

OUTPUT: string

Set embedded equal to True if formatting for use in the notebook; this just gets passed as an argument to detex.

EXAMPLES:

sage: from sage.misc.sagedoc import format
sage: identity_matrix(2).rook_vector.__doc__[115:184]
'Let `A` be a general `m` by `n`\n        (0,1)-matrix with `m \\le n`. '
sage: format(identity_matrix(2).rook_vector.__doc__[115:184])
'Let `A` be a general `m` by `n`\n        (0,1)-matrix with `m <= n`. '

If the first line of the string is ‘nodetex’, remove ‘nodetex’ but don’t modify any TeX commands:

sage: format("nodetex\n`x \\geq y`")
'\n`x \\geq y`'

Testing a string enclosed in triple angle brackets:

sage: format('<<<identity_matrix')
'<<<identity_matrix'
sage: format('identity_matrixsage:')
'identity_matrixsage:'
sage: format('<<<identity_matrixsage:')[:28]
'\nDefinition: identity_matrix'
sage.misc.sagedoc.format_search_as_html(what, r, search)

Format the output from search_src, search_def, or search_doc as html, for use in the notebook.

INPUT:

  • what - (string) what was searched (source code or documentation)
  • r - (string) the results of the search
  • search - (string) what was being searched for

This function parses r: it should have the form FILENAME: string where FILENAME is the file in which the string that matched the search was found. Everything following the first colon is ignored; we just use the filename. If FILENAME ends in ‘.html’, then this is part of the documentation; otherwise, it is in the source code. In either case, an appropriate link is created.

EXAMPLES:

sage: from sage.misc.sagedoc import format_search_as_html
sage: format_search_as_html('Source', 'algebras/steenrod_algebra_element.py:        an antihomomorphism: if we call the antipode `c`, then', 'antipode antihomomorphism')
'<html><font color="black"><h2>Search Source: antipode antihomomorphism</h2></font><font color="darkpurple"><ol><li><a href="/src/algebras/steenrod_algebra_element.py"><tt>algebras/steenrod_algebra_element.py</tt></a>\n</ol></font></html>'
sage: format_search_as_html('Other', 'html/en/reference/sage/algebras/steenrod_algebra_element.html:an antihomomorphism: if we call the antipode <span class="math">c</span>, then', 'antipode antihomomorphism')
'<html><font color="black"><h2>Search Other: antipode antihomomorphism</h2></font><font color="darkpurple"><ol><li><a href="/doc/live/reference/sage/algebras/steenrod_algebra_element.html"><tt>reference/sage/algebras/steenrod_algebra_element.html</tt></a>\n</ol></font></html>'
sage.misc.sagedoc.format_src(s)

Format Sage source code s for viewing with IPython.

If s contains a string of the form “<<<obj>>>”, then it replaces it with the source code for “obj”.

INPUT: s - string

OUTPUT: string

EXAMPLES:

sage: from sage.misc.sagedoc import format_src
sage: format_src('unladen swallow')
'unladen swallow'
sage: format_src('<<<Sqsage:')[5:15]
'Sq(*nums):'
sage.misc.sagedoc.my_getdoc(obj)

Retrieve the documentation for obj.

INPUT: obj - a Sage object, function, etc.

OUTPUT: its documentation (string)

EXAMPLES:

sage: from sage.misc.sagedoc import my_getdoc
sage: s = my_getdoc(identity_matrix)
sage: type(s)
<type 'str'>
sage.misc.sagedoc.my_getsource(obj, is_binary)

Retrieve the source code for obj.

INPUT:

  • obj - a Sage object, function, etc.
  • is_binary - (boolean) ignored argument.

OUTPUT: its documentation (string)

EXAMPLES:

sage: from sage.misc.sagedoc import my_getsource
sage: s = my_getsource(identity_matrix, True)
sage: s[:19]
'def identity_matrix'
sage.misc.sagedoc.search_def(name, extra1='', extra2='', extra3='', extra4='', extra5='', interact=True, path_re='', module='sage')

Search Sage library source code for function definitions containing name. The search is not case sensitive.

INPUT:

  • name - a string to find in the names of functions in the Sage source code.
  • extra1, ..., extra4 - additional strings to require, as in search_src().
  • interact (optional, default True) - if False, return a string with all the matches. Otherwise, this function returns None, and the results are displayed appropriately, according to whether you are using the notebook or the command-line interface. You should not ordinarily need to use this.
  • path_re (optional, default ‘’) - regular expression which the filename (including the path) must match.
  • module (optional, default ‘sage’) - the module in which to search. The default is ‘sage’, the entire Sage library. If module doesn’t start with “sage”, then the links in the notebook output may not function.

The string and extraN arguments are treated as regular expressions, as is path_re, and errors will be raised if they are invalid. The matches will always be case-insensitive.

In the command-line interface, each line of the results has the form filename:num:line of code, where num is the line number in filename and line of code is the line that matched your search terms.

Note

The regular expression used by this function only finds function definitions that are preceded by spaces, so if you use tabs on a “def” line, this function will not find it. As tabs are not allowed in Sage library code, this should not be a problem.

Note

The extraN parameters are present only because search_src(string, *extras, interact=False) is not parsed correctly by Python 2.6; see http://bugs.python.org/issue1909.

EXAMPLES:

sage: print search_def("fetch", interact=False) # random # long time
matrix/matrix0.pyx:    cdef fetch(self, key):
matrix/matrix0.pxd:    cdef fetch(self, key)

sage: print search_def("fetch", path_re="pyx", interact=False) # random # long time
matrix/matrix0.pyx:    cdef fetch(self, key):
sage.misc.sagedoc.search_doc(string, extra1='', extra2='', extra3='', extra4='', extra5='', interact=True, path_re='')

Search Sage HTML documentation for lines containing string. The search is not case sensitive.

The file paths in the output are relative to $SAGE_ROOT/devel/sage/doc/output.

INPUT:

  • string - a string to find in the Sage documentation.
  • extra1, ..., extra5 - additional strings to require when searching. Lines must match all of these, as well as string.
  • interact (optional, default True) - if False, return a string with all the matches. Otherwise, this function returns None, and the results are displayed appropriately, according to whether you are using the notebook or the command-line interface. You should not ordinarily need to use this.
  • path_re (optional, default ‘’) - regular expression which the filename (including the path) must match.

The string and extraN arguments are treated as regular expressions, as is path_re, and errors will be raised if they are invalid. The matches will always be case-insensitive.

In the command-line interface, each line of the results has the form filename:num:line of code, where num is the line number in filename and line of code is the line that matched your search terms. This may not be very helpful for this function, but we include it anyway.

Note

The extraN parameters are present only because search_src(string, *extras, interact=False) is not parsed correctly by Python 2.6; see http://bugs.python.org/issue1909.

EXAMPLES:

sage: search_doc('creates a polynomial', path_re='tutorial', interact=False) # random
html/en/tutorial/tour_polynomial.html:<p>This creates a polynomial ring and tells Sage to use (the string)
sage.misc.sagedoc.search_src(string, extra1='', extra2='', extra3='', extra4='', extra5='', interact=True, path_re='', module='sage')

Search Sage library source code for lines containing string. The search is not case sensitive.

INPUT:

  • string - a string to find in the Sage source code.
  • extra1, ..., extra5 - additional strings to require when searching. Lines must match all of these, as well as string.
  • interact (optional, default True) - if False, return a string with all the matches. Otherwise, this function returns None, and the results are displayed appropriately, according to whether you are using the notebook or the command-line interface. You should not ordinarily need to use this.
  • path_re (optional, default ‘’) - regular expression which the filename (including the path) must match.
  • module (optional, default ‘sage’) - the module in which to search. The default is ‘sage’, the entire Sage library. If module doesn’t start with “sage”, then the links in the notebook output may not function.

The file paths in the output are relative to $SAGE_ROOT/devel/sage/. In the command-line interface, each line of the results has the form filename:num:line of code, where num is the line number in filename and line of code is the line that matched your search terms.

The string and extraN arguments are treated as regular expressions, as is path_re, and errors will be raised if they are invalid. The matches will always be case-insensitive.

Note

The extraN parameters are present only because search_src(string, *extras, interact=False) is not parsed correctly by Python 2.6; see http://bugs.python.org/issue1909.

EXAMPLES:

First note that without using interact=False, this function produces no output, while with interact=False, the output is a string. These examples almost all use this option.

You can search for “matrix” by typing search_src("matrix"). This particular search will produce many results:

sage: len(search_src("matrix", interact=False).splitlines()) # random # long time
9522

You can restrict to the Sage calculus code with search_src("matrix", module="sage.calculus"), and this produces many fewer results:

sage: len(search_src("matrix", module="sage.calculus", interact=False).splitlines()) # random
26

Note that you can do tab completion on the module string. Another way to accomplish a similar search:

sage: len(search_src("matrix", path_re="calc", interact=False).splitlines()) # random
26

The following produces an error because the string ‘fetch(‘ is a malformed regular expression:

sage: print search_src(" fetch(", "def", interact=False)
...
error: unbalanced parenthesis

To fix this, escape the parenthesis with a backslash:

sage: print search_src(" fetch\(", "def", interact=False) # random # long time
matrix/matrix0.pyx:    cdef fetch(self, key):
matrix/matrix0.pxd:    cdef fetch(self, key)

sage: print search_src(" fetch\(", "def", "pyx", interact=False) # random # long time
matrix/matrix0.pyx:    cdef fetch(self, key):

A little recursive narcissism: let’s do a doctest that searches for this function’s doctests. Note that you can’t put “sage:” in the doctest string because it will get replaced by the Python “>>>” prompt.

sage: print search_src('^ *sage[:] .*search_src\(', interact=False) # long time
misc/sagedoc.py:... len(search_src("matrix", interact=False).splitlines()) # random # long time
misc/sagedoc.py:... len(search_src("matrix", module="sage.calculus", interact=False).splitlines()) # random
misc/sagedoc.py:... len(search_src("matrix", path_re="calc", interact=False).splitlines()) # random
misc/sagedoc.py:... print search_src(" fetch(", "def", interact=False)
misc/sagedoc.py:... print search_src(" fetch\(", "def", interact=False) # random # long time
misc/sagedoc.py:... print search_src(" fetch\(", "def", "pyx", interact=False) # random # long time
misc/sagedoc.py:... print search_src('^ *sage[:] .*search_src\(', interact=False) # long time
misc/sagedoc.py:... len(search_src("matrix", interact=False).splitlines()) > 9000 # long time
misc/sagedoc.py:... print search_src('matrix', 'column', 'row', 'sub', 'start', 'index', interact=False) # random # long time

TESTS:

As of this writing, there are about 9500 lines in the Sage library that contain “matrix”; it seems safe to assume we’ll continue to have over 9000 such lines:

sage: len(search_src("matrix", interact=False).splitlines()) > 9000 # long time
True

Check that you can pass 5 parameters:

sage: print search_src('matrix', 'column', 'row', 'sub', 'start', 'index', interact=False) # random # long time
matrix/matrix0.pyx:598:        Get The 2 x 2 submatrix of M, starting at row index and column
matrix/matrix0.pyx:607:        Get the 2 x 3 submatrix of M starting at row index and column index
matrix/matrix0.pyx:924:        Set the 2 x 2 submatrix of M, starting at row index and column
matrix/matrix0.pyx:933:        Set the 2 x 3 submatrix of M starting at row index and column

Previous topic

Random testing.

Next topic

Miscellaneous arithmetic functions

This Page