### Navigation

- index
- modules |
- next |
- previous |
- Miscellaneous »

# 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.
- Simon King (2011-09): Use os.linesep, avoid destruction of embedding information, enable nodetex in a docstring. Consequently use sage_getdoc.

TESTS:

Check that argspecs of extension function/methods appear correctly, see trac ticket #12849:

    sage: docfilename = os.path.join(SAGE_DOC, 'output', 'html', 'en', 'reference', 'calculus', 'sage', 'symbolic', 'expression.html')
    sage: for line in open(docfilename):
    ...       if "#sage.symbolic.expression.Expression.N" in line:
    ...           print line
    <tt class="descname">N</tt><big>(</big><em>prec=None</em>, <em>digits=None</em>, <em>algorithm=None</em><big>)</big>...

`sage.misc.sagedoc.``constructions`

  Sage constructions. Attempts to answer the question “How do I construct ... in Sage?”

  EXAMPLES:

      sage: constructions()  # indirect doctest, not tested

`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.\n'
      sage: detex(r'More math: `x \mapsto y`.  {\bf Bold face}.')
      'More math: x  |-->  y.  { Bold face}.\n'
      sage: detex(r'`a, b, c, \ldots, z`')
      'a, b, c, ..., z\n'
      sage: detex(r'`a, b, c, \ldots, z`', embedded=True)
      '`a, b, c, \\ldots, z`'

`sage.misc.sagedoc.``developer`

  The Sage developer’s guide. Learn to develop programs for Sage.

  EXAMPLES:

      sage: developer()  # indirect doctest, not tested

`sage.misc.sagedoc.``format`(s, embedded=False)

  noreplace Format Sage documentation `s` for viewing with IPython.

  This calls `detex` on `s` to convert LaTeX commands to plain text, unless the directive `nodetex` is given in the first line of the string.

  Also, if `s` contains a string of the form `<<<obj>>>`, then it replaces it with the docstring for `obj`, unless the directive `noreplace` is given in the first line. If an error occurs under the attempt to find the docstring for `obj`, then the substring `<<<obj>>>` is preserved.

  Directives must be separated by a comma.

  NOTE:

  If the first line of the string provides embedding information, which is the case for doc strings from extension modules, then the first line will not be changed.

  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 an `m` by `n` (0,1)-matrix with `m \\le n`. We identify\n'
      sage: format(identity_matrix(2).rook_vector.__doc__[115:184])
      '   Let A be an m by n (0,1)-matrix with m <= n. We identify\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`")
      '`x \\geq y`'

  Testing a string enclosed in triple angle brackets:

      sage: format('<<<identity_matrix')
      '<<<identity_matrix\n'
      sage: format('identity_matrix>>>')
      'identity_matrix>>>\n'
      sage: format('<<<identity_matrix>>>')[:28]
      'Definition: identity_matrix('

  TESTS:

  We check that the todo Sphinx extension is correctly activated:

      sage: sage.misc.sagedoc.format(sage.combinat.ranker.on_fly.__doc__)
      "   Returns ...  Todo: add tests as in combinat::rankers\n"

  We check that the embedding information of a doc string from an extension module is preserved, even if it is longer than a usual line. Moreover, a `nodetex` directive in the first “essential” line of the doc string is recognised. That has been implemented in trac ticket #11815:

      sage: r = 'File: _local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx (starting at line 6)\nnodetex\nsome doc for a cython method\n`x \geq y`'
      sage: print format(r)
      File: _local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx (starting at line 6)
      <BLANKLINE>
      some doc for a cython method
      `x \geq y`

  In the following use case, the `nodetex` directive would have been ignored prior to #11815:

      sage: cython_code = ["def testfunc(x):",
      ... "    '''",
      ... "    nodetex",
      ... "    This is a doc string with raw latex",
      ... "",
      ... "    `x \\geq y`",
      ... "    '''",
      ... "    return -x"]
      sage: cython('\n'.join(cython_code))
      sage: from sage.misc.sageinspect import sage_getdoc
      sage: print sage_getdoc(testfunc)
      <BLANKLINE>
          This is a doc string with raw latex
      <BLANKLINE>
          `x \geq y`
      <BLANKLINE>

  We check that the `noreplace` directive works, even combined with `nodetex` and an embedding information (see trac ticket #11817):

      sage: print format('File: bla.py (starting at line 1)\nnodetex, noreplace\n<<<identity_matrix>>>`\\not= 0`')
      File: bla.py (starting at line 1)
      <<<identity_matrix>>>`\not= 0`

  If replacement is impossible, then no error is raised:

      sage: print format('<<<bla\n<<<bla>>>\n<<<identity_matrix>>>')
      <<<bla <<<bla>>>
      <BLANKLINE>
      Definition: identity_matrix(ring, n=0, sparse=False)
      <BLANKLINE>
      This function is available as identity_matrix(...) and
      matrix.identity(...).
      <BLANKLINE>
         Return the n x n identity matrix over the given ring.
      ...

`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" target="_blank"><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" target="_blank"><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('<<<Sq>>>')[5:15]
      'Sq(*nums):'

`sage.misc.sagedoc.``help`(module=None)

  If there is an argument `module`, print the Python help message for `module`. With no argument, print a help message about getting help in Sage.

  EXAMPLES:

      sage: help()
      Welcome to Sage ...

`sage.misc.sagedoc.``manual`

  The Sage reference manual.

  EXAMPLES:

      sage: reference() # indirect doctest, not tested
      sage: manual() # indirect doctest, not tested

`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[15:34]
      'def identity_matrix'

`sage.misc.sagedoc.``process_dollars`(s)

  Replace dollar signs with backticks.

  More precisely, do a regular expression search. Replace a plain dollar sign ($) by a backtick (`). Replace an escaped dollar sign (\$) by a dollar sign ($). Don’t change a dollar sign preceded or followed by a backtick (`$ or $`), because of strings like “`$HOME`”. Don’t make any changes on lines starting with more spaces than the first nonempty line in `s`, because those are indented and hence part of a block of code or examples.

  This also doesn’t replaces dollar signs enclosed in curly braces, to avoid nested math environments.

  EXAMPLES:

      sage: from sage.misc.sagedoc import process_dollars
      sage: process_dollars('hello')
      'hello'
      sage: process_dollars('some math: $x=y$')
      'some math: `x=y`'

  Replace \$ with $, and don’t do anything when backticks are involved:

      sage: process_dollars(r'a ``$REAL`` dollar sign: \$')
      'a ``$REAL`` dollar sign: $'

  Don’t make any changes on lines indented more than the first nonempty line:

      sage: s = '\n first line\n     indented $x=y$'
      sage: s == process_dollars(s)
      True

  Don’t replace dollar signs enclosed in curly braces:

      sage: process_dollars(r'f(n) = 0 \text{ if $n$ is prime}')
      'f(n) = 0 \\text{ if $n$ is prime}'

  This is not perfect:

      sage: process_dollars(r'$f(n) = 0 \text{ if $n$ is prime}$')
      '`f(n) = 0 \\text{ if $n$ is prime}$'

  The regular expression search doesn’t find the last $. Fortunately, there don’t seem to be any instances of this kind of expression in the Sage library, as of this writing.

`sage.misc.sagedoc.``process_extlinks`(s, embedded=False)

  In docstrings at the command line, process markup related to the Sphinx extlinks extension. For example, replace `:trac:`NUM`` with `http://trac.sagemath.org/NUM`, and similarly with `:python:TEXT` and `:wikipedia:TEXT`, looking up the url from the dictionary `extlinks` in SAGE_DOC/common/conf.py. If `TEXT` is of the form `blah <LINK>`, then it uses `LINK` rather than `TEXT` to construct the url.

  In the notebook, don’t do anything: let sphinxify take care of it.

  INPUT:

  - `s` – string, in practice a docstring
  - `embedded` – boolean (optional, default False)

  This function is called by `format()`, and if in the notebook, it sets `embedded` to be `True`, otherwise `False`.

  EXAMPLES:

      sage: from sage.misc.sagedoc import process_extlinks
      sage: process_extlinks('See :trac:`1234`, :wikipedia:`Wikipedia <Sage_(mathematics_software)>`, and :trac:`4321` ...')
      'See http://trac.sagemath.org/1234, http://en.wikipedia.org/wiki/Sage_(mathematics_software), and http://trac.sagemath.org/4321 ...'
      sage: process_extlinks('See :trac:`1234` for more information.', embedded=True)
      'See :trac:`1234` for more information.'
      sage: process_extlinks('see :python:`Implementing Descriptors <reference/datamodel.html#implementing-descriptors>` ...')
      'see http://docs.python.org/release/.../reference/datamodel.html#implementing-descriptors ...'

`sage.misc.sagedoc.``process_mathtt`(s)

  Replace \mathtt{BLAH} with BLAH in the command line.

  INPUT:

  - `s` - string, in practice a docstring

  This function is called by `format()`.

  EXAMPLES:

      sage: from sage.misc.sagedoc import process_mathtt
      sage: process_mathtt(r'e^\mathtt{self}')
      'e^self'

`sage.misc.sagedoc.``reference`

  The Sage reference manual.

  EXAMPLES:

      sage: reference() # indirect doctest, not tested
      sage: manual() # indirect doctest, not tested

`sage.misc.sagedoc.``search_def`(name, extra1='', extra2='', extra3='', extra4='', extra5='', **kwds)

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

  INPUT: same as for `search_src()`.

  OUTPUT: same as for `search_src()`.

  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.

  EXAMPLES:

  See the documentation for `search_src()` for more 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='', **kwds)

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

  The file paths in the output are relative to `$SAGE_DOC/output`.

  INPUT: same as for `search_src()`.

  OUTPUT: same as for `search_src()`.

  EXAMPLES:

  See the documentation for `search_src()` for more 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)

  If you search the documentation for ‘tree’, then you will get too many results, because many lines in the documentation contain the word ‘toctree’. If you use the `whole_word` option, though, you can search for ‘tree’ without returning all of the instances of ‘toctree’. In the following, since `search_doc('tree', interact=False)` returns a string with one line for each match, counting the length of `search_doc('tree', interact=False).splitlines()` gives the number of matches.

      sage: len(search_doc('tree', interact=False).splitlines()) > 4000  # long time
      True
      sage: len(search_doc('tree', whole_word=True, interact=False).splitlines()) < 1000  # long time
      True

`sage.misc.sagedoc.``search_src`(string, extra1='', extra2='', extra3='', extra4='', extra5='', **kwds)

  Search Sage library source code for lines containing `string`. The search is 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`.
  - `whole_word` (optional, default False) - if True, search for `string` and `extra1` (etc.) as whole words only. This assumes that each of these arguments is a single word, not a regular expression, and it might have unexpected results if used with regular expressions.
  - `ignore_case` (optional, default False) - if True, perform a case-insensitive search
  - `multiline` (optional, default False) - if True, search more than one line at a time. In this case, print any matching file names, but don’t print line numbers.
  - `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.

  OUTPUT: If `interact` is False, then return a string with all of the matches, separated by newlines. On the other hand, if `interact` is True (the default), there is no output. Instead: at the command line, the search results are printed on the screen in the form `filename:line_number:line of text`, showing the filename in which each match occurs, the line number where it occurs, and the actual matching line. (If `multiline` is True, then only the filename is printed for each match.) The file paths in the output are relative to `$SAGE_SRC`. In the notebook, each match produces a link to the actual file in which it occurs.

  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 be case-sensitive unless `ignore_case` is True.

  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, so that they have something to which to compare their output.

  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()) > 15
      True

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

      sage: print search_src(" fetch(", "def", interact=False)
      Traceback (most recent call last):
      ...
      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):

  As noted above, the search is case-sensitive, but you can make it case-insensitive with the ‘ignore_case’ key word:

      sage: s = search_src('Matrix', path_re='matrix', interact=False); s.find('x') > 0
      True

      sage: s = search_src('MatRiX', path_re='matrix', interact=False); s.find('x') > 0
      False

      sage: s = search_src('MatRiX', path_re='matrix', interact=False, ignore_case=True); s.find('x') > 0
      True

  Searches are by default restricted to single lines, but this can be changed by setting `multiline` to be True. In the following, since `search_src(string, interact=False)` returns a string with one line for each match, counting the length of `search_src(string, interact=False).splitlines()` gives the number of matches.

      sage: len(search_src('log', 'derivative', interact=False).splitlines()) < 10
      True
      sage: len(search_src('log', 'derivative', interact=False, multiline=True).splitlines()) > 30
      True

  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()) > 15
      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:... s = search_src('Matrix', path_re='matrix', interact=False); s.find('x') > 0
      misc/sagedoc.py:... s = search_src('MatRiX', path_re='matrix', interact=False); s.find('x') > 0
      misc/sagedoc.py:... s = search_src('MatRiX', path_re='matrix', interact=False, ignore_case=True); s.find('x') > 0
      misc/sagedoc.py:... len(search_src('log', 'derivative', interact=False).splitlines()) < 10
      misc/sagedoc.py:... len(search_src('log', 'derivative', interact=False, multiline=True).splitlines()) > 30
      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

`sage.misc.sagedoc.``tutorial`

  The Sage tutorial. To get started with Sage, start here.

  EXAMPLES:

      sage: tutorial()  # indirect doctest, not tested

### Navigation

- index
- modules |
- next |
- previous |
- Miscellaneous »