Ticket #6840: trac_6840-notebook-documentation-v4.patch

File trac_6840-notebook-documentation-v4.patch, 167.1 KB (added by timdumol, 12 years ago)

Version 4. Brought up cell.py coverage to almost 100%, except for 2 functions.

  • doc/en/reference/notebook.rst 

    # HG changeset patch
# User Mitesh Patel <qed777@gmail.com>
# Date 1249912330 25200
# Node ID 6b319da23983c6adc44e752c2471f4c7ed138e85
# Parent  832b4605800675c661715a511041de9ea77904a7
#6840 Fixes documentation for sage.server.*

diff -r 832b46058006 -r 6b319da23983 doc/en/reference/notebook.rst
    a b  
    1111   sage/server/notebook/worksheet
    1212   sage/server/notebook/twist
    1313
     14   sage/server/notebook/interact
    1415   sage/server/notebook/js
    1516   sage/server/notebook/config
    1617   sage/server/notebook/css
     18   sage/server/notebook/docHTMLProcessor
     19   sage/server/notebook/template
    1720
     21   sage/server/misc
    1822   sage/server/support
    1923   sage/server/introspect
    2024

  • sage/server/introspect.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/introspect.py
    a b  
    11"""
    2 Sage Notebook: Introspection
     2Sage Notebook Introspection
    33
     4"""
     5
     6"""
    47TODO: - add support for grabbing source code from Pyrex functions
    58(even if not perfect is better than nothing). - PNG or MathML
    69output format for docstring

  • sage/server/misc.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/misc.py
    a b  
    11"""
    2 Misc code useful for the notebook
     2Miscellaneous Notebook Functions
    33"""
    44
    55#############################################################################
    … …  
    1919    web browser to a certain URL.
    2020
    2121    INPUT:
    22         address -- a computer address
    23         port -- a port number
    24         secure -- bool (default: False); whether to put HTTP or HTTPS
    25         path -- path after the port.
    2622
    27     EXAMPLES:   
     23    - ``address`` -- a string; a computer address or name
     24   
     25    - ``port`` -- an int; a port number
     26   
     27    - ``secure`` -- a bool (default: False); whether to prefix the URL
     28      with 'http' or 'https'
     29   
     30    - ``path`` -- a string; the URL's path following the port.
     31   
     32    EXAMPLES::
     33
    2834        sage: sage.server.misc.print_open_msg('localhost', 8000, True)
    2935        ****************************************************
    3036        *                                                  *
    … …  
    7278import socket
    7379def find_next_available_port(start, max_tries=100, verbose=False):
    7480    """
    75     Find the next port that is available to be used, where available means that
    76     currently trying to connect to it gives a 'Connection refused'
    77     error message.
     81    Find for the next available port, that is, a port for which a
     82    current connection attempt returns a 'Connection refused' error
     83    message.  If no port is found, raise a RuntimError exception.
    7884
    7985    INPUT:
    80         start -- integer; a port number to start scanning for a new port at
    81         max_tries -- integer (default: 100); how many ports to try
    82         verbose -- bool (default: True); whether or not to print out info about scanning results.
     86
     87       - ``start`` - an int; the starting port number for the scan
     88
     89       - ``max_tries`` - an int (default: 100); how many ports to scan
     90
     91       - ``verbose`` - a bool (default: True); whether to print information
     92         about the scan
    8393
    8494    OUTPUT:
    85         an integer, or if no port is found, raises a RuntimError exception
    8695
    87     EXAMPLES:
     96    - an int - the port number
     97
     98    EXAMPLES::
     99
    88100        sage: sage.server.misc.find_next_available_port(9000, verbose=False)   # random output -- depends on network
    89101        9002
    90102    """

  • sage/server/notebook/avatars.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/avatars.py
    a b  
    2828    OUTPUT:
    2929        string -- 'invalid_user', 'admin', 'user'
    3030   
    31     EXAMPLES:
     31    EXAMPLES::
     32
    3233        sage: import sage.server.notebook.twist
    3334        sage: import sage.server.notebook.avatars as avatars
    3435        sage: avatars.user_type(avatars.FailedLogin('fake'))

  • sage/server/notebook/cell.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/cell.py
    a b  
    251251
    252252    def plain_text(self, prompts=False):
    253253        """
     254        Returns a plain text version of self.
     255       
    254256        EXAMPLES::
    255257       
    256258            sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None)
    … …  
    261263
    262264    def edit_text(self):
    263265        """
     266        Returns the text to be displayed in the Edit window.
     267       
    264268        EXAMPLES::
    265269       
    266270            sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None)
    … …  
    271275
    272276    def id(self):
    273277        """
     278        Returns self's id.
     279
     280        OUTPUT:
     281
     282        - int -- self's id.
     283       
    274284        EXAMPLES::
    275285       
    276286            sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None)
    … …  
    281291
    282292    def is_auto_cell(self):
    283293        """
     294        Returns true if self is automatically evaluated.
     295       
    284296        EXAMPLES::
    285297       
    286298            sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None)
    … …  
    291303
    292304    def __cmp__(self, right):
    293305        """
     306        Compares cells by `id`.
     307       
    294308        EXAMPLES::
    295309       
    296310            sage: C1 = sage.server.notebook.cell.TextCell(0, '2+3', None)
    … …  
    339353
    340354    def set_asap(self, asap):
    341355        """
     356        Set whether this cell is evaluated as soon as possible.
     357       
    342358        EXAMPLES::
    343359       
    344360            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None)
    … …  
    568584        mainly because there is no good way to distinguish content (e.g.,
    569585        images in the current directory) that goes into the interactive
    570586        template and content that would go here.
     587
     588        EXAMPLES::
     589
     590            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     591            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     592            sage: W = nb.create_new_worksheet('Test', 'sage')
     593            sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W)
     594            sage: C.evaluate()
     595            sage: W.check_comp(wait=9999)
     596            ('d', Cell 0; in=plot(sin(x),0,5), out=
     597            <html><font color='black'><img src='cell://sage0.png'></font></html>
     598            <BLANKLINE>
     599            )
     600            sage: C.update_html_output()
     601            sage: C.output_html()
     602            '<img src="/home/sage/0/cells/0/sage0.png?...">'
    571603        """
    572604        if self.is_interactive_cell():
    573605            self.__out_html = ""
    … …  
    702734
    703735    def __cmp__(self, right):
    704736        """
     737        Compares cells by their `id`s.
     738       
    705739        EXAMPLES::
    706740       
    707741            sage: C1 = sage.server.notebook.cell.Cell(0, '2+3', '5', None)
    … …  
    718752
    719753    def __repr__(self):
    720754        """
     755        Returns a string representation of self.
     756       
    721757        EXAMPLES::
    722758       
    723759            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None); C
    … …  
    755791            return 70
    756792       
    757793    def plain_text(self, ncols=0, prompts=True, max_out=None):
    758         """
     794        r"""
    759795        Returns the plain text version of self.
    760        
    761         TODO: Add more comprehensive doctests.
     796
     797        EXAMPLES::
     798
     799            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None)
     800            sage: len(C.plain_text())
     801            11
    762802        """
    763803        if ncols == 0:
    764804            ncols = self.word_wrap_cols()
    … …  
    831871   
    832872    def edit_text(self, ncols=0, prompts=False, max_out=None):
    833873        r"""
     874        Returns the text displayed in the Edit window.
     875       
    834876        EXAMPLES::
    835877       
    836878            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None)
    … …  
    9861028
    9871029    def is_interacting(self):
    9881030        """
    989         Returns True
     1031        Returns True if this cell is currently interacting with the user.
     1032
     1033        EXAMPLES::
     1034            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     1035            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     1036            sage: W = nb.create_new_worksheet('Test', 'sage')
     1037            sage: C = W.new_cell_after(0, "@interact\ndef f(a=slider(0,10,1,5):\n    print a^2")
     1038            sage: C.is_interacting()
     1039            False
    9901040        """
    9911041        return hasattr(self, 'interact')
    9921042
    9931043    def stop_interacting(self):
    9941044        """
    995        
     1045        Stops interaction with user.
     1046
     1047        TODO: Add doctests for :meth: `stop_interacting`.
     1048           
    9961049        """
    9971050        if self.is_interacting():
    9981051            del self.interact
    … …  
    12241277        self.__in = new_text
    12251278
    12261279    def set_output_text(self, output, html, sage=None):
     1280        r"""
     1281        Sets the output text for self.
     1282
     1283        EXAMPLES::
     1284       
     1285            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None)
     1286            sage: len(C.plain_text())
     1287            11
     1288            sage: C.set_output_text('10', '10')
     1289            sage: len(C.plain_text())
     1290            12
     1291        """
    12271292        if output.count('<?__SAGE__TEXT>') > 1:
    12281293            html = '<h3><font color="red">WARNING: multiple @interacts in one cell disabled (not yet implemented).</font></h3>'
    12291294            output = ''
    … …  
    12791344            return None
    12801345
    12811346    def output_html(self):
     1347        """
     1348        Returns the HTML for self's output.
     1349
     1350        EXAMPLES::
     1351            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None)
     1352            sage: C.output_html()
     1353            ''
     1354            sage: C.set_output_text('5', '<strong>5</strong>')
     1355            sage: C.output_html()
     1356            '<strong>5</strong>'
     1357        """
    12821358        try:
    12831359            return self.__out_html
    12841360        except AttributeError:
    12851361            self.__out_html = ''
    12861362            return ''
    12871363   
    1288     def process_cell_urls(self, x):
     1364    def process_cell_urls(self, urls):
     1365        """
     1366        Processes urls of the form 'cell://.*?' by replacing the
     1367        protocol with the path to self and appending self's version
     1368        number.
     1369
     1370        INPUT:
     1371
     1372        - ``urls`` - a string
     1373
     1374        EXAMPLES::
     1375            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     1376            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     1377            sage: W = nb.create_new_worksheet('Test', 'sage')
     1378            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W)
     1379            sage: C.process_cell_urls('"cell://foobar"')
     1380            '/home/sage/0/cells/0/foobar?0"'
     1381        """
    12891382        end = '?%d"'%self.version()
    12901383        begin = self.url_to_self()
    1291         for s in re_cell.findall(x) + re_cell_2.findall(x):
    1292             x = x.replace(s,begin + s[7:-1] + end)
    1293         return x
     1384        for s in re_cell.findall(urls) + re_cell_2.findall(urls):
     1385            urls = urls.replace(s,begin + s[7:-1] + end)
     1386        return urls
    12941387
    12951388    def output_text(self, ncols=0, html=True, raw=False, allow_interact=True):
     1389        """
     1390        Returns the text for self's output.
     1391
     1392        INPUT:
     1393
     1394            - ``ncols`` - maximum number of columns
     1395           
     1396            - ``html`` - boolean stating whether to output html
     1397           
     1398            - ``raw`` - boolean stating whether to output raw text
     1399            (takes precedence over html)
     1400
     1401            - ``allow_interact`` - boolean stating whether to allow interaction
     1402
     1403        EXAMPLE::
     1404
     1405            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     1406            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     1407            sage: W = nb.create_new_worksheet('Test', 'sage')
     1408            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W)
     1409            sage: C.output_text()
     1410            '<pre class="shrunk">5</pre>'
     1411            sage: C.output_text(html=False)
     1412            '<pre class="shrunk">5</pre>'
     1413            sage: C.output_text(raw=True)
     1414            '5'
     1415        """
    12961416        if allow_interact and hasattr(self, '_interact_output'):
    12971417            # Get the input template
    12981418            z = self.output_text(ncols, html, raw, allow_interact=False)
    … …  
    13371457        return s.strip('\n')
    13381458
    13391459    def parse_html(self, s, ncols):
     1460        """
     1461        Parse HTML for output.
     1462
     1463        INPUT:
     1464
     1465            - ``s`` - the input string containing HTML
     1466           
     1467            - ``ncols`` - maximum number of columns
     1468
     1469        EXAMPLES::
     1470            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     1471            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     1472            sage: W = nb.create_new_worksheet('Test', 'sage')
     1473            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W)
     1474            sage: C.parse_html('<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">\n<html><head></head><body>Test</body></html>', 80)
     1475            '&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0...Test</body>'
     1476        """
    13401477        def format(x):
    13411478            return word_wrap(escape(x), ncols=ncols)
    13421479
    … …  
    14421579        ``verbose`` is not easily accessible now -- if you need to
    14431580        debug, you have to edit this file, changing its value to True,
    14441581        and run 'sage -b'.
     1582
     1583        EXAMPLES::
     1584
     1585            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     1586            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     1587            sage: W = nb.create_new_worksheet('Test', 'sage')
     1588            sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W)
     1589            sage: C.introspect()
     1590            False
     1591            sage: C.evaluate(username='sage')
     1592            sage: W.check_comp(9999)
     1593            ('d', Cell 0; in=sage?, out=)
     1594            sage: C.set_introspect_html('foobar')
     1595            sage: C.introspect_html()
     1596            '<div class="docstring"><pre>foobar</pre></div>'
     1597            sage: C.set_introspect_html('`foobar`')
     1598            sage: C.introspect_html()
     1599            '<div class="docstring">\n    \n  <p><span class="math">foobar</span></p>\n\n\n</div>'
    14451600        """
    14461601        if html == "" or completing:
    14471602            self.__introspect_html = html
    … …  
    15991754                return
    16001755
    16011756    def introspect_html(self):
     1757        """
     1758        Returns html for introspection.
     1759
     1760        EXAMPLES::
     1761       
     1762            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     1763            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     1764            sage: W = nb.create_new_worksheet('Test', 'sage')
     1765            sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W)
     1766            sage: C.introspect()
     1767            False
     1768            sage: C.evaluate(username='sage')
     1769            sage: W.check_comp(9999)
     1770            ('d', Cell 0; in=sage?, out=)
     1771            sage: C.introspect_html()
     1772            u'<div class="docstring">...</pre></div>'
     1773        """
    16021774        if not self.introspect():
    16031775            return ''
    16041776        try:
    … …  
    16091781
    16101782    def introspect(self):
    16111783        """
    1612         TODO: Figure out what the __introspect method is for and write a
    1613         better doctest.
     1784        Returns self's introspection text.
    16141785       
    16151786        EXAMPLES::
    1616        
    1617             sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None)
     1787
     1788            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     1789            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     1790            sage: W = nb.create_new_worksheet('Test', 'sage')
     1791            sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W)
    16181792            sage: C.introspect()
    16191793            False
    1620             sage: C.set_introspect("a", "b")
     1794            sage: C.evaluate(username='sage')
     1795            sage: W.check_comp(9999)
     1796            ('d', Cell 0; in=sage?, out=)
    16211797            sage: C.introspect()
    1622             ['a', 'b']
     1798            ['sage?', '']
    16231799        """
    16241800        try:
    16251801            return self.__introspect
    … …  
    16281804
    16291805    def unset_introspect(self):
    16301806        """
    1631         TODO: Figure out what the __introspect method is for and write a
    1632         better doctest.
     1807        Unsets self's introspection text.
    16331808       
    16341809        EXAMPLES::
    1635        
    1636             sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None)
    1637             sage: C.set_introspect("a", "b")
     1810
     1811            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     1812            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     1813            sage: W = nb.create_new_worksheet('Test', 'sage')
     1814            sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W)
    16381815            sage: C.introspect()
    1639             ['a', 'b']
     1816            False
     1817            sage: C.evaluate(username='sage')
     1818            sage: W.check_comp(9999)
     1819            ('d', Cell 0; in=sage?, out=)
     1820            sage: C.introspect()
     1821            ['sage?', '']
    16401822            sage: C.unset_introspect()
    16411823            sage: C.introspect()
    16421824            False
    … …  
    16451827
    16461828    def set_introspect(self, before_prompt, after_prompt):
    16471829        """
    1648         TODO: Figure out what the __introspect method is for and write a
    1649         better doctest.
     1830        Set self's introspection text.
    16501831       
    16511832        EXAMPLES::
    16521833       
    … …  
    16701851           [before_cursor, after_cursor] of strings.
    16711852       
    16721853       
    1673         EXAMPLES: We create a notebook, worksheet, and cell and evaluate it
     1854        EXAMPLES:
     1855
     1856        We create a notebook, worksheet, and cell and evaluate it
    16741857        in order to compute `3^5`::
    16751858       
    16761859            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    17531936        This is a hack and needs to be improved. The problem is how to get
    17541937        the documentation html to display nicely between the example cells.
    17551938        The type setting (jsMath formatting) needs attention too.
     1939
     1940        TODO: Remove this hack ( :meth: `doc_html` )
    17561941        """
    17571942        self.evaluate()
    17581943        if wrap is None:
    … …  
    17731958        return s
    17741959   
    17751960    def html(self, wrap=None, div_wrap=True, do_print=False):
     1961        r"""
     1962        Returns the html for self.
     1963
     1964        INPUT:
     1965
     1966        - ``wrap`` - a boolean stating whether to wrap lines. Defaults to
     1967          configuration if not given,
     1968
     1969        - ``div_wrap`` - a boolean stating whether to wrap ``div``s.
     1970
     1971        - ``do_print`` - a boolean stating whether the HTML is for
     1972          print or not.
     1973
     1974        EXAMPLES::
     1975
     1976            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     1977            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     1978            sage: W = nb.create_new_worksheet('Test', 'sage')
     1979            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W)
     1980            sage: C.html()
     1981            '\n\n<div id="cell_outer_0" cl...</div>'
     1982        """
    17761983        if do_print:
    17771984            wrap = 68
    17781985            div_wrap = 68
    … …  
    19102117            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    19112118            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
    19122119            sage: W = nb.create_new_worksheet('Test', 'sage')
    1913             sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', ", W)
     2120            sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W)
    19142121            sage: C.evaluate()
    19152122            sage: W.check_comp(wait=9999)
    19162123            ('d', Cell 0; in=plot(sin(x),0,5), out=
    … …  
    19372144            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    19382145            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
    19392146            sage: W = nb.create_new_worksheet('Test', 'sage')
    1940             sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', ", W)
     2147            sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W)
    19412148            sage: C.evaluate()
    19422149            sage: W.check_comp(wait=9999)
    19432150            ('d', Cell 0; in=plot(sin(x),0,5), out=
    … …  
    19602167
    19612168
    19622169    def files_html(self, out):
     2170        """
     2171        Returns html to display the files in self's directory.
     2172
     2173        INPUT:
     2174
     2175        - ``out`` - string to exclude files.
     2176                    Format: To exclude bar, foo, ...`'cell://bar cell://foo ...'`
     2177
     2178        EXAMPLES::
     2179
     2180            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     2181            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     2182            sage: W = nb.create_new_worksheet('Test', 'sage')
     2183            sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W)
     2184            sage: C.evaluate()
     2185            sage: W.check_comp(wait=9999)
     2186            ('d', Cell 0; in=plot(sin(x),0,5), out=
     2187            <html><font color='black'><img src='cell://sage0.png'></font></html>
     2188            <BLANKLINE>
     2189            )
     2190            sage: C.files_html('')
     2191            '<img src="/home/sage/0/cells/0/sage0.png?...">'
     2192        """
    19632193        import time
    19642194        D = self.files()
    19652195        D.sort()
    … …  
    20272257        return images + files
    20282258
    20292259    def html_out(self, ncols=0, do_print=False):
     2260        r"""
     2261        Returns the html for self's output.
     2262
     2263        INPUT:
     2264       
     2265            - ``do_print`` - a boolean stating whether to output html
     2266            for print
     2267
     2268            - ``ncols`` - the number of columns
     2269
     2270        EXAMPLES::
     2271
     2272            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     2273            sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
     2274            sage: W = nb.create_new_worksheet('Test', 'sage')
     2275            sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W)
     2276            sage: C.html_out()
     2277            '\n...<table class="cell_output_box">...</table>'
     2278        """
    20302279        if do_print and self.cell_output_type() == 'hidden':
    20312280            return '<pre>\n</pre>'
    20322281       

  • sage/server/notebook/config.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/config.py
    a b  
    11"""
    2 Customization of the Notebook Keybindings
     2Notebook Keybindings
    33
    44This module is responsible for setting the keyboard bindings for the notebook.
    55"""

  • sage/server/notebook/css.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/css.py
    a b  
    11"""nodoctest
    2 Sage Notebook CSS
     2Notebook Stylesheets (CSS)
    33"""
    44
    55

  • sage/server/notebook/docHTMLProcessor.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/docHTMLProcessor.py
    a b  
    44Processes Sage documentation into notebook worksheet format with
    55evaluatable examples.
    66
    7 This takes in any HTML document, i.e. Sage documentation, and returns
     7This takes in any HTML document, i.e., Sage documentation, and returns
    88it in the editable format (like the notebook edit window). It also
    9 returns a string representing the css link for the document.  The SGML
    10 parser is setup to return only the body of the html documentation page
     9returns a string representing the CSS link for the document.  The SGML
     10parser is setup to return only the body of the HTML documentation page
    1111and to re-format Sage examples and type-setting.
    1212
    1313Note: This extension of sgmllib.SGMLParser was partly inspired by Mark
    1414Pilgrim's 'Dive Into Python' examples.
    1515
    1616Author:
    17     -- Dorian Raymer (2006): first version
    18     -- William Stein (2007-06-10): rewrite to work with twisted Sage notebook
    19     -- Mike Hansen (2008-09-27): Rewrite to work with Sphinx HTML documentation
     17
     18    - Dorian Raymer (2006): first version
     19
     20    - William Stein (2007-06-10): rewrite to work with twisted Sage notebook
     21
     22    - Mike Hansen (2008-09-27): Rewrite to work with Sphinx HTML documentation
    2023"""
    2124#############################################################################
    2225#       Copyright (C) 2007 William Stein <wstein@gmail.com> and Dorian Raimer
    … …  
    3235class SphinxHTMLProcessor(SGMLParser):
    3336    def reset(self):
    3437        """
    35         This function is called by SGMLParser.__init__ so all necessary things
    36         are initialized here.
     38        Initialize necessary variables.  Called by
     39        :meth:`SGMLParser.__init__`.
    3740
    38         EXAMPLES:
     41        EXAMPLES::
     42
    3943            sage: from sage.server.notebook.docHTMLProcessor import SphinxHTMLProcessor
    4044            sage: d = SphinxHTMLProcessor()
    4145            sage: d.bodyQ
    … …  
    6468
    6569    def process_doc_html(self, doc_in):
    6670        """
    67         process_doc_html is the only function that needs to be called
    68         externally.  docin should be a properly marked up html file.
     71        Returns processed HTML input as HTML output.  This is the only
     72        method that needs to be called externally.
    6973
    70         self.feed() is a
    71         SGMLParser method and starts everything off; Most of the
    72         functions here are extensions to SGMLParser, and may never
    73         actually be visibly called here.
    74         """
     74        INPUT:
     75
     76        - ``doc_in`` - a string containing properly formed HTML
     77
     78        OUTPUT:
     79
     80        - a string; the processed HTML
     81        """       
     82        # self.feed() is a SGMLParser method and starts everything
     83        # off; Most of the functions here are extensions to
     84        # SGMLParser, and may never actually be visibly called here.
    7585        self.feed(doc_in) #SGMLParser call
    7686        self.close()     #SGMLParser call
    7787        self.hand_off_temp_pieces('to_doc_pieces')
    … …  
    8191       
    8292    def hand_off_temp_pieces(self, piece_type):
    8393        """
    84         To separate documentation content from sage examples,
    85         everything is split into one of two cell types.  This function
    86         is called to put the current self.temp_pieces into
    87         self.all_pieces.
     94        To separate the documentation's content from the Sage
     95        examples, everything is split into one of two cell types.
     96        This method puts the current ``self.temp_pieces`` into
     97        ``self.all_pieces``.
     98
     99        INPUT:
     100
     101        - ``piece_type`` - a string; indicates the type of and how to
     102          process the current ``self.temp_pieces``
    88103        """
    89104        pieces = "".join(self.temp_pieces)
    90105        pieces = pieces.lstrip()
    … …  
    100115
    101116    def get_cellcount(self):
    102117        """
    103         Returns the current cell count and increments it
    104         by one.
     118        Return the current cell count and increment it by one.
    105119
    106         EXAMPLES:
     120        OUTPUT:
     121
     122        - an int
     123
     124        EXAMPLES::
     125
    107126            sage: from sage.server.notebook.docHTMLProcessor import SphinxHTMLProcessor
    108127            sage: d = SphinxHTMLProcessor()
    109128            sage: d.get_cellcount()
    … …  
    116135
    117136    def process_cell_input_output(self, cell_piece):
    118137        """
    119         All class='highlight' div's contain code examples.
    120         Some examples are models of how the function works;
    121         those begin with INPUT: or something.
    122         The rest of the examples should have sage:input and
    123         output. If the example is a model, it is made into a
    124         div class='usage_model' so it can be stylized.
    125         If it is actual input/output, the input is separated
    126         from the output according to the Notebook edit format.
     138        Process and return a ``cell_piece``.
     139
     140        All divs with CSS class="highlight" contain code examples.
     141        They include
     142
     143         - Models of how the function works.  These begin with, e.g.,
     144           'INPUT:' and are re-styled as divs with
     145           class="usage_model".
     146
     147         - Actual Sage input and ouput.  These begin with 'sage:'.
     148           The input and output are separated according to the
     149           Notebook edit format.
     150
     151        INPUT:
     152
     153        - ``cell_piece`` - a string; a cell piece
     154
     155        OUTPUT:
     156
     157        - a string; the processed cell piece
    127158        """
    128159        if cell_piece[:5] != 'sage:' and cell_piece[:12] != '&gt;'*3:
    129160            piece = '<div class="highlight"><pre>'
    … …  
    215246    ##
    216247    def start_body(self, attrs):
    217248        """
    218         This just sets self.bodyQ to True once we've hit the body tag.
     249        Set ``self.bodyQ`` to True upon finding the opening body tag.
    219250
    220         EXAMPLES:
     251        INPUT:
     252
     253        - ``attrs`` - a string:string dictionary containing the
     254          element's attributes
     255
     256        EXAMPLES::
     257
    221258            sage: from sage.server.notebook.docHTMLProcessor import SphinxHTMLProcessor
    222259            sage: d = SphinxHTMLProcessor()
    223260            sage: d.bodyQ

  • sage/server/notebook/interact.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/interact.py
    a b  
    66#############################################################################
    77
    88r"""
    9 Interact Sage functions in the notebook
     9Interact Functions in the Notebook
    1010
    11 This module implements a interact decorator for function in the Sage
     11This module implements an :func:`interact` function decorator for the Sage
    1212notebook.
    1313
    1414AUTHORS:
    15     -- William Stein (2008-03-02): version 1.0 at Sage/Enthought Days 8 in Texas
    16     -- Jason Grout (2008-03): discussion and first few prototypes
    17     -- Jason Grout (2008-05): input_grid control
     15
     16    - William Stein (2008-03-02): version 1.0 at Sage/Enthought Days
     17       8 in Texas
     18
     19    - Jason Grout (2008-03): discussion and first few prototypes
     20
     21    - Jason Grout (2008-05): :class:`input_grid` control
    1822"""
    1923
    2024"""
    … …  
    158162
    159163def reset_state():
    160164    """
    161     Reset the interact state of this sage process.
     165    Reset the :func:`interact` state of this sage process.
    162166
    163     EXAMPLES:
     167    EXAMPLES::
     168
    164169        sage: sage.server.notebook.interact.state  # random output
    165170        {1: {'function': <function g at 0x72aaab0>, 'variables': {'m': 3, 'n': 5}, 'adapt': {1: <bound method Slider._adaptor of Slider Interact Control: n [1--|1|---10].>, 2: <bound method Slider._adaptor of Slider Interact Control: m [1--|1|---10].>}}}
    166171        sage: from sage.server.notebook.interact import reset_state
    … …  
    180185    e.g., makes sure the control always produces int's.
    181186
    182187    OUTPUT:
    183         integer
    184188
    185     EXAMPLES:
     189    - an integer
     190
     191    EXAMPLES::
     192
    186193        sage: sage.server.notebook.interact.new_adapt_number()   # random output -- depends on when called
    187194        1   
    188195    """
    … …  
    193200
    194201def html(s):
    195202    """
    196     Render the input string s in a form that tells the notebook
    197     to display it in the HTML portion of the output.
     203    Print the input string ``s`` in a form that tells the notebook to
     204    display it in the HTML portion of the output.  This function has
     205    no return value.
    198206
    199207    INPUT:
    200         s -- a string
    201208
    202     OUTPUT:
    203         string -- html format
     209    - ``s`` - a string
    204210
    205     EXAMPLES:
     211    EXAMPLES::
     212
    206213        sage: sage.server.notebook.interact.html('hello')
    207214        <html>hello</html>   
    208215    """
    … …  
    213220    Return the HTML representation of a jQuery slider.
    214221
    215222    INPUT:
    216         id      -- string -- the DOM id of the slider (better be unique)
    217         values  -- 'null' or javascript string containing array of values on slider
    218         callback-- javascript that is executed whenever the slider is done moving
    219         steps   -- number of steps from minimum to maximum value.
    220         default -- (default: 0) the default position of the slider
    221         margin  -- (default: 0) size of margin to insert around the slider
     223
     224    - ``id`` - a string; the DOM id of the slider (better be unique)
     225
     226    - ``values`` - a string; 'null' or JavaScript string containing
     227      array of values on slider
     228
     229    - ``callback`` - a string; JavaScript that is executed whenever
     230      the slider is done moving
     231
     232    - ``steps`` - an integer; number of steps from minimum to maximum
     233      value.
     234
     235    - ``default`` - an integer (default: 0); the default position of
     236      the slider
     237
     238    - ``margin`` - an integer (default: 0); size of margin to insert
     239      around the slider
     240
     241    OUTPUT:
     242   
     243    - a string - HTML format
    222244
    223245    EXAMPLES:
    224     We create a jQuery HTML slider.    If you do the following in the notebook
    225     you should obtain a slider that when moved pops up a window showing its
    226     current position.
     246
     247    We create a jQuery HTML slider.  If you do the following in the
     248    notebook you should obtain a slider that when moved pops up a
     249    window showing its current position::
     250
    227251        sage: from sage.server.notebook.interact import html_slider, html
    228252        sage: html(html_slider('slider-007', 'null', 'alert(position)', steps=5, default=2, margin=5))
    229253        <html>...</html>
    … …  
    257281    Return the HTML representation of a jQuery range slider.
    258282
    259283    INPUT:
    260         id      -- string -- the DOM id of the slider (better be unique)
    261         values  -- 'null' or javascript string containing array of values on slider
    262         callback-- javascript that is executed whenever the slider is done moving
    263         steps   -- number of steps from minimum to maximum value.
    264         default_l -- (default: 0) the default position of the left edge of the slider
    265         default_r -- (default: 1) the default position of the right edge of the slider
    266         margin  -- (default: 0) size of margin to insert around the slider
     284
     285    - ``id`` - a string; the DOM id of the slider (better be unique)
     286
     287    - ``values`` - a string; 'null' or JavaScript string containing
     288      array of values on slider
     289
     290    - ``callback`` - a string; JavaScript that is executed whenever
     291      the slider is done moving
     292
     293    - ``steps`` - an integer; number of steps from minimum to maximum
     294      value.
     295
     296    - ``default_l`` - an integer (default: 0); the default position of
     297      the left edge of the slider
     298
     299    - ``default_r`` - an integer (default: 1); the default position of
     300      the right edge of the slider
     301
     302    - ``margin`` - an integer (default: 0); size of margin to insert
     303      around the slider
     304
     305    OUTPUT:
     306
     307    - a string - HTML format
    267308
    268309    EXAMPLES:
    269     We create a jQuery range slider. If you do the following in the notebook
    270     you should obtain a slider that when moved pops up a window showing its
    271     current position.
     310
     311    We create a jQuery range slider. If you do the following in the
     312    notebook you should obtain a slider that when moved pops up a
     313    window showing its current position::
     314
    272315        sage: from sage.server.notebook.interact import html_rangeslider, html
    273316        sage: html(html_rangeslider('slider-007', 'null', 'alert(pos[0]+", "+pos[1])', steps=5, default_l=2, default_r=3, margin=5))
    274317        <html>...</html>
    … …  
    324367    Return HTML representation of a jQuery color selector.
    325368
    326369    INPUT:
    327         id -- integer; the id of the html div element that this selector should have
    328         change -- javascript code to execute when the color selector changes.
    329         default -- string (default: '000000'); default color as a 6-character
    330                    HTML hex string.
     370
     371    - ``id`` - an integer; the id of the HTML div element that this
     372      selector should have
     373
     374    - ``change`` - a string; JavaScript code to execute when the color
     375      selector changes.
     376
     377    - ``default`` - a string (default: ``'000000'``); default color as
     378      a 6-character HTML hex string.
    331379
    332380    OUTPUT:
    333         string -- HTML that creates the slider.
    334381
    335     EXAMPLES:
     382    - a string - HTML that creates the slider.
     383
     384    EXAMPLES::
     385
    336386        sage: sage.server.notebook.interact.html_color_selector(0, 'alert("changed")', '', default='0afcac')
    337387        '<table>...'
    338388    """
    … …  
    366416        Returns an empty label for this element. This should be
    367417        overridden for subclasses that need a label.
    368418
    369         EXAMPLES:
     419        OUTPUT:
     420
     421        - a string
     422
     423        EXAMPLES::
     424
    370425            sage: from sage.server.notebook.interact import UpdateButton, InteractElement
    371426            sage: b = UpdateButton(1)
    372427            sage: isinstance(b, InteractElement)
    … …  
    378433   
    379434    def set_canvas(self, canvas):
    380435        """
    381         Sets the InteractCanvas on which this element appears.  This
    382         method is primarily called in the constructor for
    383         InteractCanvas.
     436        Sets the :class:`InteractCanvas` on which this element appears.
     437        This method is primarily called in the constructor for
     438        :class:`InteractCanvas`.
    384439
    385         EXAMPLES:
     440        EXAMPLES::
     441
    386442            sage: from sage.server.notebook.interact import InputBox, InteractCanvas
    387443            sage: B = InputBox('x',2)
    388444            sage: canvas1 = InteractCanvas([B], 3)
    … …  
    398454
    399455    def canvas(self):
    400456        """
    401         Returns the InteractCanvas associated to this element.  If no
    402         canvas has been set (via the set_canvas method), then this
    403         will return a ValueError.
     457        Returns the :class:`InteractCanvas` associated to this element.  If
     458        no canvas has been set (via the :meth:`set_canvas` method), then
     459        raise a ValueError.
    404460
    405         EXAMPLES:
     461        EXAMPLES::
     462
    406463            sage: from sage.server.notebook.interact import InputBox, InteractCanvas
    407464            sage: B = InputBox('x',2)
    408465            sage: canvas1 = InteractCanvas([B], 3)
    … …  
    420477class InteractControl(InteractElement):
    421478    def __init__(self, var, default_value, label=None):
    422479        """
    423         Abstract base class for interact controls.  These are controls
    424         that are used in a specific interact.  They have internal
    425         state information about the specific function being interactd,
     480        Abstract base class for :func:`interact` controls.  These are controls
     481        that are used in a specific :func:`interact`.  They have internal
     482        state information about the specific function being interacted,
    426483        etc.
    427484       
    428485        INPUT:
    429              var -- string; name of variable that this control interacts
    430              default_value -- the default value of the variable
    431                               corresponding to this control.
    432              label -- string (default: None) label of this control; if None
    433                       then defaults to var.
    434486
    435         EXAMPLES:
     487        - ``var`` - a string; name of variable that this control
     488          interacts
     489
     490        - ``default_value`` - the default value of the variable
     491          corresponding to this control.
     492
     493        - ``label`` - a string (default: None); label for this
     494          control; if None then defaults to ``var``.
     495
     496        EXAMPLES::
     497
    436498            sage: from sage.server.notebook.interact import InteractControl
    437499            sage: InteractControl('x', default_value=5)
    438500            A InteractControl (abstract base class)
    … …  
    450512
    451513    def __repr__(self):
    452514        """
    453         String representation of interact control.
     515        String representation of :func:`interact` control.
    454516
    455         EXAMPLES:
     517        OUTPUT:
     518
     519        - a string
     520
     521        EXAMPLES::
     522
    456523            sage: from sage.server.notebook.interact import InteractControl
    457524            sage: InteractControl('x', default_value=5).__repr__()
    458525            'A InteractControl (abstract base class)'
    … …  
    461528
    462529    def value_js(self):
    463530        """
    464         Javascript that when evaluated gives the current value of this
     531        JavaScript that when evaluated gives the current value of this
    465532        control.  This should be redefined in a derived class.
    466533
    467534        OUTPUT:
    468             string -- defaults to NULL -- this should be redefined.
    469535
    470         EXAMPLES:
     536        - a string - defaults to 'NULL' - this should be redefined.
     537
     538        EXAMPLES::
     539
    471540            sage: sage.server.notebook.interact.InteractControl('x', default_value=5).value_js()
    472541            'NULL'       
    473542        """
    … …  
    475544
    476545    def label(self):
    477546        """
    478         Return the text label of this interact control.
     547        Return the text label of this :func:`interact` control.
    479548
    480         EXAMPLES:
     549        OUTPUT:
     550
     551        - a string
     552
     553        EXAMPLES::
     554
    481555            sage: from sage.server.notebook.interact import InteractControl
    482556            sage: InteractControl('x', default_value=5, label='the x value').label()
    483557            'the x value'       
    … …  
    487561    def default_value(self):
    488562        """
    489563        Return the default value of the variable corresponding to this
    490         interact control.
     564        :func:`interact` control.
    491565
    492566        OUTPUT:
    493             object
    494567
    495         EXAMPLES:
     568        - an object
     569
     570        EXAMPLES::
     571
    496572            sage: from sage.server.notebook.interact import InteractControl
    497573            sage: InteractControl('x', 19/3).default_value()
    498574            19/3
    … …  
    502578    def html_escaped_default_value(self):
    503579        """
    504580        Returns the HTML escaped default value of the variable
    505         corresponding to this interact control.  Note that any
    506         HTML that uses quotes around this should use double
    507         quotes and not single quotes.
     581        corresponding to this :func:`interact` control.  Note that any
     582        HTML that uses quotes around this should use double quotes and
     583        not single quotes.
    508584
    509         EXAMPLES:
     585        OUTPUT:
     586
     587        - a string
     588
     589        EXAMPLES::
     590
    510591            sage: from sage.server.notebook.interact import InteractControl
    511592            sage: InteractControl('x', '"cool"').html_escaped_default_value()
    512593            '&quot;cool&quot;'
    … …  
    528609        called to adapt the values of this control to Python.
    529610
    530611        OUTPUT:
    531             an integer
    532612
    533         EXAMPLES:
     613        - an integer
     614
     615        EXAMPLES::
     616
    534617            sage: from sage.server.notebook.interact import InteractControl
    535618            sage: InteractControl('x', 19/3).adapt_number()       # random -- depends on call order
    536619            2
    … …  
    543626        by this control.
    544627
    545628        INPUT:
    546             value -- the string the user typed in
    547             globs -- the globals interpreter variables, e.g.,
    548                      globals(), which is useful for evaling value.
     629
     630        - ``value`` - the string the user typed in
     631
     632        - ``globs`` - a string:object dictionary; the globals
     633          interpreter variables, e.g., :func:`globals`, which is
     634          useful for evaling value.
    549635
    550636        OUTPUT:
    551             object
    552637
    553         EXAMPLES:
     638        - an object
     639
     640        EXAMPLES::
     641
    554642            sage: sage.server.notebook.interact.InteractControl('x', 1)._adaptor('2/3', globals())
    555643            2/3       
    556644        """
    … …  
    558646       
    559647    def interact(self, *args):
    560648        """
    561         Return a string that when evaluated in Javascript calls the
    562         javascript interact function with appropriate inputs for
     649        Return a string that when evaluated in JavaScript calls the
     650        JavaScript :func:`interact` function with appropriate inputs for
    563651        this control.
    564652
    565653        This method will check to see if there is a canvas attached to
    … …  
    569657        automatically update.
    570658
    571659        OUTPUT:
    572             string -- that is meant to be evaluated in Javascript
    573660
    574         EXAMPLES:
     661        - a string - that is meant to be evaluated in JavaScript
     662
     663        EXAMPLES::
     664
    575665            sage: sage.server.notebook.interact.InteractControl('x', 1).interact()
    576666            'interact(..., "sage.server.notebook.interact.update(..., \\"x\\", ..., sage.server.notebook.interact.standard_b64decode(\\""+encode64(NULL)+"\\"), globals());sage.server.notebook.interact.recompute(0)")'
    577667        """
    … …  
    599689        Return the name of the variable that this control interacts.
    600690
    601691        OUTPUT:
    602             string -- name of a variable as a string.
    603692
    604         EXAMPLES:
     693        - a string - name of a variable as a string.
     694
     695        EXAMPLES::
     696
    605697            sage: sage.server.notebook.interact.InteractControl('theta', 1).var()
    606698            'theta'       
    607699        """
    … …  
    609701
    610702    def cell_id(self):
    611703        """
    612         Return the id of the cell that contains this interact control.
     704        Return the id of the cell that contains this :func:`interact` control.
    613705
    614706        OUTPUT:
    615             integer -- id of cell that this control interacts
     707
     708        - an integer - id of cell that this control interacts
    616709
    617710        EXAMPLES:
    618         The output below should equal the ID of the current cell.
     711
     712        The output below should equal the id of the current cell::
     713
    619714            sage: sage.server.notebook.interact.InteractControl('theta', 1).cell_id()
    620715            0
    621716        """
    … …  
    624719class InputBox(InteractControl):
    625720    def __init__(self, var, default_value, label=None, type=None, width = 80):
    626721        """
    627         An input box interact control.
     722        An input box :func:`interact` control.
    628723
    629         InputBox(var, default_value, label, type)
     724        EXAMPLES::
    630725
    631         EXAMPLES:
    632726            sage: sage.server.notebook.interact.InputBox('theta', 1, 'theta')
    633727            An InputBox interactive control with theta=1 and label 'theta'
    634728            sage: sage.server.notebook.interact.InputBox('theta', 1, 'theta', int)
    … …  
    640734       
    641735    def __repr__(self):
    642736        """
    643         String representation of an InputBox interactive control.
     737        String representation of an :class:`InputBox` interactive control.
    644738
    645         EXAMPLES:
     739        OUTPUT:
     740
     741        - a string
     742
     743        EXAMPLES::
     744
    646745            sage: sage.server.notebook.interact.InputBox('theta', 1).__repr__()
    647746            "An InputBox interactive control with theta=1 and label 'theta'"
    648747        """
    … …  
    655754        element selected by this control.
    656755
    657756        INPUT:
    658             value -- text entered by user
    659             globs -- the globals interpreter variables (not used here).
     757
     758        - ``value`` - text entered by user
     759
     760        - ``globs`` - a string:object dictionary; the :func:`globals`
     761          interpreter variables (not used here).
    660762
    661763        OUTPUT:
    662             object
    663764
    664         EXAMPLES:
     765        - an object
     766
     767        EXAMPLES::
     768
    665769            sage: sage.server.notebook.interact.InputBox('theta', Color('red'), type=Color)._adaptor('#aaaaaa',globals())
    666770            RGB color (0.6640625, 0.6640625, 0.6640625)
    667771        """
    … …  
    676780
    677781    def value_js(self):
    678782        """
    679         Return javascript string that will give the value of this
     783        Return JavaScript string that will give the value of this
    680784        control element.
    681785
    682786        OUTPUT:
    683              string -- javascript
    684787
    685         EXAMPLES:
     788        - a string - JavaScript
     789
     790        EXAMPLES::
     791
    686792            sage: sage.server.notebook.interact.InputBox('theta', 1).value_js()
    687793            'this.value'
    688794        """
    … …  
    696802        Render this control as a string.
    697803
    698804        OUTPUT:
    699              string -- html format
    700805
    701         EXAMPLES:
     806        - a string - HTML format
     807
     808        EXAMPLES::
     809
    702810            sage: sage.server.notebook.interact.InputBox('theta', 1).render()
    703811            '<input type=\'text\' value="1" size=80 onchange=\'interact(0, "sage.server.notebook.interact.update(0, \\"theta\\", ..., sage.server.notebook.interact.standard_b64decode(\\""+encode64(this.value)+"\\"), globals());sage.server.notebook.interact.recompute(0)")\'></input>'
    704812        """
    … …  
    715823class ColorInput(InputBox):
    716824    def value_js(self, n):
    717825        """
    718         Return javascript that evaluates to value of this control.
     826        Return JavaScript that evaluates to value of this control.
     827        If ``n`` is 0 return code for evaluation by the actual color
     828        control.  If ``n`` is 1, return code for the text area that
     829        displays the current color.
    719830
    720831        INPUT:
    721             n -- integer, either 0 or 1.
    722832
    723         If n is 0 return code for evaluation by the actual color control.
    724         If n is 1, return code for the text area that displays the current color.
     833        - ``n`` - integer, either 0 or 1.
    725834
    726         EXAMPLES:
     835        OUTPUT:
     836
     837        - a string
     838
     839        EXAMPLES::
     840
    727841            sage: C = sage.server.notebook.interact.ColorInput('c', Color('red'))
    728842            sage: C.value_js(0)
    729843            'color'
    … …  
    737851
    738852    def render(self):
    739853        """
    740         Render this color input box to html.
     854        Render this color input box to HTML.
    741855
    742         EXAMPLES:
     856        OUTPUT:
     857
     858        - a string - HTML format
     859
     860        EXAMPLES::
     861
    743862            sage: sage.server.notebook.interact.ColorInput('c', Color('red')).render()
    744863            '<table>...'
    745864        """
    … …  
    754873        """
    755874        A grid interact control.
    756875
    757         INPUT
    758             var -- the variable
    759             rows -- the number of rows
    760             columns -- the number of columns
    761             default_value -- if this is a scalar, it is put in every
    762                 cell; if it is a list, it is filled into the cells row by
    763                 row; if it is a nested list, then it is filled into the
    764                 cells according to the nesting structure.
    765             label -- the label for the control
    766             to_value -- a function which is applied to the nested list
    767                 from user input when assigning the variable
    768             width -- the width of the input boxes
     876        INPUT:
    769877
    770         EXAMPLES:
     878        - ``var`` - an object; the variable
     879
     880        - ``rows`` - an integer; the number of rows
     881
     882        - ``columns`` - an integer; the number of columns
     883
     884        - ``default_value`` - an object; if this is a scalar, it is
     885          put in every cell; if it is a list, it is filled into the
     886          cells row by row; if it is a nested list, then it is filled
     887          into the cells according to the nesting structure.
     888
     889        - ``label`` - a string; the label for the control
     890
     891        - ``to_value`` - a function applied to the nested list from
     892          user input when assigning the variable
     893
     894        - ``width`` - an integer; the width of the input boxes
     895
     896        EXAMPLES::
     897
    771898            sage: sage.server.notebook.interact.InputGrid('M', 2,2, default_value = 0, label='M')
    772899            A 2 x 2 InputGrid interactive control with M=[[0, 0], [0, 0]] and label 'M'
    773900            sage: sage.server.notebook.interact.InputGrid('M', 2,2, default_value = [[1,2],[3,4]], label='M')
    … …  
    795922
    796923    def __repr__(self):
    797924        """
    798         String representation of an InputGrid interactive control.
     925        String representation of an :class:`InputGrid` interactive control.
    799926
    800         EXAMPLES:
     927        OUTPUT:
     928
     929        - a string
     930
     931        EXAMPLES::
     932
    801933            sage: sage.server.notebook.interact.InputGrid('M', 2,2).__repr__()
    802934            "A 2 x 2 InputGrid interactive control with M=[[None, None], [None, None]] and label 'M'"
    803935        """
    … …  
    812944        element selected by this control.
    813945
    814946        INPUT:
    815             value -- text entered by user
    816             globs -- the globals interpreter variables (not used here).
     947
     948        - ``value`` - text entered by user
     949
     950        - ``globs`` - a string:object dictionary; the :func:`globals`
     951          interpreter variables (not used here).
    817952
    818953        OUTPUT:
    819             object
    820954
    821         EXAMPLES:
     955        - an object
     956
     957        EXAMPLES::
     958
    822959            sage: sage.server.notebook.interact.InputGrid('M', 1,3, default_value=[[1,2,3]], to_value=lambda x: vector(flatten(x)))._adaptor("[[4,5,6]]", globals())
    823960            (4, 5, 6)
    824961        """
    … …  
    827964
    828965    def value_js(self):
    829966        """
    830         Return javascript string that will give the value of this
     967        Return JavaScript string that will give the value of this
    831968        control element.
    832969
    833970        OUTPUT:
    834              string -- javascript
    835971
    836         EXAMPLES:
     972        - string - JavaScript
     973
     974        EXAMPLES::
     975
    837976            sage: sage.server.notebook.interact.InputGrid('M', 2,2).value_js()
    838977            ' "[["+jQuery(this).parents("table").eq(0).find("tr").map(function(){return jQuery(this).find("input").map(function() {return jQuery(this).val();}).get().join(",");}).get().join("],[")+"]]" '
    839978        """
    … …  
    848987        Render this control as a string.
    849988
    850989        OUTPUT:
    851              string -- html format
    852990
    853         EXAMPLES:
     991        - string - HTML format
     992
     993        EXAMPLES::
     994
    854995            sage: sage.server.notebook.interact.InputGrid('M', 1,2).render()
    855996            '<table><tr><td><input type=\'text\' value=\'None\' ...
    856997
    … …  
    8741015        A drop down menu or a button bar that when pressed sets a
    8751016        variable to a given value.
    8761017
    877         Selector(var, values, label=None, nrows=None, ncols=None)
     1018        INPUT:
    8781019
    879         INPUT:
    880             var   -- string; variable name
    881             values-- list; button values
    882             label -- string (default: None) label off to the left for this button group
    883             default -- integer (default: 0) position of default value in values list.
    884             nrows -- integer (default: None) number of rows
    885             ncols -- integer (default: None) number of columns
    886             width -- integer (default: None) width of all the buttons
    887             buttons -- bool (default: False) if True use buttons instead of dropdown
     1020        - ``var`` - a string; variable name
    8881021
    889         EXAMPLES:
     1022        - ``values`` - a list; button values
     1023
     1024        - ``label`` - a string (default: None); label off to the left
     1025          for this button group
     1026
     1027        - ``default`` - an integer (default: 0); position of default
     1028          value in values list.
     1029
     1030        - ``nrows`` - an integer (default: None); number of rows
     1031
     1032        - ``ncols`` - an integer (default: None); number of columns
     1033
     1034        - ``width`` - an integer (default: None); width of all the
     1035          buttons
     1036
     1037        - ``buttons`` - a bool (default: False); if True use buttons
     1038            instead of dropdown
     1039
     1040        EXAMPLES::
     1041
    8901042            sage: sage.server.notebook.interact.Selector('x', [1..5], 'alpha', default=2)
    8911043            Selector with 5 options for variable 'x'
    8921044            sage: sage.server.notebook.interact.Selector('x', [1..4], 'alpha', default=2, nrows=2, ncols=2, width=10, buttons=True)
    … …  
    9371089       
    9381090    def __repr__(self):
    9391091        """
    940         String representation of a Selector interactive control.
     1092        String representation of a :class:`Selector` interactive control.
    9411093
    942         EXAMPLES:
     1094        OUTPUT:
     1095
     1096        - a string
     1097
     1098        EXAMPLES::
     1099
    9431100            sage: sage.server.notebook.interact.Selector('x', [1..5]).__repr__()
    9441101            "Selector with 5 options for variable 'x'"       
    9451102        """
    … …  
    9471104
    9481105    def _adaptor(self, value, globs):
    9491106        """
    950         Adapt value of button or menu selection.
    951 
    952         The button value is just an integer, and this function adapts
    953         it to be the value that we associate with that button.
     1107        Adapt value of button or menu selection.  The button value is
     1108        just an integer, and this function adapts it to be the value
     1109        that we associate with that button.
    9541110
    9551111        INPUT:
    956             value -- value sent in via javascript
    957             globs -- the globals interpreter variables (not used here).
     1112
     1113        - ``value` - an integer; value sent in via JavaScript
     1114
     1115        - ``globs`` - a string:object dictionary; the :func:`globals`
     1116          interpreter variables (not used here).
    9581117
    9591118        OUTPUT:
    960             object
    9611119
    962         EXAMPLES:
     1120        - an object
     1121
     1122        EXAMPLES::
     1123
    9631124            sage: S = sage.server.notebook.interact.Selector('x', ['first',x^3+5])
    9641125            sage: S._adaptor(0,globals())
    9651126            'first'
    … …  
    9701131
    9711132    def use_buttons(self):
    9721133        """
    973         Whether or not to use buttons instead of a drop
    974         down menu for this select list.
     1134        Whether or not to use buttons instead of a drop down menu for
     1135        this select list.
    9751136
    9761137        OUTPUT:
    977             bool
    9781138
    979         EXAMPLES:
     1139        - a bool
     1140
     1141        EXAMPLES::
     1142
    9801143            sage: sage.server.notebook.interact.Selector('x', [1..5]).use_buttons()
    9811144            False
    9821145            sage: sage.server.notebook.interact.Selector('x', [1..5], buttons=True).use_buttons()
    … …  
    9861149
    9871150    def value_js(self):
    9881151        """
    989         Return javascript string that will give the value of this
     1152        Return JavaScript string that will give the value of this
    9901153        control element.
    9911154
    9921155        OUTPUT:
    993              string -- javascript
    9941156
    995         EXAMPLES:
     1157        - a string - JavaScript
     1158
     1159        EXAMPLES::
     1160
    9961161            sage: sage.server.notebook.interact.Selector('x', [1..5]).value_js()
    9971162            'this.options[this.selectedIndex].value'
    9981163            sage: sage.server.notebook.interact.Selector('x', [1..5], buttons=True).value_js()
    … …  
    10091174        Render this control as a string.
    10101175
    10111176        OUTPUT:
    1012              string -- html format
    10131177
    1014         EXAMPLES:
     1178        - a string - HTML format
     1179
     1180        EXAMPLES::
     1181
    10151182            sage: sage.server.notebook.interact.Selector('x', [1..5]).render()
    10161183            '<select...</select>'
    10171184            sage: sage.server.notebook.interact.Selector('x', [1..5], buttons=True).render()
    … …  
    10661233class SliderGeneric(InteractControl):
    10671234    def __init__(self, var, values, default_value, label=None, display_value=True):
    10681235        """
    1069         An abstract slider interact control that takes on the given list of
    1070         values.
     1236        An abstract slider :func:`interact` control that takes on the
     1237        given list of values.
    10711238
    10721239        INPUT:
    1073             var -- string; name of variable being interactd
    1074             values -- list; a list of the values that the slider will take on
    1075             default_value -- default valueoif slider.
    1076             label -- alternative label to the left of the slider,
    1077                      instead of the variable.
    1078             display_value -- boolean, whether to display the current value
    1079                              on the slider
    10801240
    1081         EXAMPLES:
     1241        - ``var`` - a string; name of variable being interacted
     1242
     1243        - ``values`` - a list; a list of the values that the slider
     1244            will take on
     1245
     1246        - ``default_value`` - an object; default value of the slider.
     1247
     1248        - ``label`` - a string; alternative label to the left of the
     1249          slider, instead of the variable.
     1250
     1251          - ``display_value`` - a bool; whether to display the current
     1252            value on the slider
     1253
     1254        EXAMPLES::
     1255
    10821256            sage: sage.server.notebook.interact.SliderGeneric('x', [1..5], 2, 'alpha')
    10831257            Abstract Slider Interact Control: alpha [1--|2|---5]
    10841258        """
    … …  
    10901264        """
    10911265        Return string representation of this slider control.
    10921266
    1093         EXAMPLES:
     1267        OUTPUT:
     1268
     1269        - a string
     1270
     1271        EXAMPLES::
     1272
    10941273            sage: sage.server.notebook.interact.SliderGeneric('x', [1..5], 2, 'alpha').__repr__()
    10951274            'Abstract Slider Interact Control: alpha [1--|2|---5]'
    10961275        """
    … …  
    11031282        Return list of values the slider acts on.
    11041283       
    11051284        OUTPUT:
    1106             list
     1285
     1286        - a list
    11071287           
    1108         EXAMPLES:
     1288        EXAMPLES::
     1289
    11091290            sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').values()
    11101291            [1, 2, 3, 4, 5]
    11111292        """
    … …  
    11161297        Returns whether to display the value on the slider.
    11171298       
    11181299        OUTPUT:
    1119             boolean
     1300
     1301        - a bool
    11201302       
    1121         EXAMPLES:
     1303        EXAMPLES::
     1304
    11221305            sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').display_value()
    11231306            True
    11241307        """
    … …  
    11261309
    11271310    def values_js(self):
    11281311        """
    1129         Returns Javascript array representation of values or null if display_value is False
     1312        Returns JavaScript array representation of values or 'null' if
     1313        display_value=False
    11301314
    11311315        OUTPUT:
    1132             string
     1316
     1317        - a string
    11331318       
    1134         EXAMPLES:
     1319        EXAMPLES::
     1320
    11351321            sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').values_js()
    11361322            '["1","2","3","4","5"]'
    11371323            sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha', False).values_js()
    … …  
    11521338class Slider(SliderGeneric):
    11531339    def __init__(self, var, values, default_position, label=None, display_value=True):
    11541340        """
    1155         A slider interact control that takes on the given list of
     1341        A slider :func:`interact` control that takes on the given list of
    11561342        values.
    11571343
    11581344        INPUT:
    1159             var -- string; name of variable being interactd
    1160             values -- list; a list of the values that the slider will take on
    1161             default_position -- int; default location that the slider is set to.
    1162             label -- alternative label to the left of the slider,
    1163                      instead of the variable.
    1164             display_value -- boolean, whether to display the current value right
    1165                              of the slider
    11661345
    1167         EXAMPLES:
     1346        - ``var`` - a string; name of variable being interacted
     1347
     1348        - ``values`` - a list; a list of the values that the slider
     1349          will take on
     1350
     1351        - ``default_position`` - an integer; default location that the
     1352          slider is set to.
     1353
     1354        - ``label`` - a string; alternative label to the left of the
     1355          slider, instead of the variable.
     1356
     1357          - ``display_value`` - a bool, whether to display the current
     1358            value right of the slider
     1359
     1360        EXAMPLES::
     1361
    11681362            sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha')
    11691363            Slider Interact Control: alpha [1--|3|---5]
    11701364        """
    … …  
    11751369        """
    11761370        Return string representation of this slider control.
    11771371
    1178         EXAMPLES:
     1372        OUTPUT:
     1373
     1374        - a string
     1375
     1376        EXAMPLES::
     1377
    11791378            sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').__repr__()
    11801379            'Slider Interact Control: alpha [1--|3|---5]'
    11811380        """
    … …  
    11871386        """
    11881387        Return the default position (as an integer) of the slider.
    11891388
    1190         EXAMPLES:
     1389        OUTPUT:
     1390
     1391        - an integer
     1392
     1393        EXAMPLES::
     1394
    11911395            sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').default_position()
    11921396            2
    11931397        """
    … …  
    11951399
    11961400    def value_js(self):
    11971401        """
    1198         Return javascript string that will give the
    1199         value of this control element.
     1402        Return JavaScript string that will give the value of this
     1403        control element.
    12001404
    12011405        OUTPUT:
    1202              string -- javascript
    12031406
    1204         EXAMPLES:
     1407        - a string - JavaScript
     1408
     1409        EXAMPLES::
     1410
    12051411            sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').value_js()
    12061412            'position'
    12071413        """
    … …  
    12131419        element selected by this control.
    12141420
    12151421        INPUT:
    1216             position -- position of the slider
    1217             globs -- the globals interpreter variables (not used here).
     1422
     1423        - ``position`` - an object; position of the slider
     1424
     1425        - ``globs`` - a string:object dictionary; the :func:`globals`
     1426          interpreter variables (not used here).
    12181427
    12191428        OUTPUT:
    1220             object
    12211429
    1222         EXAMPLES:
     1430        - an object
     1431
     1432        EXAMPLES::
     1433
    12231434            sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha')._adaptor(2,globals())
    12241435            3
    12251436        """
    … …  
    12331444        Render this control as an HTML string.
    12341445
    12351446        OUTPUT:
    1236              string -- html format
    12371447
    1238         EXAMPLES:
     1448        - a string - HTML format
     1449
     1450        EXAMPLES::
     1451
    12391452            sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').render()
    12401453            '<table>...<div ...var values = ["1","2","3","4","5"];...'
    12411454
    … …  
    12511464class RangeSlider(SliderGeneric):
    12521465    def __init__(self, var, values, default_position, label=None, display_value=True):
    12531466        """
    1254         A range slider interact control that takes on the given list of
    1255         values.
     1467        A range slider :func:`interact` control that takes on the given
     1468        list of values.
    12561469
    12571470        INPUT:
    1258             var -- string; name of variable being interactd
    1259             values -- list; a list of the values that the slider will take on
    1260             default_position -- (int,int); default location that the slider is set to.
    1261             label -- alternative label to the left of the slider,
    1262                      instead of the variable.
    1263             display_value -- boolean, whether to display the current value below
    1264                              the slider
    12651471
    1266         EXAMPLES:
     1472        - ``var`` - a string; name of variable being interacted
     1473
     1474        - ``values`` - a list; a list of the values that the slider
     1475          will take on
     1476
     1477        - ``default_position`` - an integer 2-tuple; default location
     1478          that the slider is set to.
     1479
     1480        - ``label`` - a string; alternative label to the left of the
     1481          slider, instead of the variable.
     1482
     1483        - ``display_value`` - a bool, whether to display the current
     1484          value below the slider
     1485
     1486        EXAMPLES::
     1487
    12671488            sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha')
    12681489            Range Slider Interact Control: alpha [1--|3==4|---5]
    12691490        """
    … …  
    12741495        """
    12751496        Return string representation of this slider control.
    12761497
    1277         EXAMPLES:
     1498        OUTPUT:
     1499
     1500        - a string
     1501
     1502        EXAMPLES::
     1503
    12781504            sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha').__repr__()
    12791505            'Range Slider Interact Control: alpha [1--|3==4|---5]'
    12801506        """
    … …  
    12861512        """
    12871513        Return the default position (as an integer) of the slider.
    12881514
    1289         EXAMPLES:
     1515        OUTPUT:
     1516
     1517        - an integer 2-tuple
     1518
     1519        EXAMPLES::
     1520
    12901521            sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha').default_position()
    12911522            (2, 3)
    12921523        """
    … …  
    12941525
    12951526    def value_js(self):
    12961527        """
    1297         Return javascript string that will give the
    1298         value of this control element.
     1528        Return JavaScript string that will give the value of this
     1529        control element.
    12991530
    13001531        OUTPUT:
    1301              string -- javascript
    13021532
    1303         EXAMPLES:
     1533        - a string - JavaScript
     1534
     1535        EXAMPLES::
     1536
    13041537            sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha').value_js()
    13051538            "pos[0]+' '+pos[1]"
    13061539        """
    … …  
    13121545        element selected by this control.
    13131546
    13141547        INPUT:
    1315             position -- position of the slider
    1316             globs -- the globals interpreter variables (not used here).
     1548
     1549        - ``position`` - an object; position of the slider
     1550
     1551        - ``globs` - a string:object dictionary; the :func:`globals`
     1552          interpreter variables (not used here).
    13171553
    13181554        OUTPUT:
    1319             object
    13201555
    1321         EXAMPLES:
     1556        - an object
     1557
     1558        EXAMPLES::
     1559
    13221560            sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha')._adaptor("2 3",globals())
    13231561            (3, 4)
    13241562        """
    … …  
    13321570        Render this control as an HTML string.
    13331571
    13341572        OUTPUT:
    1335              string -- html format
    13361573
    1337         EXAMPLES:
     1574        - string - HTML format
     1575
     1576        EXAMPLES::
     1577
    13381578            sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha').render()
    13391579            '<table>...<div ...var values = ["1","2","3","4","5"];...'
    13401580
    … …  
    13511591class TextControl(InteractControl):
    13521592    def __init__(self, var, data):
    13531593        """
    1354         A text field interact control
     1594        A text field :func:`interact` control
    13551595
    13561596        INPUT:
    1357             data -- the HTML value of the text field
    13581597
    1359         EXAMPLES:
     1598        - ``data`` - a string; the HTML value of the text field
     1599
     1600        EXAMPLES::
     1601
    13601602            sage: sage.server.notebook.interact.TextControl('x', 'something')
    13611603            Text Interact Control: something
    13621604        """
    … …  
    13671609        """
    13681610        Return string representation of this control.
    13691611
    1370         EXAMPLES:
     1612        OUTPUT:
     1613
     1614        - a string
     1615
     1616        EXAMPLES::
     1617
    13711618            sage: sage.server.notebook.interact.TextControl('x', 'something').__repr__()
    13721619            'Text Interact Control: something'
    13731620        """
    … …  
    13781625        Render this control as an HTML string.
    13791626
    13801627        OUTPUT:
    1381              string -- html format
    13821628
    1383         EXAMPLES:
     1629        - a string - HTML format
     1630
     1631        EXAMPLES::
     1632
    13841633            sage: sage.server.notebook.interact.TextControl('x', 'something').render()
    13851634            '<div ...>something</div>'
    13861635        """
    … …  
    13901639class InteractCanvas:
    13911640    def __init__(self, controls, id, **options):
    13921641        """
    1393         Base class for interact canvases. This is where all the controls
    1394         along with the output of the interactd function are laid out
    1395         and rendered.
     1642        Base class for :func:`interact` canvases. This is where all
     1643        the controls along with the output of the interacted function
     1644        are laid out and rendered.
    13961645       
    13971646        INPUT:
    1398             controls -- a list of InteractControl instances.
    1399             id -- the id of the cell that contains this InteractCanvas.
    1400             options -- any additional keyword arguments (for example, auto_update=False)
     1647
     1648        - ``controls`` - a list of :class:`InteractControl` instances.
     1649
     1650        - ``id`` - an integer; the id of the cell that contains this
     1651          InteractCanvas.
     1652
     1653        - ``options`` - any additional keyword arguments (for example,
     1654          auto_update=False)
    14011655           
    1402         EXAMPLES:
     1656        EXAMPLES::
     1657
    14031658            sage: B = sage.server.notebook.interact.InputBox('x',2)
    14041659            sage: sage.server.notebook.interact.InteractCanvas([B], 3)
    14051660            Interactive canvas in cell 3 with 1 controls
    … …  
    14151670        """
    14161671        Print representation of an interactive canvas.
    14171672
    1418         EXAMPLES:
     1673        OUTPUT:
     1674
     1675        - a string
     1676
     1677        EXAMPLES::
     1678
    14191679            sage: B = sage.server.notebook.interact.InputBox('x',2)
    14201680            sage: sage.server.notebook.interact.InteractCanvas([B], 3).__repr__()
    14211681            'Interactive canvas in cell 3 with 1 controls'
    … …  
    14241684            self.__cell_id, len(self.__controls))
    14251685
    14261686    def is_auto_update(self):
    1427         """
     1687        r"""
    14281688        Returns True if any change of the values for the controls on
    1429         this canvas should cause an update.  If auto_update=False was
     1689        this canvas should cause an update.  If `auto_update=False` was
    14301690        not specified in the constructor for this canvas, then this
    14311691        will default to True.
    14321692
    1433         EXAMPLES:
     1693        OUTPUT:
     1694
     1695        - a bool
     1696
     1697        EXAMPLES::
     1698
    14341699            sage: B = sage.server.notebook.interact.InputBox('x',2)
    14351700            sage: canvas = sage.server.notebook.interact.InteractCanvas([B], 3)
    14361701            sage: canvas.is_auto_update()
    … …  
    14421707        return self.__options.get('auto_update', True)
    14431708
    14441709    def cell_id(self):
    1445         """
    1446         Returns the cell id associated to this InteractCanvas.
     1710        r"""
     1711        Returns the cell id associated to this :class:`InteractCanvas`.
    14471712
    1448         EXAMPLES:
     1713        OUTPUT:
     1714
     1715        - an integer
     1716
     1717        EXAMPLES::
     1718
    14491719            sage: B = sage.server.notebook.interact.InputBox('x',2)
    14501720            sage: canvas = sage.server.notebook.interact.InteractCanvas([B], 3)
    14511721            sage: canvas.cell_id()
    … …  
    14551725
    14561726    def controls(self):
    14571727        """
    1458         Return list of controls in this canvas.
     1728        Return a list of controls in this canvas.
    14591729
    1460         WARNING: Returns a reference to a mutable list.
     1730        OUTPUT:
    14611731
    1462         EXAMPLES:
     1732        - list of controls
     1733
     1734        .. note:: Returns a reference to a mutable list.
     1735
     1736        EXAMPLES::
     1737
    14631738            sage: B = sage.server.notebook.interact.InputBox('x',2)
    14641739            sage: sage.server.notebook.interact.InteractCanvas([B], 3).controls()
    14651740            [An InputBox interactive control with x=2 and label 'x']
    … …  
    14701745        """
    14711746        Return the cell id that contains this interactive canvas.
    14721747
    1473         EXAMPLES:
     1748        OUTPUT:
     1749
     1750        - an integer
     1751
     1752        EXAMPLES::
     1753
    14741754            sage: B = sage.server.notebook.interact.InputBox('x',2)
    14751755            sage: sage.server.notebook.interact.InteractCanvas([B], 3).cell_id()
    14761756            3
    … …  
    14791759
    14801760    def render_output(self):
    14811761        """
    1482         Render in text (html) form the output portion of the interact canvas.
     1762        Render in text (HTML) form the output portion of the
     1763        :func:`interact` canvas.
    14831764
    14841765        The output contains two special tags, <?TEXT> and <?HTML>,
    1485         which get replaced at runtime by the text and html parts
     1766        which get replaced at runtime by the text and HTML parts
    14861767        of the output of running the function.
    14871768
    14881769        OUTPUT:
    1489             string -- html
    14901770
    1491         EXAMPLES:
     1771        - a string - HTML format
     1772
     1773        EXAMPLES::
     1774
    14921775            sage: B = sage.server.notebook.interact.InputBox('x',2)
    14931776            sage: sage.server.notebook.interact.InteractCanvas([B], 3).render_output()
    14941777            "<div ...</div>"
    … …  
    15011784
    15021785    def render_controls(self):
    15031786        """
    1504         Render in text (html) form all the input controls.
     1787        Render in text (HTML) form all the input controls.
    15051788
    15061789        OUTPUT:
    1507             string -- html
    15081790
    1509         EXAMPLES:
     1791        - a string - HTML format
     1792
     1793        EXAMPLES::
     1794
    15101795            sage: B = sage.server.notebook.interact.InputBox('x',2)
    15111796            sage: sage.server.notebook.interact.InteractCanvas([B], 3).render_controls()
    15121797            '<table>...'
    … …  
    15231808    def wrap_in_outside_frame(self, inside):
    15241809        """
    15251810        Return the entire HTML for the interactive canvas, obtained by
    1526         wrapping all the inside html of the canvas in a div and a
     1811        wrapping all the inside HTML of the canvas in a div and a
    15271812        table.
    15281813
    15291814        INPUT:
    1530             inside -- string (of HTML)
     1815
     1816        - ``inside`` - a string; HTML
    15311817
    15321818        OUTPUT:
    1533             string of HTML
     1819
     1820        - a string - HTML format
    15341821           
    1535         EXAMPLES:
     1822        EXAMPLES::
     1823
    15361824            sage: B = sage.server.notebook.interact.InputBox('x',2)
    15371825            sage: sage.server.notebook.interact.InteractCanvas([B], 3).wrap_in_outside_frame('<!--inside-->')
    15381826            "<!--notruncate--><div padding=6 id='div-interact-3'> ...</div>\n                 "
    … …  
    15531841
    15541842    def render(self):
    15551843        """
    1556         Render in text (html) the entire interact canvas.
     1844        Render in text (HTML) the entire :func:`interact` canvas.
    15571845
    15581846        OUTPUT:
    1559             string -- html
     1847
     1848        - string - HTML format
    15601849           
    1561         EXAMPLES:
     1850        EXAMPLES::
     1851
    15621852            sage: B = sage.server.notebook.interact.InputBox('x',2)
    15631853            sage: sage.server.notebook.interact.InteractCanvas([B], 3).render()
    15641854            '<!--notruncate--><div padding=6 id=\'div-interact-3\'> ...</div>\n                 '
    … …  
    15701860class JavascriptCodeButton(InteractElement):
    15711861    def __init__(self, label, code):
    15721862        """
    1573         This interact element displays a button which when clicked
    1574         executes Javascript code in the notebook.
     1863        This :func:`interact` element displays a button which when clicked
     1864        executes JavaScript code in the notebook.
    15751865
    1576         EXAMPLES:
     1866        EXAMPLES::
     1867
    15771868            sage: b = sage.server.notebook.interact.JavascriptCodeButton('Push me', 'alert("2")')
    15781869        """
    15791870        self.__label = label
    … …  
    15841875        r"""
    15851876        Returns the HTML to display this button.
    15861877
    1587         EXAMPLES:
     1878        OUTPUT:
     1879
     1880        - a string - HTML format
     1881
     1882        EXAMPLES::
     1883
    15881884            sage: b = sage.server.notebook.interact.JavascriptCodeButton('Push me', 'alert("2")')
    15891885            sage: b.render()
    15901886            '<input type="button" value="Push me" onclick=\'alert("2")\'>\n'
    … …  
    15951891class UpdateButton(JavascriptCodeButton):
    15961892    def __init__(self, cell_id):
    15971893        r"""
    1598         This interact element creates a button which when clicked
    1599         causes the interact function in the cell cell_id to be
     1894        This :func:`interact` element creates a button which when clicked
     1895        causes the :func:`interact` function in the cell ``cell_id`` to be
    16001896        recomputed with the current values of the variables.
    16011897
    1602         EXAMPLES:
     1898        INPUT:
     1899
     1900        - ``cell_id`` - an integer; the ambient cell's id
     1901
     1902        EXAMPLES::
     1903
    16031904            sage: b = sage.server.notebook.interact.UpdateButton(0)
    16041905            sage: b.render()
    16051906            '<input type="button" value="Update" onclick=\'interact(0, "sage.server.notebook.interact.recompute(0)")\'>\n'
    … …  
    16121913    r"""
    16131914    Use interact as a decorator to create interactive Sage notebook
    16141915    cells with sliders, text boxes, radio buttons, check boxes, and
    1615     color selectors.  Simply put @interact on the line before a
     1916    color selectors.  Simply put ``@interact`` on the line before a
    16161917    function definition in a cell by itself, and choose appropriate
    16171918    defaults for the variable names to determine the types of
    16181919    controls (see tables below).
    16191920
    16201921    INPUT:
    1621         f -- a Python function
     1922
     1923    - ``f`` - a Python function
    16221924
    16231925    EXAMPLES:
     1926
    16241927    In each example below we use a single underscore for the function
    1625     name.  You can use \emph{any} name you want; it does not have to
     1928    name.  You can use *any* name you want; it does not have to
    16261929    be an underscore. 
    16271930   
    16281931    We create an interact control with two inputs, a text input for
    1629     the variable $a$ and a $y$ slider that runs through the range of
    1630     integers from $0$ to $19$. 
     1932    the variable ``a`` and a ``y`` slider that runs through the range of
     1933    integers from `0` to `19`.
     1934
     1935    ::
     1936
    16311937        sage: @interact
    16321938        ... def _(a=5, y=(0..20)): print a + y
    16331939        ...
    16341940        <html>...
    16351941
    1636     Draw a plot interacting with the ``continuous'' variable $a$.  By
     1942    Draw a plot interacting with the "continuous" variable ``a``.  By
    16371943    default continuous variables have exactly 50 possibilities.
     1944
     1945    ::
     1946
    16381947        sage: @interact
    16391948        ... def _(a=(0,2)):
    16401949        ...     show(plot(sin(x*(1+a*x)), (x,0,6)), figsize=4)
    16411950        <html>...
    16421951
    16431952    Interact a variable in steps of 1 (we also use an unnamed
    1644     function):
     1953    function)::
     1954
    16451955        sage: @interact
    16461956        ... def _(n=(10,100,1)):
    16471957        ...     show(factor(x^n - 1))
    16481958        <html>...
    16491959
    1650     Interact two variables:
     1960    Interact two variables::
     1961
    16511962        sage: @interact
    16521963        ... def _(a=(1,4), b=(0,10)):
    16531964        ...     show(plot(sin(a*x+b), (x,0,6)), figsize=3)
    16541965        <html>...
    16551966
    1656     Place a block of text among the controls:
     1967    Place a block of text among the controls::
     1968
    16571969        sage: @interact
    16581970        ... def _(t1=text_control("Factors an integer."), n="1"):
    16591971        ...     print factor(Integer(n))   
    16601972        <html>...
    16611973   
    16621974    You do not have to use interact as a decorators; you can also
    1663     simply write \code{interact(f)} where f is any Python function
    1664     that you have defined, though this is frowned on.  E.g., f can
    1665     also be a library function as long as it is written in Python:
     1975    simply write ``interact(f)`` where ``f`` is any Python function
     1976    that you have defined, though this is frowned upon.  E.g., ``f``
     1977    can also be a library function as long as it is written in
     1978    Python::
    16661979
    16671980        sage: interact(matrix)   # put ZZ, 2,2,[1..4] in boxes...
    16681981        <html>...
    16691982
    16701983    If your the time to evaluate your function takes awhile, you may
    16711984    not want to have it reevaluated every time the inputs change.  In
    1672     order to prevent this, you can add a keyword
    1673     \code{auto_update=False} to your function to prevent it from
    1674     updating whenever the values are changed.  This will cause a
    1675     button labeled 'Update' to appear which you can click on to
    1676     re-evaluate your function.
     1985    order to prevent this, you can add a keyword ``auto_update=False`` to
     1986    your function to prevent it from updating whenever the values are
     1987    changed.  This will cause a button labeled 'Update' to appear
     1988    which you can click on to re-evaluate your function.
     1989
     1990    ::
    16771991
    16781992        sage: @interact
    16791993        ... def _(n=(10,100,1), auto_update=False):
    … …  
    16811995        <html>...
    16821996
    16831997    DEFAULTS:
     1998
    16841999    Defaults for the variables of the input function determine
    1685     interactive controls.  The standard controls are \code{input_box},
    1686     \code{slider}, \code{range_slider}, \code{checkbox}, \code{selector},
    1687     \code{input_grid}.  There is also a color selector and text control
     2000    interactive controls.  The standard controls are ``input_box``,
     2001    ``slider``, ``range_slider``, ``checkbox``, ``selector``, and
     2002    ``input_grid``.  There is also a color selector and text control
    16882003    (see defaults below).
     2004
    16892005   
    1690     \begin{itemize}
    1691         \item u = input_box(default=None, label=None, type=None)
    1692                          -- input box with given default; use type=str to
    1693                             get input as an arbitrary string
    1694         \item u = slider(vmin, vmax=None,step_size=1,default=None,label=None)
    1695                          -- slider with given list of possible values; vmin can be a list
    1696         \item u = range_slider(vmin, vmax=None,step_size=1,default=None,label=None)
    1697                          -- range slider with given list of possible values;
    1698                             vmin can be a list
    1699         \item u = checkbox(default=True, label=None)
    1700                          -- a checkbox
    1701         \item u = selector(values, label=None, nrows=None, ncols=None, buttons=False)                 
    1702                          -- a dropdown menu or buttons (get buttons if nrows,
    1703                             ncols, or buttons is set, otherwise a dropdown menu)
    1704         \item u = input_grid(nrows, ncols, default=None, label=None,
    1705                              to_value=lambda x:x, width=4)
    1706                          -- an editable grid of objects (a matrix or array)
    1707         \item u = text_control(value='')
    1708                          -- a block of text
    1709     \end{itemize}
     2006        * ``u = input_box(default=None, label=None, type=None)`` -
     2007          input box with given ``default``; use ``type=str`` to get
     2008          input as an arbitrary string
     2009
     2010
     2011        * ``u = slider(vmin, vmax=None, step_size=1, default=None,
     2012          label=None)`` - slider with given list of possible values;
     2013          ``vmin`` can be a list
     2014
     2015
     2016        * ``u = range_slider(vmin, vmax=None, step_size=1,
     2017          default=None, label=None)`` - range slider with given list
     2018          of possible values; ``vmin`` can be a list
     2019
     2020
     2021        * ``u = checkbox(default=True, label=None)`` - a checkbox
     2022
     2023
     2024        * ``u = selector(values, label=None, nrows=None, ncols=None,
     2025          buttons=False)`` - a dropdown menu or buttons (get buttons
     2026          if ``nrows``, ``ncols``, or ``buttons`` is set, otherwise a
     2027          dropdown menu)
     2028
     2029
     2030        * ``u = input_grid(nrows, ncols, default=None, label=None,
     2031          to_value=lambda x:x, width=4)`` - an editable grid of
     2032          objects (a matrix or array)
     2033
     2034
     2035        * ``u = text_control(value='')`` - a block of text
     2036
    17102037
    17112038    You can create a color selector by setting the default value for a
    1712     variable to Color(...).
     2039    variable to ``Color(...)``.
    17132040
    17142041    There are also some convenient defaults that allow you to make
    17152042    controls automatically without having to explicitly specify them.
    1716     E.g., you can make $x$ a continuous slider of values between $u$
    1717     and $v$ by just writing \code{x=(u,v)} in the argument list of
     2043    E.g., you can make ``x`` a continuous slider of values between ``u``
     2044    and ``v`` by just writing ``x=(u,v)`` in the argument list of
    17182045    your function.  These are all just convenient shortcuts for
    17192046    creating the controls listed above.
    17202047   
    1721     \begin{itemize}
    1722         \item u                 -- blank input_box field
    1723         \item u = element       -- input_box with default=element, if element not below.
    1724         \item u = (umin,umax)   -- continuous slider (really 100 steps)
    1725         \item u = (umin,umax,du)-- slider with step size du
    1726         \item u = list          -- buttons if len(list) at most 5; otherwise, drop down
    1727         \item u = generator     -- a slider (up to 10000 steps)
    1728         \item u = bool          -- a checkbox
    1729         \item u = Color('blue') -- a 2d RGB color selector; returns Color object
    1730         \item u = (default, v)  -- v as above, with given default value
    1731         \item u = (label, v)    -- v as above, with given label (a string)
    1732         \item u = matrix        -- an input_grid with to_value set to matrix.parent()
    1733                                    and default values given by the matrix
    1734     \end{itemize}
     2048        * ``u`` - blank input_box field
    17352049
    1736     WARNING: Suppose you would like to make a interactive with a
    1737     default rgb color of (1,0,0), so the function would have signature
    1738     \code{f(color=(1,0,0))}.  Unfortunately, the above shortcuts reinterpret
    1739     the (1,0,0) as a discrete slider with step size 0 between 1 and 0.
    1740     Instead you should do the following:
    1741         sage: @interact
    1742         ... def _(v = input_box((1,0,0))):
    1743         ...       show(plot(sin,color=v))
    1744         <html>...
     2050        * ``u = element`` - input_box with ``default=element``, if
     2051          element not below.
     2052
     2053        * ``u = (umin,umax)`` - continuous slider (really `100` steps)
     2054
     2055        * ``u = (umin,umax,du)`` - slider with step size ``du``
     2056
     2057        * ``u = list`` - buttons if ``len(list)`` at most `5`;
     2058          otherwise, drop down
     2059
     2060        * ``u = generator`` - a slider (up to `10000` steps)
     2061
     2062        * ``u = bool`` - a checkbox
     2063
     2064        * ``u = Color('blue')`` - a 2D RGB color selector; returns
     2065          ``Color`` object
     2066
     2067        * ``u = (default, v)`` - ``v`` as above, with given
     2068          ``default`` value
     2069
     2070        * ``u = (label, v)`` - ``v`` as above, with given ``label``
     2071          (a string)
     2072
     2073        * ``u = matrix`` - an ``input_grid`` with ``to_value`` set to
     2074          ``matrix.parent()`` and default values given by the matrix
     2075
     2076    .. note::
     2077
     2078        Suppose you would like to make a interactive with a default
     2079        RGB color of ``(1,0,0)``, so the function would have signature
     2080        ``f(color=(1,0,0))``.  Unfortunately, the above shortcuts
     2081        reinterpret the ``(1,0,0)`` as a discrete slider with step
     2082        size 0 between 1 and 0.  Instead you should do the
     2083        following::
     2084
     2085            sage: @interact
     2086            ... def _(v = input_box((1,0,0))):
     2087            ...       show(plot(sin,color=v))
     2088            <html>...
    17452089
    17462090    MORE EXAMPLES:
    1747     We give an input box that allows one to enter completely arbitrary strings.
     2091
     2092    We give an input box that allows one to enter completely arbitrary
     2093    strings::
     2094
    17482095        sage: @interact
    17492096        ... def _(a=input_box('sage', label="Enter your name", type=str)):
    17502097        ...        print "Hello there %s"%a.capitalize()
    17512098        <html>...
    17522099
    1753     The scope of variables that you control via interact are local to
    1754     the scope of the function being interacted with. However, by using
    1755     the global Python keyword, you can still modify global variables
    1756     as follows:
     2100    The scope of variables that you control via :func:`interact` are local
     2101    to the scope of the function being interacted with. However, by
     2102    using the ``global`` Python keyword, you can still modify global
     2103    variables as follows::
     2104
    17572105        sage: xyz = 10
    17582106        sage: @interact
    17592107        ... def _(a=('xyz',5)):
    … …  
    17612109        ...       xyz = a
    17622110        <html>...
    17632111
    1764     If you enter the above you obtain an interact canvas.  Entering
    1765     values in the box, changes the global variable xyz.
     2112    If you enter the above you obtain an :func:`interact` canvas.  Entering
     2113    values in the box changes the global variable ``xyz``::
    17662114
    17672115        sage: @interact
    17682116        ... def _(title=["A Plot Demo", "Something silly", "something tricky"], a=input_box(sin(x*sin(x*sin(x))), 'function'),
    … …  
    17722120        ...     show(plot(a, -zoom*pi,zoom*pi, color=clr, thickness=thickness, plot_points=plot_points))
    17732121        <html>...
    17742122
    1775     We give defaults and name the variables:
     2123    We give defaults and name the variables::
     2124
    17762125        sage: @interact
    17772126        ... def _(a=('first', (1,4)), b=(0,10)):
    17782127        ...       show(plot(sin(a*x+sin(b*x)), (x,0,6)), figsize=3)
    17792128        <html>...
    17802129
    1781     Another example involving labels and defaults, and the
    1782     slider command.
     2130    Another example involving labels, defaults, and the slider
     2131    command::
     2132
    17832133        sage: @interact
    17842134        ... def _(a = slider(1, 4, default=2, label='Multiplier'),
    17852135        ...       b = slider(0, 10, default=0, label='Phase Variable')):
    17862136        ...     show(plot(sin(a*x+b), (x,0,6)), figsize=4)
    17872137        <html>...
    17882138
    1789     An example where the range slider control is useful.
     2139    An example where the range slider control is useful::
     2140
    17902141        sage: @interact
    17912142        ... def _(b = range_slider(-20, 20, 1, default=(-19,3), label='Range')):
    17922143        ...     plot(sin(x)/x, b[0], b[1]).show(xmin=b[0],xmax=b[1])
    17932144        <html>...
    17942145
    1795     An example using checkboxes, obtained by making the default values bools.
     2146    An example using checkboxes, obtained by making the default values
     2147    bools::
     2148
    17962149        sage: @interact
    17972150        ... def _(axes=('Show axes', True), square=False):
    17982151        ...       show(plot(sin, -5,5), axes=axes, aspect_ratio = (1 if square else None))
    17992152        <html>...
    18002153
    1801     An example generating a random walk that uses a checkbox control to determine
    1802     whether points are placed at each step:
     2154    An example generating a random walk that uses a checkbox control
     2155    to determine whether points are placed at each step::
     2156
    18032157        sage: @interact
    18042158        ... def foo(pts = checkbox(True, "points"), n = (50,(10..100))):
    18052159        ...       s = 0; v = [(0,0)]
    … …  
    18112165        ...       show(L)
    18122166        <html>...
    18132167
    1814     You can rotate and zoom into 3D graphics while
    1815     interacting with a variable.
     2168    You can rotate and zoom into 3D graphics while interacting with a
     2169    variable::
     2170
    18162171        sage: @interact
    18172172        ... def _(a=(0,1)):
    18182173        ...     x,y = var('x,y')
    18192174        ...     show(plot3d(sin(x*cos(y*a)), (x,0,5), (y,0,5)), figsize=4)
    18202175        <html>...
    18212176
    1822     A random polygon:
     2177    A random polygon::
     2178
    18232179        sage: pts = [(random(), random()) for _ in xrange(20)]
    18242180        sage: @interact
    18252181        ... def _(n = (4..len(pts)), c=Color('purple') ):
    … …  
    18272183        ...     show(G, figsize=5, xmin=0, ymin=0)
    18282184        <html>...
    18292185
    1830     Two "sinks" displayed simultaneously via a contour plot and a 3d
    1831     interactive plot:
     2186    Two "sinks" displayed simultaneously via a contour plot and a 3D
     2187    interactive plot::
     2188
    18322189        sage: @interact
    18332190        ... def _(q1=(-1,(-3,3)), q2=(-2,(-3,3))):
    18342191        ...     x,y = var('x,y')
    … …  
    18382195        ...     show(plot3d(f, (x,-2,2), (y,-2,2)), figsize=4)       
    18392196        <html>...
    18402197
    1841     This is similar to above, but you can select the color map from a dropdown menu:
     2198    This is similar to above, but you can select the color map from a
     2199    dropdown menu::
     2200
    18422201        sage: @interact
    18432202        ... def _(q1=(-1,(-3,3)), q2=(-2,(-3,3)),
    18442203        ...    cmap=['autumn', 'bone', 'cool', 'copper', 'gray', 'hot', 'hsv',
    … …  
    18492208        ...     show(C, figsize=3, aspect_ratio=1)
    18502209        <html>...
    18512210
    1852     A quadratic roots etch-a-sketch:
     2211    A quadratic roots etch-a-sketch::
     2212
    18532213        sage: v = []
    18542214        sage: html('<h2>Quadratic Root Etch-a-sketch</h2>')
    18552215        <html><font color='black'><h2>Quadratic Root Etch-a-sketch</h2></font></html>
    … …  
    18632223        ...       show(line(v, rgbcolor='purple') + point(P, pointsize=200))   
    18642224        <html>...
    18652225
    1866     In the following example, we only generate data for a given n
    1867     once, so that as one varies p the data doesn't not randomly
    1868     change.  We do this by simply caching the results for each n
    1869     in a dictionary.
     2226    In the following example, we only generate data for a given ``n``
     2227    once, so that as one varies ``p`` the data does not randomly change.
     2228    We do this by simply caching the results for each ``n`` in a
     2229    dictionary.::
     2230
    18702231        sage: data = {}
    18712232        sage: @interact
    18722233        ... def _(n=(500,(100,5000,1)), p=(1,(0.1,10))):
    … …  
    18762237        ...     show(points([(x^p,y^p) for x,y in data[n]], rgbcolor='black'), xmin=0, ymin=0, axes=False)
    18772238        <html>...
    18782239
    1879     A conchoid:
     2240    A conchoid::
     2241
    18802242        sage: @interact
    18812243        ... def _(k=(1.2,(1.1,2)), k_2=(1.2,(1.1,2)), a=(1.5,(1.1,2))):
    18822244        ...     u, v = var('u,v')
    … …  
    18842246        ...     show(parametric_plot3d(f, (u,0,6*pi), (v,0,2*pi), plot_points=[40,40], texture=(0,0.5,0)))
    18852247        <html>...
    18862248
    1887     An input grid:
     2249    An input grid::
     2250
    18882251        sage: @interact
    18892252        ... def _(A=matrix(QQ,3,3,range(9)), v=matrix(QQ,3,1,range(3))):
    18902253        ...     try:
    … …  
    19372300class control:
    19382301    def __init__(self, label=None):
    19392302        """
    1940         An interactive control object used with the interact command.
     2303        An interactive control object used with the :func:`interact` command.
    19412304        This is the abstract base class.
    19422305
    19432306        INPUTS:
    1944             label -- a string
     2307
     2308        - ``label`` - a string
    19452309           
    1946         EXAMPLES:
     2310        EXAMPLES::
     2311
    19472312            sage: sage.server.notebook.interact.control('a control')
    19482313            Interative control 'a control' (abstract base class)
    19492314        """
    … …  
    19512316
    19522317    def __repr__(self):
    19532318        """
    1954         Return string representation of this control.
    1955         (It just mentions the label and that this is an abstract base class.)
     2319        Return string representation of this control.  (It just
     2320        mentions the label and that this is an abstract base class.)
    19562321
    1957         EXAMPLES:
     2322        OUTPUT:
     2323
     2324        - a string
     2325
     2326        EXAMPLES::
     2327
    19582328            sage: sage.server.notebook.interact.control('a control').__repr__()
    19592329            "Interative control 'a control' (abstract base class)"
    19602330        """
    … …  
    19652335        Return the label of this control.
    19662336
    19672337        OUTPUT:
    1968             a string
    1969            
    1970         EXAMPLES:
     2338
     2339        - a string
     2340
     2341        EXAMPLES::
     2342
    19712343            sage: sage.server.notebook.interact.control('a control').label()
    19722344            'a control'
    19732345            sage: selector([1,2,7], 'alpha').label()
    … …  
    19802352        Set the label of this control.
    19812353
    19822354        INPUT:
    1983             label -- a string
     2355
     2356        - ``label`` - a string
    19842357           
    1985         EXAMPLES:
     2358        EXAMPLES::
     2359
    19862360            sage: C = sage.server.notebook.interact.control('a control')
    19872361            sage: C.set_label('sage'); C
    19882362            Interative control 'sage' (abstract base class)
    … …  
    19932367    def __init__(self, default=None, label=None, type=None, width = 80):
    19942368        r"""
    19952369        An input box interactive control.  Use this in conjunction
    1996         with the interact command.
    1997        
    1998         \code{input_box(default=None, label=None, type=None)}
     2370        with the :func:`interact` command.
    19992371       
    20002372        INPUT:
    2001             default -- object; the default put in this input box
    2002             label -- the label rendered to the left of the box.
    2003             type -- coerce inputs to this; this doesn't have to be
    2004                     an actual type, since anything callable will do.
    2005             width -- width of text box in characters
     2373
     2374        - ``default`` - an object; the default put in this input box
     2375
     2376        - ``label`` - a string; the label rendered to the left of the
     2377          box.
     2378
     2379        - ``type`` - a type; coerce inputs to this; this doesn't
     2380          have to be an actual type, since anything callable will do.
     2381
     2382        - ``width`` - an integer; width of text box in characters
    20062383           
    2007         EXAMPLES:
     2384        EXAMPLES::
     2385
    20082386            sage: input_box("2+2", 'expression')
    20092387            Interact input box labeled 'expression' with default value '2+2'
    20102388            sage: input_box('sage', label="Enter your name", type=str)
    … …  
    20192397        """
    20202398        Return print representation of this input box.
    20212399
    2022         EXAMPLES:
     2400        OUTPUT:
     2401
     2402        - a string
     2403
     2404        EXAMPLES::
     2405
    20232406            sage: input_box("2+2", 'expression').__repr__()
    20242407            "Interact input box labeled 'expression' with default value '2+2'"
    20252408        """
    … …  
    20292412        """
    20302413        Return the default value of this input box.
    20312414
    2032         EXAMPLES:
     2415        OUTPUT:
     2416
     2417        - an object
     2418
     2419        EXAMPLES::
     2420
    20332421            sage: input_box('2+2', 'Expression').default()
    20342422            '2+2'
    20352423            sage: input_box(x^2 + 1, 'Expression').default()
    … …  
    20422430    def type(self):
    20432431        """
    20442432        Return the type that elements of this input box are coerced to
    2045         or None if they are not coerced (they have whatever type they
    2046         evaluate to).
     2433        or None if they are not coerced (they have whatever type
     2434        they evaluate to).
    20472435
    2048         EXAMPLES:
     2436        OUTPUT:
     2437
     2438        - a type
     2439
     2440        EXAMPLES::
     2441
    20492442            sage: input_box("2+2", 'expression', type=int).type()
    20502443            <type 'int'>
    20512444            sage: input_box("2+2", 'expression').type() is None
    … …  
    20552448
    20562449    def render(self, var):
    20572450        r"""
    2058         Return rendering of this input box as an InputBox to be used
    2059         for an interact canvas.  Basically this specializes this
    2060         input to be used for a specific function and variable.
     2451        Return rendering of this input box as an :class:`InputBox` to be
     2452        used for an :func:`interact` canvas.  Basically this specializes
     2453        this input to be used for a specific function and variable.
    20612454       
    20622455        INPUT:
    2063             var -- a string (variable; one of the variable names input to f)
     2456
     2457        - ``var`` - a string (variable; one of the variable names
     2458          input to ``f``)
    20642459
    20652460        OUTPUT:
    2066             InputBox -- an InputBox object.
    20672461
    2068         EXAMPLES:
     2462        - an :class:`InputBox` instance
     2463
     2464        EXAMPLES::
     2465
    20692466            sage: input_box("2+2", 'Exp').render('x')
    20702467            An InputBox interactive control with x='2+2' and label 'Exp'       
    20712468        """
    … …  
    20792476    def __init__(self, nrows, ncols, default=None, label=None, to_value=lambda x: x, width=4):
    20802477        r"""
    20812478        An input grid interactive control.  Use this in conjunction
    2082         with the interact command.
     2479        with the :func:`interact` command.
    20832480
    20842481        INPUT:
    2085             nrows -- integer
    2086             ncols -- integer
    2087             default -- object; the default put in this input box
    2088             label -- the label rendered to the left of the box.
    2089             to_value -- the grid output (list of rows) is sent through
    2090                         this function.  This may reformat the data or
    2091                         coerce the type.
    2092             width -- size of each input box in characters
     2482
     2483        - ``nrows`` - an integer
     2484
     2485        - ``ncols`` - an integer
     2486
     2487        - ``default`` - an object; the default put in this input box
     2488
     2489        - ``label`` - a string; the label rendered to the left of the
     2490          box.
     2491
     2492        - ``to_value`` - a list; the grid output (list of rows) is
     2493          sent through this function.  This may reformat the data or
     2494          coerce the type.
     2495
     2496        - ``width`` - an integer; size of each input box in characters
    20932497           
    20942498        NOTEBOOK EXAMPLE:
     2499
    20952500            @interact
    20962501            def _(m = input_grid(2,2, default = [[1,7],[3,4]],
    20972502                                 label='M=', to_value=matrix),
    … …  
    21032508                except:
    21042509                    html('There is no solution to $$%s x=%s$$'%(latex(m), latex(v)))
    21052510
     2511        EXAMPLES::
    21062512
    2107         EXAMPLES:
    21082513            sage: input_grid(2,2, default = 0, label='M')
    21092514            Interact 2 x 2 input grid control labeled M with default value 0
    21102515            sage: input_grid(2,2, default = [[1,2],[3,4]], label='M')
    … …  
    21262531        """
    21272532        Return print representation of this input box.
    21282533
    2129         EXAMPLES:
     2534        OUTPUT:
     2535
     2536        - a string
     2537
     2538        EXAMPLES::
     2539
    21302540            sage: input_grid(2,2, label='M').__repr__()
    21312541            'Interact 2 x 2 input grid control labeled M with default value None'
    21322542
    … …  
    21402550        """
    21412551        Return the default value of this input grid.
    21422552
    2143         EXAMPLES:
     2553        OUTPUT:
     2554
     2555        - an object
     2556
     2557        EXAMPLES::
     2558
    21442559            sage: input_grid(2,2, default=1).default()
    21452560            1
    21462561        """
    … …  
    21492564
    21502565    def render(self, var):
    21512566        r"""
    2152         Return rendering of this input grid as an InputGrid to be used
    2153         for an interact canvas.  Basically this specializes this
    2154         input to be used for a specific function and variable.
     2567        Return rendering of this input grid as an :class:`InputGrid` to be
     2568        used for an :func:`interact` canvas.  Basically this specializes
     2569        this input to be used for a specific function and variable.
    21552570       
    21562571        INPUT:
    2157             var -- a string (variable; one of the variable names input to f)
     2572
     2573        - ``var`` - a string (variable; one of the variable names
     2574          input to ``f``)
    21582575
    21592576        OUTPUT:
    2160             InputGrid -- an InputGrid object.
    21612577
    2162         EXAMPLES:
     2578        - an :class:`InputGrid` instance.
     2579
     2580        EXAMPLES::
     2581
    21632582            sage: input_grid(2,2).render('x')
    21642583            A 2 x 2 InputGrid interactive control with x=[[None, None], [None, None]] and label 'x'
    21652584           
    … …  
    21712590class checkbox(input_box):
    21722591    def __init__(self, default=True, label=None):
    21732592        """
    2174         A checkbox interactive control.  Use this in conjecture
    2175         with the interact command.
     2593        A checkbox interactive control.  Use this in conjunction with
     2594        the :func:`interact` command.
    21762595
    21772596        INPUT:
    2178             default -- bool (default: True); whether box should be checked or not
    2179             label -- str or None (default: None) text label rendered to the left of the box
    21802597
    2181         EXAMPLES:
     2598        - ``default`` - a bool (default: True); whether box should be
     2599          checked or not
     2600
     2601        - ``label`` - a string (default: None) text label rendered to
     2602          the left of the box
     2603
     2604        EXAMPLES::
     2605
    21822606            sage: checkbox(False, "Points")
    21832607            Interact checkbox labeled 'Points' with default value False
    21842608            sage: checkbox(True, "Points")
    … …  
    21942618        """
    21952619        Print representation of this checkbox.
    21962620       
    2197         EXAMPLES:
     2621        OUTPUT:
     2622
     2623        - a string
     2624
     2625        EXAMPLES::
     2626
    21982627            sage: checkbox(True, "Points").__repr__()
    21992628            "Interact checkbox labeled 'Points' with default value True"
    22002629        """
    … …  
    22482677        Returns list of values that this slider takes on, in order.
    22492678
    22502679        OUTPUT:
    2251             list -- list of values
    22522680
    2253         WARNING: This is a reference to a mutable list.
     2681        - a list
    22542682
    2255         EXAMPLES:
     2683        .. note:: This is a reference to a mutable list.
     2684
     2685        EXAMPLES::
     2686
    22562687            sage: sage.server.notebook.interact.slider(1,10,1/2).values()
    22572688            [1, 3/2, 2, 5/2, 3, 7/2, 4, 9/2, 5, 11/2, 6, 13/2, 7, 15/2, 8, 17/2, 9, 19/2, 10]
    22582689        """
    … …  
    22632694        Returns whether to display the value on the slider.
    22642695       
    22652696        OUTPUT:
    2266             boolean
     2697
     2698        - a bool
    22672699           
    2268         EXAMPLES:
     2700        EXAMPLES::
     2701
    22692702            sage.server.notebook.interact.slider_generic(1,10,1/2).display_value()
    22702703            True
    22712704        """
    … …  
    22762709    def __init__(self, vmin, vmax=None, step_size=None, default=None, label=None, display_value=True):
    22772710        r"""
    22782711        An interactive slider control, which can be used in conjunction
    2279         with the interact command.
    2280 
    2281         \code{slider(vmin, vmax=None, step_size=1, default=None, label=None)}
     2712        with the :func:`interact` command.
    22822713       
    22832714        INPUT:
    2284             vmin -- object or number
    2285             vmax -- object or None; if None then vmin must be a list, and the slider
    2286                     then varies over elements of the list.
    2287             step_size -- integer (default: 1)
    2288             default -- object or None; default value is ``closest'' in vmin or range
    2289                        to this default.
    2290             label -- string
    2291             display_value -- boolean, whether to display the current value to the right
    2292                              of the slider
    22932715
    2294         EXAMPLES:
    2295         We specify both vmin and vmax.  We make the default 3, but
    2296         since 3 isn't one of 3/17-th spaced values between 2 and 5,
    2297         52/17 is instead chosen as the default (it is closest).
     2716        - ``vmin`` - an object
     2717
     2718        - ``vmax`` - an object (default: None); if None then ``vmin``
     2719          must be a list, and the slider then varies over elements of
     2720          the list.
     2721
     2722        - ``step_size`` - an integer (default: 1)
     2723
     2724        - ``default`` - an object (default: None); default value is
     2725          "closest" in ``vmin`` or range to this default.
     2726
     2727        - ``label`` - a string
     2728
     2729        - ``display_value`` - a bool, whether to display the current
     2730          value to the right of the slider
     2731
     2732        EXAMPLES::
     2733
     2734        We specify both ``vmin`` and ``vmax``.  We make the default
     2735        `3`, but since `3` isn't one of `3/17`-th spaced values
     2736        between `2` and `5`, `52/17` is instead chosen as the
     2737        default (it is closest)::
     2738
    22982739            sage: slider(2, 5, 3/17, 3, 'alpha')
    22992740            Slider: alpha [2--|52/17|---5]
    23002741
    2301         Here we give a list:
     2742        Here we give a list::
     2743
    23022744            sage: slider([1..10], None, None, 3, 'alpha')
    23032745            Slider: alpha [1--|3|---10]
    23042746
    2305         The elements of the list can be anything:
     2747        The elements of the list can be anything::
     2748
    23062749            sage: slider([1, 'x', 'abc', 2/3], None, None, 'x', 'alpha')
    23072750            Slider: alpha [1--|x|---2/3]           
    23082751        """
    … …  
    23292772        """
    23302773        Return string representation of this slider.
    23312774       
    2332         EXAMPLES:
     2775        OUTPUT:
     2776
     2777        - a string
     2778
     2779        EXAMPLES::
     2780
    23332781            sage: slider(2, 5, 1/5, 3, 'alpha').__repr__()
    23342782            'Slider: alpha [2--|3|---5]'
    23352783        """
    … …  
    23432791        Return default index into the list of values.
    23442792
    23452793        OUTPUT:
    2346             int
    23472794
    2348         EXAMPLES:
     2795        - an integer
     2796
     2797        EXAMPLES::
     2798
    23492799            sage: slider(2, 5, 1/2, 3, 'alpha').default_index()
    23502800            2
    23512801        """
    … …  
    23532803
    23542804    def render(self, var):
    23552805        """
    2356         Render the interact control for the given function and
     2806        Render the :func:`interact` control for the given function and
    23572807        variable.
    23582808
    23592809        INPUT:
    2360             var -- string; variable name
    23612810
    2362         EXAMPLES:
     2811         - ``var`` - a string; variable name
     2812
     2813        OUTPUT:
     2814
     2815        - a :class:`Slider` instance
     2816
     2817        EXAMPLES::
     2818
    23632819            sage: S = slider(0, 10, 1, default=3, label='theta'); S
    23642820            Slider: theta [0--|3|---10]
    23652821            sage: S.render('x')
    … …  
    23752831    def __init__(self, vmin, vmax=None, step_size=None, default=None, label=None, display_value=True):
    23762832        r"""
    23772833        An interactive range slider control, which can be used in conjunction
    2378         with the interact command.
     2834        with the :func:`interact` command.
    23792835
    2380         \code{range_slider(vmin, vmax=None, step_size=1, default=None, label=None)}
    2381        
    23822836        INPUT:
    2383             vmin -- object or number
    2384             vmax -- object or None; if None then vmin must be a list, and the slider
    2385                     then varies over elements of the list.
    2386             step_size -- integer (default: 1)
    2387             default -- (object, object) or None; default range is ``closest'' in vmin or range
    2388                        to this default.
    2389             label -- string
    2390             display_value -- boolean, whether to display the current value below
    2391                              the slider
    23922837
    2393         EXAMPLES:
    2394         We specify both vmin and vmax.  We make the default (3,4) but
    2395         since neither is one of 3/17-th spaced values between 2 and 5,
    2396         the closest values: 52/17 and 67/17, are instead chosen as the
    2397         default.
     2838        - ``vmin`` - an object
     2839
     2840        - ``vmax`` - object or None; if None then ``vmin`` must be a
     2841          list, and the slider then varies over elements of the list.
     2842
     2843        - ``step_size`` - integer (default: 1)
     2844
     2845        - ``default`` - a 2-tuple of objects (default: None); default
     2846          range is "closest" in ``vmin`` or range to this default.
     2847
     2848        - ``label`` - a string
     2849
     2850        - ``display_value`` - a bool, whether to display the current
     2851          value below the slider
     2852
     2853        EXAMPLES::
     2854
     2855        We specify both ``vmin`` and ``vmax``.  We make the default
     2856        `(3,4)` but since neither is one of `3/17`-th spaced
     2857        values between `2` and `5`, the closest values: `52/17`
     2858        and `67/17`, are instead chosen as the default::
     2859
    23982860            sage: range_slider(2, 5, 3/17, (3,4), 'alpha')
    23992861            Range Slider: alpha [2--|52/17==67/17|---5]
    24002862           
    2401         Here we give a list:
     2863        Here we give a list::
     2864
    24022865            sage: range_slider([1..10], None, None, (3,7), 'alpha')
    24032866            Range Slider: alpha [1--|3==7|---10]
    24042867        """
    … …  
    24302893        """
    24312894        Return string representation of this slider.
    24322895       
    2433         EXAMPLES:
     2896        OUTPUT:
     2897
     2898        - a string
     2899
     2900        EXAMPLES::
     2901
    24342902            sage: range_slider(2, 5, 1/5, (3,4), 'alpha').__repr__()
    24352903            'Range Slider: alpha [2--|3==4|---5]'
    24362904        """
    … …  
    24432911        Return default index into the list of values.
    24442912
    24452913        OUTPUT:
    2446             (int, int)
    24472914
    2448         EXAMPLES:
     2915        - an integer 2-tuple
     2916
     2917        EXAMPLES::
     2918
    24492919            sage: range_slider(2, 5, 1/2, (3,4), 'alpha').default_index()
    24502920            (2, 4)
    24512921        """
    … …  
    24532923
    24542924    def render(self, var):
    24552925        """
    2456         Render the interact control for the given function and
     2926        Render the :func:`interact` control for the given function and
    24572927        variable.
    24582928
    24592929        INPUT:
    2460             var -- string; variable name
    24612930
    2462         EXAMPLES:
     2931        - ``var`` - string; variable name
     2932
     2933        OUTPUT:
     2934
     2935        - a :class:`RangeSlider` instance
     2936
     2937        EXAMPLES::
     2938
    24632939            sage: S = range_slider(0, 10, 1, default=(3,7), label='theta'); S
    24642940            Range Slider: theta [0--|3==7|---10]
    24652941            sage: S.render('x')
    … …  
    24772953        r"""
    24782954        A drop down menu or a button bar that when pressed sets a
    24792955        variable to a given value.  Use this in conjunction with the
    2480         interact command.
    2481 
    2482         \code{selector(values, label=None, nrows=None, ncols=None, buttons=False)}
     2956        :func:`interact` command.
    24832957
    24842958        We use the same command to create either a drop down menu or
    24852959        selector bar of buttons, since conceptually the two controls
    2486         do exactly the same thing -- they only look different.  If
    2487         either nrows or ncols is given, then you get a buttons instead
    2488         of a drop down menu.
     2960        do exactly the same thing - they only look different.  If
     2961        either ``nrows`` or ``ncols`` is given, then you get a buttons
     2962        instead of a drop down menu.
    24892963       
    24902964        INPUT:
    2491             values -- [val0, val1, val2, ...] or
    2492                       [(val0, lbl0), (val1,lbl1), ...] where all labels must be
    2493                                                        given or given as None.
    2494             label -- (default: None); if given, this label is placed to
    2495                                       the left of the entire button group
    2496             default -- object (default: 0) default value in values list
    2497             nrows -- (default: None); if given determines the number
    2498                      of rows of buttons; if given buttons option below is set to True
    2499             ncols -- (default: None); if given determines the number
    2500                      of columns of buttons; if given buttons option below is set to True
    2501             width -- (default: None); if given, all buttons are the same
    2502                      width, equal to this in html ex units's.
    2503             buttons -- (default: False); if True, use buttons         
    25042965
    2505         EXAMPLES:
     2966        - ``values`` - [val0, val1, val2, ...] or [(val0, lbl0),
     2967          (val1,lbl1), ...] where all labels must be given or given as
     2968          None.
     2969
     2970        - ``label`` - a string (default: None); if given, this label
     2971          is placed to the left of the entire button group
     2972
     2973        - ``default`` - an object (default: 0); default value in values
     2974          list
     2975
     2976        - ``nrows`` - an integer (default: None); if given determines
     2977          the number of rows of buttons; if given buttons option below
     2978          is set to True
     2979
     2980        - ``ncols`` - an integer (default: None); if given determines
     2981          the number of columns of buttons; if given buttons option
     2982          below is set to True
     2983
     2984        - ``width`` - an integer (default: None); if given, all
     2985          buttons are the same width, equal to this in HTML ex
     2986          units's.
     2987
     2988        - ``buttons`` - a bool (default: False); if True, use buttons
     2989
     2990        EXAMPLES::
     2991
    25062992            sage: selector([1..5])   
    25072993            Drop down menu with 5 options
    25082994            sage: selector([1,2,7], default=2)
    … …  
    25163002            sage: selector([1,2,7], buttons=True)
    25173003            Button bar with 3 buttons
    25183004
    2519         We create an interactive that involves computing charpolys of matrices over various rings:
     3005        We create an :func:`interact` that involves computing charpolys of
     3006        matrices over various rings::
     3007
    25203008            sage: @interact
    25213009            ... def _(R=selector([ZZ,QQ,GF(17),RDF,RR]), n=(1..10)):
    25223010            ...      M = random_matrix(R, n)
    … …  
    25263014            ...      print f
    25273015            <html>...
    25283016
    2529         Here we create a drop-down
     3017        Here we create a drop-down::
     3018
    25303019            sage: @interact
    25313020            ... def _(a=selector([(2,'second'), (3,'third')])):
    25323021            ...       print a
    … …  
    25533042        """
    25543043        Return print representation of this button.
    25553044
    2556         EXAMPLES:
     3045        OUTPUT:
     3046
     3047        - a string
     3048
     3049        EXAMPLES::
     3050
    25573051            sage: selector([1,2,7], default=2).__repr__()
    25583052            'Drop down menu with 3 options'
    25593053        """
    … …  
    25683062        selector can take on.
    25693063
    25703064        OUTPUT:
    2571             list
    25723065
    2573         EXAMPLES:
     3066        - a list
     3067
     3068        EXAMPLES::
     3069
    25743070            sage: selector([1..5]).values()   
    25753071            [1, 2, 3, 4, 5]
    25763072            sage: selector([(5,'fifth'), (8,'eight')]).values()
    … …  
    25833079        Return the default choice for this control.
    25843080
    25853081        OUTPUT:
    2586            int -- an integer, with 0 corresponding to the first choice.
    25873082
    2588         EXAMPLES:
     3083        - an integer, with 0 corresponding to the first choice.
     3084
     3085        EXAMPLES::
     3086
    25893087            sage: selector([1,2,7], default=2).default()
    25903088            1       
    25913089        """
    … …  
    25933091
    25943092    def render(self, var):
    25953093        r"""
    2596         Return rendering of this button as a Button instance to be
    2597         used for an interact canvas.
     3094        Return rendering of this button as a :class:`Selector`
     3095        instance to be used for an :func:`interact` canvas.
    25983096       
    25993097        INPUT:
    2600             var -- a string (variable; one of the variable names input to f)
     3098
     3099        - ``var`` - a string (variable; one of the variable names
     3100          input to ``f``)
    26013101
    26023102        OUTPUT:
    2603             Button -- a Button instance
    26043103
    2605         EXAMPLES:
     3104        - a :class:`Selector` instance
     3105
     3106        EXAMPLES::
     3107
    26063108            sage: selector([1..5]).render('alpha')
    26073109            Selector with 5 options for variable 'alpha'
    26083110        """
    … …  
    26143116class text_control(control):
    26153117    def __init__(self, value=''):
    26163118        """
    2617         Text that can be inserted among other interact controls.
     3119        Text that can be inserted among other :func:`interact` controls.
    26183120
    26193121        INPUT:
    2620             value -- HTML for the control
    26213122
    2622         EXAMPLES:
     3123        - ``value`` - HTML for the control
     3124
     3125        EXAMPLES::
     3126
    26233127            sage: text_control('something')
    26243128            Text field: something
    26253129        """
    … …  
    26303134        """
    26313135        Return print representation of this control.
    26323136
    2633         EXAMPLES:
     3137        OUTPUT:
     3138
     3139        - a string
     3140
     3141        EXAMPLES::
     3142
    26343143            sage: text_control('something')
    26353144            Text field: something
    26363145        """
    … …  
    26413150        Return rendering of the text field
    26423151       
    26433152        INPUT:
    2644             var -- a string (variable; one of the variable names input to f)
     3153
     3154        - ``var`` - a string (variable; one of the variable names
     3155          input to ``f``)
    26453156
    26463157        OUTPUT:
    2647             TextControl -- a TextControl instance
     3158
     3159        - a :class:`TextControl` instance
    26483160        """
    26493161        return TextControl(var, self.__default)
    26503162
    … …  
    26553167    value of the variable.
    26563168
    26573169    INPUT:
    2658         default -- the default value for v given by the function; see
    2659                    the documentation to interact? for details.
     3170
     3171    - ``default`` - the default value for ``v`` given by the function;
     3172      see the documentation to :func:`interact` for details.
    26603173
    26613174    OUTPUT:
    2662         a interact control
    26633175
    2664     EXAMPLES:
     3176    - an :func:`interact` control
     3177
     3178    EXAMPLES::
     3179
    26653180        sage: sage.server.notebook.interact.automatic_control('')
    26663181        Interact input box labeled None with default value ''
    26673182        sage: sage.server.notebook.interact.automatic_control(15)
    … …  
    27373252    Given an iterator v, return first n elements it produces as a list.
    27383253
    27393254    INPUT:
    2740         v -- an iterator
    2741         n -- an integer
     3255
     3256    - ``v`` - an iterator
     3257
     3258    - ``n`` - an integer
    27423259
    27433260    OUTPUT:
    2744         list
    27453261
    2746     EXAMPLES:
     3262    - a list
     3263
     3264    EXAMPLES::
     3265
    27473266        sage: sage.server.notebook.interact.list_of_first_n(Primes(), 10)
    27483267        [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
    27493268        sage: sage.server.notebook.interact.list_of_first_n((1..5), 10)
    … …  
    27643283
    27653284
    27663285def update(cell_id, var, adapt, value, globs):
    2767     """
     3286    r"""
    27683287    Called when updating the positions of an interactive control.
    27693288    Note that this just causes the values of the variables to be
    27703289    updated; it does not reevaluate the function with the new values.
    27713290   
    27723291    INPUT:
    2773         cell_id -- the id of a interact cell
    2774         var -- a variable associated to that cell
    2775         adapt -- the number of the adapt function
    2776         value -- new value of the control
    2777         globs -- global variables.
     3292
     3293    - ``cell_id`` - an integer; the id of an :func:`interact` cell
     3294
     3295    - ``var`` - an object; a variable associated to that cell
     3296
     3297    - ``adapt`` - in integer; the number of the adapt function
     3298
     3299    - ``value`` - an object; new value of the control
     3300
     3301    - ``globs`` - global variables.
    27783302
    27793303    EXAMPLES:
     3304
    27803305    The following outputs __SAGE_INTERACT_RESTART__ to indicate that
    2781     not all the state of the interrupt canvas has been setup yet (this
    2782     setup happens when javascript calls certain functions).
     3306    not all the state of the :func:`interact` canvas has been set up yet
     3307    (this setup happens when JavaScript calls certain functions)::
     3308
    27833309        sage: sage.server.notebook.interact.update(0, 'a', 0, '5', globals())
    27843310        __SAGE_INTERACT_RESTART__         
    27853311    """
    … …  
    27953321
    27963322def recompute(cell_id):
    27973323    """
    2798     Evaluates the interact function associated to the cell
    2799     cell_id. This typically gets called after a call to
    2800     sage.server.notebook.interact.update.
     3324    Evaluates the :func:`interact` function associated to the cell
     3325    ``cell_id``. This typically gets called after a call to
     3326    :func:`update`.
    28013327   
     3328    INPUT:
     3329
     3330    - ``cell_id`` - an integer
     3331
    28023332    EXAMPLES:
     3333
    28033334    The following outputs __SAGE_INTERACT_RESTART__ to indicate that
    2804     not all the state of the interrupt canvas has been setup yet (this
    2805     setup happens when javascript calls certain functions).
     3335    not all the state of the :func:`interact` canvas has been set up yet
     3336    (this setup happens when JavaScript calls certain functions)::
     3337
    28063338        sage: sage.server.notebook.interact.recompute(10)
    28073339        __SAGE_INTERACT_RESTART__         
    28083340

  • sage/server/notebook/js.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/js.py
    a b  
    11r"""nodoctest
    2 Javascript (AJAX) Component of \sage Notebook
     2JavaScript (AJAX) Components of the Notebook
    33
    44AUTHORS:
    55

  • sage/server/notebook/notebook.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/notebook.py
    a b  
    182182        Create the default users for a notebook.
    183183       
    184184        INPUT:
    185        
    186        
     185
    187186        -  ``passwd`` - a string
    188187       
    189        
    190188        EXAMPLES::
    191189       
    192190            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    213211
    214212    def user_exists(self, username):
    215213        """
    216         Return whether or not a user exists given a username.
     214        Return whether a user with the given ``username`` exists.
    217215       
     216        INPUT:
     217
     218        - ``username`` - a string
     219
     220        OUTPUT:
     221
     222        - a bool
     223
    218224        EXAMPLES::
    219225       
    220226            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    233239           
    234240    def users(self):
    235241        """
    236         Return dictionary of users in a notebook.
     242        Return a dictionary of users in a notebook.
    237243       
     244        OUTPUT:
     245
     246        - a string:User instance dictionary
     247
    238248        EXAMPLES::
    239249       
    240250            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    251261
    252262    def user(self, username):
    253263        """
    254         Return an instance of the User class given the username of a user
     264        Return an instance of the User class given the ``username`` of a user
    255265        in a notebook.
    256266       
     267        INPUT:
     268
     269        - ``username`` - a string
     270
     271        OUTPUT:
     272
     273        - an instance of User
     274
    257275        EXAMPLES::
    258276       
    259277            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    284302
    285303    def create_user_with_same_password(self, user, other_user):
    286304        r"""
     305        Change the password of ``user`` to that of ``other_user``.
     306       
    287307        INPUT:
    288308       
    289        
    290309        -  ``user`` - a string
    291310       
    292311        -  ``other_user`` - a string
    293312       
    294        
    295         OUTPUT: Changes password of ``user`` to that of
    296         ``other_user``.
    297        
    298313        EXAMPLES::
    299314       
    300315            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    315330
    316331    def user_is_admin(self, user):
    317332        """
     333        Return true if ``user`` is an admin.
     334
     335        INPUT:
     336
     337        - ``user`` - an instance of User
     338       
     339        OUTPUT:
     340       
     341        - a bool
     342
    318343        EXAMPLES::
    319344       
    320345            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    321             sage: nb.add_user('Administrator', 'password', ", 'admin', True)
    322             sage: nb.add_user('RegularUser', 'password', ", 'user', True)
     346            sage: nb.add_user('Administrator', 'password', '', 'admin', True)
     347            sage: nb.add_user('RegularUser', 'password', '', 'user', True)
    323348            sage: nb.user_is_admin('Administrator')
    324349            True
    325350            sage: nb.user_is_admin('RegularUser')
    … …  
    329354
    330355    def user_is_guest(self, username):
    331356        """
     357        Return true if ``username`` is a guest.
     358
     359        INPUT:
     360
     361        - ``username`` - a string
     362       
     363        OUTPUT:
     364
     365        - a bool
     366
    332367        EXAMPLES::
    333368       
    334369            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    346381   
    347382    def user_list(self):
    348383        """
    349         Return list of user objects.
     384        Return a list of user objects.
    350385       
     386        OUTPUT:
     387
     388        - a list of User instances
     389
    351390        EXAMPLES::
    352391       
    353392            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    360399
    361400    def usernames(self):
    362401        """
    363         Return list of usernames.
     402        Return a list of usernames.
    364403       
     404        OUTPUT:
     405
     406        - a list of strings
     407
    365408        EXAMPLES::
    366409       
    367410            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    375418
    376419    def valid_login_names(self):
    377420        """
    378         Return list of users that can be signed in.
     421        Return a list of users that can log in.
    379422       
     423        OUTPUT:
     424
     425        - a list of strings
     426
    380427        EXAMPLES::
    381428       
    382429            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    384431            Creating default users.
    385432            sage: nb.valid_login_names()
    386433            ['admin']
    387             sage: nb.add_user('Mark', 'password', ", force=True)
    388             sage: nb.add_user('Sarah', 'password', ", force=True)
    389             sage: nb.add_user('David', 'password', ", force=True)
     434            sage: nb.add_user('Mark', 'password', '', force=True)
     435            sage: nb.add_user('Sarah', 'password', '', force=True)
     436            sage: nb.add_user('David', 'password', '', force=True)
    390437            sage: sorted(nb.valid_login_names())
    391438            ['David', 'Mark', 'Sarah', 'admin']
    392439        """
    393440        return [x for x in self.usernames() if not x in ['guest', '_sage_', 'pub']]
    394441
    395442    def default_user(self):
    396         """
    397         Return a default login name that the user will see when confronted
    398         with the Sage notebook login page.
     443        r"""
     444        Return a default login name that the user will see when
     445        confronted with the Sage notebook login page.  Currently, this
     446        returns 'admin' if that is the *only* user.  Otherwise it
     447        returns an empty string ('').
    399448       
    400         OUTPUT: string
    401        
    402         Currently this returns 'admin' if that is the *only* user.
    403         Otherwise it returns the string ".
     449        OUTPUT:
     450
     451        - a string - the default username.
    404452       
    405453        EXAMPLES::
    406454       
    … …  
    409457            Creating default users.
    410458            sage: nb.default_user()
    411459            'admin'
    412             sage: nb.add_user('AnotherUser', 'password', ", force=True)
     460            sage: nb.add_user('AnotherUser', 'password', '', force=True)
    413461            sage: nb.default_user()
    414462            ''
    415463        """
    … …  
    420468
    421469    def set_accounts(self, value):
    422470        r"""
    423         Changes ``__accounts`` to ``value``
     471        Set the attribute ``__accounts`` to ``value``.
    424472       
     473        INPUT:
     474       
     475        - ``value`` - a bool
     476
    425477        EXAMPLES::
    426478       
    427479            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    438490
    439491    def get_accounts(self):
    440492        r"""
    441         Return ``__accounts``
     493        Return ``__accounts``.
    442494       
     495        OUTPUT:
     496
     497        - a bool
     498
    443499        EXAMPLES::
    444500       
    445501            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    457513
    458514    def add_user(self, username, password, email, account_type="user", force=False):
    459515        """
     516        Add a user with the given credentials.
     517
    460518        INPUT:
    461        
    462        
     519       
    463520        -  ``username`` - the username
    464521       
    465522        -  ``password`` - the password
    466523       
    467524        -  ``email`` - the email address
    468525       
    469         -  ``account_type`` - one of 'user', 'admin', or
    470            'guest'
     526        -  ``account_type`` - one of 'user', 'admin', or 'guest'
    471527       
    472         -  ``force`` - bool
     528        -  ``force`` - a bool (default: False)
    473529       
    474        
    475         If the method get_accounts return False then user can only be
    476         added if force=True
    477        
     530        If the method :meth:`get_accounts` returns False then user can
     531        only be added if ``force`` is True.
     532
    478533        EXAMPLES::
    479534       
    480535            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    481             sage: nb.add_user('Mark', 'password', ", force=True)
     536            sage: nb.add_user('Mark', 'password', '', force=True)
    482537            sage: nb.user('Mark')
    483538            Mark
    484539            sage: nb.add_user('Sarah', 'password', ")
    … …  
    500555
    501556    def change_password(self, username, password):
    502557        """
     558        Change a user's password.
     559
    503560        INPUT:
    504561       
     562        - ``username`` - a string, the username
    505563       
    506         -  ``username`` - the username
    507        
    508         -  ``password`` - the password to change the user's
    509            password to
    510        
     564        - ``password`` - a string, the user's new password
    511565       
    512566        EXAMPLES::
    513567       
    514568            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    515             sage: nb.add_user('Mark', 'password', ", force=True)
     569            sage: nb.add_user('Mark', 'password', '', force=True)
    516570            sage: nb.user('Mark').password()
    517571            'aajfMKNH1hTm2'
    518572            sage: nb.change_password('Mark', 'different_password')
    … …  
    523577
    524578    def del_user(self, username):
    525579        """
    526         Deletes the given user
     580        Delete the given user.
    527581       
     582        INPUT:
     583
     584        - ``username`` - a string
     585
    528586        EXAMPLES::
    529587       
    530588            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    531             sage: nb.add_user('Mark', 'password', ", force=True)
     589            sage: nb.add_user('Mark', 'password', '', force=True)
    532590            sage: nb.user('Mark')
    533591            Mark
    534592            sage: nb.del_user('Mark')
    … …  
    542600
    543601    def passwords(self):
    544602        """
    545         Return the username:password dictionary.
     603        Return a username:password dictionary.
    546604       
     605        OUTPUT:
     606
     607        - a string:string dictionary
     608
    547609        EXAMPLES::
    548610       
    549611            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    550612            sage: nb.create_default_users('password')
    551613            Creating default users.
    552             sage: nb.add_user('Mark', 'password', ", force=True)
     614            sage: nb.add_user('Mark', 'password', '', force=True)
    553615            sage: list(sorted(nb.passwords().iteritems()))
    554616            [('Mark', 'aajfMKNH1hTm2'), ('_sage_', 'aaQSqAReePlq6'), ('admin', 'aajfMKNH1hTm2'), ('guest', 'aaQSqAReePlq6'), ('pub', 'aaQSqAReePlq6')]
    555617        """
    … …  
    557619
    558620    def user_conf(self, username):
    559621        """
    560         Return a user's configuration.
     622        Return a user's configuration object.
    561623       
     624        OUTPUT:
     625
     626        - an instance of Configuration.
     627
    562628        EXAMPLES::
    563629       
    564630            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    581647    ##########################################################
    582648    def _initialize_worksheet(self, src, W):
    583649        r"""
    584         ``src`` and ``W`` are worksheets and
    585         ``W`` is brand new.
     650        Initialize a new worksheet from a source worksheet.
     651
     652        INPUT:
     653
     654        - ``src`` - a Worksheet instance; the source
     655
     656        - ``W`` - a new Worksheet instance; the target
    586657        """
    587658        # Copy over images and other files
    588659        data = src.data_directory()
    … …  
    595666
    596667    def publish_worksheet(self, worksheet, username):
    597668        r"""
    598         Publish the given worksheet.
     669        Publish a user's worksheet.  This creates a new worksheet in
     670        the 'pub' directory with the same contents as ``worksheet``.
    599671       
    600         This creates a new worksheet in the ``pub`` directory
    601         with the same contents as ``worksheet``.
    602        
     672        INPUT:
     673
     674        - ``worksheet`` - an instance of Worksheet
     675
     676        - ``username`` - a string
     677
     678        OUTPUT:
     679
     680        - a new or existing published instance of Worksheet
     681
    603682        EXAMPLES::
    604683       
    605684            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    606             sage: nb.add_user('Mark','password',",force=True)
     685            sage: nb.add_user('Mark','password','',force=True)
    607686            sage: W = nb.new_worksheet_with_title_from_text('First steps', owner='Mark')
    608687            sage: nb.worksheet_names()
    609688            ['Mark/0']
    … …  
    691770    def delete_worksheet(self, filename):
    692771        """
    693772        Delete the given worksheet and remove its name from the worksheet
    694         list.
     773        list.  Raise a KeyError, if it is missing.
     774
     775        INPUT:
     776
     777        - ``filename`` - a string
    695778        """
    696779        if not (filename in self.__worksheets.keys()):
    697780            print self.__worksheets.keys()
    … …  
    715798       
    716799        INPUT:
    717800       
    718        
    719801        -  ``username`` - a string
    720802       
    721        
    722803        This empties the trash for the given user and cleans up all files
    723804        associated with the worksheets that are in the trash.
    724805       
    … …  
    745826        """
    746827        Return a list of all the names of worksheets in this notebook.
    747828       
    748         OUTPUT: list of strings.
     829        OUTPUT:
     830
     831        - a list of strings.
    749832       
    750833        EXAMPLES: We make a new notebook with two users and two worksheets,
    751834        then list their names::
    … …  
    764847
    765848    def migrate_old(self):
    766849        """
    767         Migrate all old worksheets, i.e., ones with no owner, to
    768         ``/pub``.
     850        Migrate all old worksheets, i.e., those with no owner, to
     851        ``/pub``.  Currently, this always raises a
     852        NotImplementedError.
    769853        """
    770854        raise NotImplementedError
    771855        for w in self.__worksheets.itervalues():
    … …  
    9271011    ##########################################################
    9281012    def export_worksheet(self, worksheet_filename, output_filename, verbose=True):
    9291013        """
    930         Export a worksheet with given directory filenmae to
    931         output_filename.
     1014        Export a worksheet, creating a sws file on the file system.
    9321015       
    9331016        INPUT:
    9341017       
     1018        -  ``worksheet_filename`` - a string
    9351019       
    936         -  ``worksheet_filename`` - string
     1020        -  ``output_filename`` - a string
    9371021       
    938         -  ``output_filename`` - string
    939        
    940         -  ``verbose`` - bool (default: True) if True print
    941            some the tar command used to extract the sws file.
    942        
    943        
    944         OUTPUT: creates a file on the filesystem
     1022        - ``verbose`` - a bool (default: True); if True, print the tar
     1023           command used to create the sws file.
    9451024        """
    9461025        W = self.get_worksheet_with_filename(worksheet_filename)
    9471026        W.save()
    … …  
    9681047
    9691048    def import_worksheet(self, filename, owner):
    9701049        r"""
    971         Upload the worksheet with name ``filename`` and make it
    972         have the given owner.
     1050        Import a worksheet with the given ``filename`` and set its
     1051        ``owner``.  If the file extension is not txt or sws, raise a
     1052        ValueError.
    9731053       
    9741054        INPUT:
    9751055       
    976        
    9771056        -  ``filename`` - a string
    9781057       
    9791058        -  ``owner`` - a string
    9801059       
    981        
    9821060        OUTPUT:
    9831061       
    984        
    985         -  ``worksheet`` - a newly created worksheet
    986        
     1062        -  ``worksheet`` - a newly created Worksheet instance
    9871063       
    9881064        EXAMPLES: We create a notebook and import a plain text worksheet
    9891065        into it.
    … …  
    10241100       
    10251101        INPUT:
    10261102       
     1103        -  ``filename`` - a string; a filename that ends in .txt
    10271104       
    1028         -  ``filename`` - string; a filename that ends in .txt
     1105        -  ``owner`` - a string; the imported worksheet's owner
    10291106       
    1030         -  ``owner`` - string; who will own this worksheet when
    1031            imported
    1032        
    1033        
    1034         OUTPUT: a new worksheet
     1107        OUTPUT:
     1108
     1109        -  a new instance of Worksheet
    10351110       
    10361111        EXAMPLES: We write a plain text worksheet to a file and import it
    10371112        using this function.
    … …  
    10551130    def _import_worksheet_sws(self, filename, owner, verbose=True):
    10561131        r"""
    10571132        Import an sws format worksheet into this notebook as a new
    1058         worksheet.
     1133        worksheet.  If the worksheet cannot be read, raise a
     1134        ValueError.
    10591135       
    10601136        INPUT:
    10611137       
    1062        
    1063         -  ``filename`` - string; a filename that ends in .sws;
     1138        - ``filename`` - a string; a filename that ends in .sws;
    10641139           internally it must be a tar'd bz2'd file.
    10651140       
    1066         -  ``owner`` - string
     1141        - ``owner`` - a string
    10671142       
    1068         -  ``verbose`` - bool (default: True) if True print
    1069            some the tar command used to extract the sws file.
     1143        - ``verbose`` - a bool (default: True) if True print some the
     1144           tar command used to extract the sws file.
    10701145       
    1071        
    1072         OUTPUT: a new worksheet
     1146        OUTPUT:
     1147
     1148        - a new Worksheet instance
    10731149       
    10741150        EXAMPLES: We create a notebook, then make a worksheet from a plain
    10751151        text file first.
    … …  
    10961172            sage: nb._import_worksheet_sws('tmp.sws', 'admin', verbose=False)
    10971173            [Cell 0; in=2+3, out=]
    10981174       
    1099         Yep, it's there now (as admin/2)::
     1175        Yes, it's there now (as admin/2)::
    11001176       
    11011177            sage: nb.worksheet_names()
    11021178            ['admin/0', 'admin/2']
    … …  
    11671243
    11681244    def plain_text_worksheet_html(self, filename, prompts=True):
    11691245        """
    1170         Outputs html containing the plain text version of a worksheet
     1246        Return HTML containing the plain text version of a worksheet.
    11711247
    11721248        INPUT:
    1173         - ``filename`` - filename of a worksheet
    1174         - ``prompts``  - boolean
     1249       
     1250        - ``filename`` - a string; filename of a worksheet
     1251       
     1252        - ``prompts`` - a bool (default: True); whether to format the
     1253          text for inclusion in docstrings
    11751254
    11761255        OUTPUT:
    1177         - A string containing the html for the plain text version
     1256       
     1257        - a string - the worksheet's HTML representation
    11781258        """
    11791259        worksheet = self.get_worksheet_with_filename(filename)
    11801260        text = escape(worksheet.plain_text(prompts = prompts))
    … …  
    11931273
    11941274    def DIR(self):
    11951275        """
    1196         Return the absolute path to the directory that contains the Sage
    1197         Notebook directory.
     1276        Return the absolute path to the parent of this Notebook
     1277        instance's home directory.
     1278
     1279        OUTPUT:
     1280
     1281        - a string
    11981282        """
    11991283        P = os.path.abspath('%s/..'%self.__dir)
    12001284        if not os.path.exists(P):
    … …  
    13091393        return s
    13101394
    13111395    def worksheet_html(self, filename, do_print=False):
    1312         """
    1313         Returns the HTML for the worksheet.
     1396        r"""
     1397        Return the HTML for a given worksheet.
    13141398
    13151399        INPUT:
    1316         - ``username`` - a string
    1317         - ``worksheet`` - an instance of Worksheet
     1400       
     1401        - ``filename`` - a string; the worksheet's filename
     1402
     1403        - ``do_print`` - a bool (default: False); whether this is a
     1404          printed worksheet
    13181405
    13191406        OUTPUT:
    1320         - a string containing the HTML
     1407       
     1408        - a string - the worksheet rendered as HTML
    13211409
    13221410        EXAMPLES::
    13231411       
    … …  
    13591447    # Revision history for a worksheet
    13601448    ##########################################################
    13611449    def html_worksheet_revision_list(self, username, worksheet):
    1362         """
    1363         Returns the HTML for the revision list of a worksheet.
     1450        r"""
     1451        Return HTML for the revision list of a worksheet.
    13641452
    13651453        INPUT:
     1454       
    13661455        - ``username`` - a string
     1456       
    13671457        - ``worksheet`` - an instance of Worksheet
    13681458
    13691459        OUTPUT:
    1370         - a string containing the HTML
     1460
     1461        - a string - the HTML for the revision list
    13711462
    13721463        EXAMPLES::
    13731464       
    … …  
    13891480
    13901481
    13911482    def html_specific_revision(self, username, ws, rev):
    1392         """
    1393         Returns the HTML for a revision of the worksheet.
     1483        r"""
     1484        Return the HTML for a specific revision of a worksheet.
    13941485
    13951486        INPUT:
     1487       
    13961488        - ``username`` - a string
     1489       
    13971490        - ``ws`` - an instance of Worksheet
     1491       
    13981492        - ``rev`` - a string containing the key of the revision
    13991493
    14001494        OUTPUT:
    1401         - a string containing the HTML
     1495       
     1496        - a string - the revision rendered as HTML
    14021497        """
    14031498        t = time.time() - float(rev[:-4])
    14041499        time_ago = worksheet.convert_seconds_to_meaningful_time_span(t)
    … …  
    14341529       
    14351530
    14361531    def html_share(self, worksheet, username):
    1437         """
    1438         Returns the HTML for the share page of a worksheet.
     1532        r"""
     1533        Return the HTML for the "share" page of a worksheet.
    14391534
    14401535        INPUT:
     1536       
    14411537        - ``username`` - a string
     1538       
    14421539        - ``worksheet`` - an instance of Worksheet
    14431540
    14441541        OUTPUT:
    1445         - a string containing the HTML
     1542
     1543        - string - the share page's HTML representation
    14461544       
    14471545        EXAMPLES::
    14481546       
    … …  
    14661564
    14671565
    14681566    def html_download_or_delete_datafile(self, ws, username, filename):
    1469         """
    1470         Returns the HTML for the download or delete datafile page.
     1567        r"""
     1568        Return the HTML for the download or delete datafile page.
    14711569
    14721570        INPUT:
     1571       
    14731572        - ``username`` - a string
     1573       
    14741574        - ``ws`` - an instance of Worksheet
    1475         - ``filename`` - the name of the file
     1575       
     1576        - ``filename`` - a string; the name of the file
    14761577
    14771578        OUTPUT:
    1478         - a string containing the HTML
     1579       
     1580        - a string - the page rendered as HTML
    14791581
    14801582        EXAMPLES::
    14811583       
    … …  
    15541656
    15551657    def get_worksheet_with_filename(self, filename):
    15561658        """
    1557         Get the worksheet with given filename. If there is no such
    1558         worksheet, raise a ``KeyError``.
     1659        Get the worksheet with the given filename.  If there is no
     1660        such worksheet, raise a ``KeyError``.
    15591661       
    1560         INPUT: string OUTPUT: a worksheet or KeyError
     1662        INPUT:
     1663
     1664        - ``filename`` - a string
     1665
     1666        OUTPUT:
     1667
     1668        - a Worksheet instance
    15611669        """
    15621670        if self.__worksheets.has_key(filename):
    15631671            return self.__worksheets[filename]
    … …  
    16131721    # HTML -- generate most html related to the whole notebook page
    16141722    ###########################################################
    16151723    def html_debug_window(self):
    1616         """
    1617         Returns the HTML for the debug window
     1724        r"""
     1725        Return the HTML for the debug window.
    16181726
    16191727        OUTPUT:
    1620         - the HTML for the debug window
     1728       
     1729        - a string - the debug window rendered as HTML
    16211730   
    16221731        EXAMPLES::
    16231732
    1624         sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    1625         sage: print(nb.html_debug_window())
    1626         <div class='debug_window'>
    1627             <div class='debug_output'><pre id='debug_output'></pre></div>
    1628             <textarea rows=5 id='debug_input' class='debug_input'
    1629                       onKeyPress='return debug_keypress(event);'
    1630                       onFocus='debug_focus();' onBlur='debug_blur();'></textarea>
    1631         </div>
     1733            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
     1734            sage: nb.html_debug_window()
     1735            "\n<div class='debug_window'>...</div>"
    16321736        """
    16331737        return template("notebook/debug_window.html")
    16341738
    16351739   
    16361740    def html_plain_text_window(self, worksheet, username):
    1637         """
    1638         Returns a window that displays a plain text version of the
    1639         worksheet
    1640        
     1741        r"""
     1742        Return HTML for the window that displays a plain text version
     1743        of the worksheet.
     1744
    16411745        INPUT:
    1642         -  ``worksheet`` - a worksheet
    1643         -  ``username`` - name of the user
     1746
     1747        -  ``worksheet`` - a Worksheet instance
     1748
     1749        -  ``username`` - a string
    16441750
    16451751        OUTPUT:
    1646         - a window that displays a plain text version of the
    1647         worksheet
    1648        
     1752
     1753        - a string - the plain text window rendered as HTML
     1754
    16491755        EXAMPLES::
    16501756       
    16511757            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
    … …  
    16661772                       
    16671773    def html_edit_window(self, worksheet, username):
    16681774        r"""
    1669         Return a window for editing ``worksheet``.
     1775        Return HTML for a window for editing ``worksheet``.
    16701776       
    16711777        INPUT:
     1778       
    16721779        - ``username`` - a string containing the username
     1780       
    16731781        - ``worksheet`` - a Worksheet instance
    16741782
    16751783        OUTPUT:
    1676         - html for a window for editing ``worksheet``.
     1784       
     1785        - a string - the editing window's HTML representation
    16771786
    16781787        EXAMPLES::
    16791788       
    … …  
    16951804                        sage_jsmath_macros = sage_jsmath_macros)
    16961805   
    16971806    def html_beforepublish_window(self, worksheet, username):
    1698         """
    1699         Return the html code for a page dedicated to worksheet publishing
    1700         prior to the publication of the given worksheet.
     1807        r"""
     1808        Return HTML for the warning and decision page displayed prior
     1809        to publishing the given worksheet.
    17011810       
    17021811        INPUT:
    1703         - ``worksheet`` - instance of Worksheet
    1704         - ``username`` - string
     1812       
     1813        - ``worksheet`` - an instance of Worksheet
     1814       
     1815        - ``username`` - a string
     1816
     1817        OUTPUT:
     1818
     1819        - a string - the pre-publication page rendered as HTML
    17051820
    17061821        EXAMPLES::
    17071822       
    … …  
    17281843                        sage_jsmath_macros = sage_jsmath_macros)
    17291844       
    17301845    def html_afterpublish_window(self, worksheet, username, url, dtime):
    1731         """
    1732         Return the html code for a page dedicated to worksheet publishing
    1733         after the publication of the given worksheet.
     1846        r"""
     1847        Return HTML for a given worksheet's post-publication page.
    17341848       
    17351849        INPUT:
    1736         - ``worksheet`` - instance of Worksheet
    1737         - ``username`` - string
    1738         - ``url`` - a string representing the url of the published worksheet
    1739         - ``dtime`` - instance of time.struct_time representing the publishing time
     1850       
     1851        - ``worksheet`` - an instance of Worksheet
     1852       
     1853        - ``username`` - a string
     1854       
     1855        - ``url`` - a string representing the URL of the published
     1856          worksheet
     1857       
     1858        - ``dtime`` - an instance of time.struct_time representing the
     1859          publishing time
     1860
     1861        OUTPUT:
     1862
     1863        - a string - the post-publication page rendered as HTML
     1864
    17401865        """
    17411866        from time import strftime
    17421867        time = strftime("%B %d, %Y %I:%M %p", dtime)
    … …  
    17501875                        sage_jsmath_macros = sage_jsmath_macros)
    17511876
    17521877    def html_upload_data_window(self, ws, username):
    1753         """
    1754         Returns the html for the "Upload Data" window
     1878        r"""
     1879        Return HTML for the "Upload Data" window.
    17551880
    17561881        INPUT:
    1757         - ``worksheet`` - instance of Worksheet
    1758         - ``username`` - string
     1882       
     1883        - ``worksheet`` - an instance of Worksheet
     1884       
     1885        - ``username`` - a string
     1886
     1887        OUTPUT:
     1888
     1889        - a string - the HTML representation of the data upload window
    17591890
    17601891        EXAMPLES::
    17611892       
    … …  
    17731904   
    17741905
    17751906    def html(self, worksheet_filename=None, username='guest', show_debug=False, admin=False):
    1776         """
    1777         Returns the html for index page of a worksheet.
     1907        r"""
     1908        Return the HTML for a worksheet's index page.
    17781909
    17791910        INPUT:
    1780         - ``worksheet_filename`` - a string
    1781         - ``username`` - a string
    1782         - ``show_debug`` - a boolean
    1783         - ``admin`` - a boolean
     1911       
     1912        - ``worksheet_filename`` - a string (default: None)
     1913       
     1914        - ``username`` - a string (default: 'guest')
     1915
     1916        - ``show_debug`` - a bool (default: False)
     1917       
     1918        - ``admin`` - a bool (default: False)
     1919
     1920        OUTPUT:
     1921
     1922        - a string - the worksheet rendered as HTML
    17841923
    17851924        EXAMPLES::
    17861925       
    … …  
    18201959
    18211960
    18221961    def html_worksheet_settings(self, ws, username):
    1823         """
    1824         Returns the html for the setings page of the worksheet.
     1962        r"""
     1963        Return the HTML for a worksheet's settings page.
    18251964       
    18261965        INPUT:
    1827         - ``ws`` - instance of Worksheet
    1828         - ``username`` - string
     1966       
     1967        - ``ws`` - an instance of Worksheet
     1968       
     1969        - ``username`` - a string
     1970
     1971        OUTPUT:
     1972
     1973        - a string - HTML representation of the settings page
    18291974
    18301975        EXAMPLES::
    18311976       
    … …  
    18562001        return s
    18572002
    18582003    def html_doc(self, username):
    1859         """
    1860         Returns the html for the documentation pages.
     2004        r"""
     2005        Return the HTML for the a documentation page.
    18612006       
    18622007        INPUT:
    1863         - ``worksheet_filename`` - a string
     2008       
    18642009        - ``username`` - a string
    1865         - ``show_debug`` - a boolean
    1866         - ``admin`` - a boolean
     2010       
     2011        OUTPUT:
     2012
     2013        - a string - the doc page rendered as HTML
    18672014
    18682015        EXAMPLES::
    18692016       
    … …  
    18832030
    18842031def load_notebook(dir, address=None, port=None, secure=None):
    18852032    """
    1886     Load the notebook from the given directory, or create one in that
    1887     directory if one isn't already there.
     2033    Load and return a notebook from a given directory.  Create a new
     2034    one in that directory, if one isn't already there.
    18882035   
    18892036    INPUT:
    18902037   
    1891    
    18922038    -  ``dir`` - a string that defines a directory name
    18932039   
    1894     -  ``address`` - the address that the notebook server
    1895        will listen on
     2040    -  ``address`` - the address the server listens at
    18962041   
    18972042    -  ``port`` - the port the server listens on
    18982043   
    1899     -  ``secure`` - whether or not the notebook is secure
     2044    -  ``secure`` - whether the notebook is secure
     2045
     2046    OUTPUT:
     2047
     2048    - a Notebook instance
    19002049    """
    19012050    sobj = '%s/nb.sobj'%dir
    19022051    nb = None
    … …  
    19372086
    19382087def make_path_relative(dir):
    19392088    r"""
    1940     If easy, replace the absolute path ``dir`` by a
    1941     relative one.
     2089    Replace an absolute path with a relative path, if possible.
     2090    Otherwise, return the given path.
     2091
     2092    INPUT:
     2093
     2094    - ``dir`` - a string containing, e.g., a directory name
     2095
     2096    OUTPUT:
     2097
     2098    - a string
    19422099    """
    19432100    base, file = os.path.split(dir)
    19442101    if os.path.exists(file):
    … …  
    19542111
    19552112def sort_worksheet_list(v, sort, reverse):
    19562113    """
     2114    Sort a given list on a given key, in a given order.
     2115
    19572116    INPUT:
    19582117   
     2118    - ``sort`` - a string; 'last_edited', 'owner', 'rating', or 'name'
    19592119   
    1960     -  ``sort`` - 'last_edited', 'owner', 'rating', or
    1961        'name'
    1962    
    1963     -  ``reverse`` - if True, reverse the order of the
    1964        sort.
     2120    - ``reverse`` - a bool; if True, reverse the order of the sort.
     2121
     2122    OUTPUT:
     2123
     2124    - the sorted list
    19652125    """
    19662126    f = None
    19672127    if sort == 'last_edited':

  • sage/server/notebook/sage_email.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/sage_email.py
    a b  
    66email server or anything else, since Sage already includes by default
    77a sophisticated email server (which is part of Twisted).
    88
    9 EXAMPLES:
     9EXAMPLES::
     10
    1011    sage: email('xxxsageuser@gmail.com', 'The calculation finished!')  # not tested
    1112    Child process ... is sending email to xxxsageuser@gmail.com
    1213
    … …  
    3233    OUTPUT:
    3334        string
    3435     
    35     EXAMPLES:
     36    EXAMPLES::
     37
    3638        sage: sage.server.notebook.sage_email.default_email_address()     
    3739        '...@...'
    3840    """
    … …  
    6466                        be a problem, but might be useful for certain
    6567                        users.
    6668                       
    67     EXAMPLES:
     69    EXAMPLES::
     70
    6871        sage: email('xxxsageuser@gmail.com', 'The calculation finished!')  # not tested
    6972        Child process ... is sending email to xxxsageuser@gmail.com
    7073

  • sage/server/notebook/sagetex.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/sagetex.py
    a b  
    88
    99    THIS IS ONLY A PROOF-of-CONCEPT.
    1010
    11     EXAMPLES:
     11    EXAMPLES::
     12
    1213        sage: sagetex('foo.tex')        # not tested
    1314        [pops up web browser with live version of foo.tex.]
    1415    """

  • sage/server/notebook/template.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/template.py
    a b  
    11# -*- coding: utf-8 -*-
    22"""
    3 HTML templating for the notebook
     3HTML Templating for the Notebook
    44
    55AUTHORS:
    6     -- Bobby Moretti (2007-07-18): initial version
    7     -- Timothy Clemans and Mike Hansen (2008-10-27): major update
     6
     7    - Bobby Moretti (2007-07-18): initial version
     8
     9    - Timothy Clemans and Mike Hansen (2008-10-27): major update
    810
    911"""
    1012#############################################################################
    … …  
    2224
    2325def contained_in(container):
    2426    """
    25     Returns a function which takes in an environment, context, and value
    26     and returns True if that value is in the container and False
    27     otherwise.  This is registered and used as a test in the templates.
     27    Given a container, returns a function which takes an environment,
     28    context, and value and returns True if that value is in the
     29    container and False otherwise.  This is registered and used as a
     30    test in the templates.
    2831
    29     EXAMPLES:
     32    INPUT::
     33
     34    - ``container`` - a container, e.g., a list or dictionary
     35
     36    EXAMPLES::
     37
    3038        sage: from sage.server.notebook.template import contained_in
    3139        sage: f = contained_in([1,2,3])
    3240        sage: f(None, None, 2)
    … …  
    4856
    4957def template(filename, **user_context):
    5058    """
    51     Returns a rendered template as a string.
     59    Returns HTML, CSS, etc., for a template file rendered in the given
     60    context.
    5261
    5362    INPUT:
    54         filename -- the filename of the template relative to
    55                     $SAGE_ROOT/devel/sage/sage/server/notebook/templates
    5663
    57     EXAMPLES:
     64    - ``filename`` - a string; the filename of the template relative
     65      to $SAGE_ROOT/devel/sage/sage/server/notebook/templates
     66
     67    - ``user_context`` - a dictionary; the context in which to evaluate
     68      the file's template variables
     69
     70    OUTPUT:
     71     
     72    - a string - the rendered HTML, CSS, etc.
     73
     74    EXAMPLES::
     75
    5876        sage: from sage.server.notebook.template import template
    5977        sage: s = template('yes_no.html'); type(s)
    6078        <type 'str'>

  • sage/server/notebook/twist.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/twist.py
    a b  
    134134    Returns an HTMLResponse object whose 'Content-Type' header has been set
    135135    to 'text/html; charset=utf-8
    136136
    137     EXAMPLES:
     137    EXAMPLES::
     138
    138139        sage: from sage.server.notebook.twist import HTMLResponse
    139140        sage: response = HTMLResponse(stream='<html><head><title>Test</title></head><body>Test</body></html>')
    140141        sage: response.headers

  • sage/server/notebook/user.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/user.py
    a b  
    6363
    6464    def username(self):
    6565        """
    66         EXAMPLES:
     66        EXAMPLES::
     67
    6768            sage: from sage.server.notebook.user import User
    6869            sage: User('andrew', 'tEir&tiwk!', 'andrew@matrixstuff.com', 'user').username()
    6970            'andrew'
    … …  
    7980
    8081    def conf(self):
    8182        """
    82         EXAMPLES:
     83        EXAMPLES::
     84
    8385            sage: from sage.server.notebook.user import User
    8486            sage: config = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin').conf(); config
    8587            Configuration: {}
    … …  
    102104
    103105    def password(self):
    104106        """
    105         EXAMPLES:
     107        EXAMPLES::
     108
    106109            sage: from sage.server.notebook.user import User
    107110            sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin')
    108111            sage: user.password()
    … …  
    112115
    113116    def set_password(self, password):
    114117        """
    115         EXAMPLES:
     118        EXAMPLES::
     119
    116120            sage: from sage.server.notebook.user import User
    117121            sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin')
    118122            sage: old = user.password()
    … …  
    127131
    128132    def set_hashed_password(self, password):
    129133        """
    130         EXAMPLES:
     134        EXAMPLES::
     135
    131136            sage: from sage.server.notebook.user import User
    132137            sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin')
    133138            sage: user.set_hashed_password('Crrc!')
    … …  
    138143
    139144    def get_email(self):
    140145        """
    141         EXAMPLES:
     146        EXAMPLES::
     147
    142148            sage: from sage.server.notebook.user import User
    143149            sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin')
    144150            sage: user.get_email()
    … …  
    148154
    149155    def set_email(self, email):
    150156        """
    151         EXAMPLES:
     157        EXAMPLES::
     158
    152159            sage: from sage.server.notebook.user import User
    153160            sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin')
    154161            sage: user.get_email()
    … …  
    161168       
    162169    def set_email_confirmation(self, value):
    163170        """
    164         EXAMPLES:
     171        EXAMPLES::
     172
    165173            sage: from sage.server.notebook.user import User
    166174            sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin')
    167175            sage: user.is_email_confirmed()
    … …  
    178186       
    179187    def is_email_confirmed(self):
    180188        """
    181         EXAMPLES:
     189        EXAMPLES::
     190
    182191            sage: from sage.server.notebook.user import User
    183192            sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin')
    184193            sage: user.is_email_confirmed()
    … …  
    192201
    193202    def password_is(self, password):
    194203        """
    195         EXAMPLES:
     204        EXAMPLES::
     205
    196206            sage: from sage.server.notebook.user import User
    197207            sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin')
    198208            sage: user.password_is('ecc')
    … …  
    206216
    207217    def account_type(self):
    208218        """
    209         EXAMPLES:
     219        EXAMPLES::
     220
    210221            sage: from sage.server.notebook.user import User
    211222            sage: User('A', account_type='admin').account_type()
    212223            'admin'
    … …  
    221232   
    222233    def is_admin(self):
    223234        """
    224         EXAMPLES:
     235        EXAMPLES::
     236
    225237            sage: from sage.server.notebook.user import User
    226238            sage: User('A', account_type='admin').is_admin()
    227239            True
    … …  
    232244
    233245    def is_guest(self):
    234246        """
    235         EXAMPLES:
     247        EXAMPLES::
     248
    236249            sage: from sage.server.notebook.user import User
    237250            sage: User('A', account_type='guest').is_guest()
    238251            True

  • sage/server/notebook/worksheet.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/worksheet.py
    a b  
    12361236        OUTPUT:
    12371237       
    12381238       
    1239         -  ``string`` - a string of HTML as a bunch of table
     1239        -  ``string`` -- a string of HTML as a bunch of table
    12401240           rows.
    12411241       
    12421242       
    … …  
    20972097        -  ``text`` - a string
    20982098       
    20992099        -  ``ignore_ids`` - bool (default: False); if True
    2100            ignore all the id's in the code block.
     2100           ignore all the id's in the {{{}}} code block.
    21012101       
    21022102       
    21032103        EXAMPLES: We create a new test notebook and a worksheet.
    … …  
    22122212    ##########################################################
    22132213    def html(self, include_title=True, do_print=False,
    22142214             confirm_before_leave=False, read_only=False):
    2215         """
    2216         INPUT:
     2215        r"""
     2216        INPUT:
     2217
     2218       
    22172219        - publish - a boolean stating whether the worksheet is published
     2220       
    22182221        - do_print - a boolean
    22192222
    22202223        OUTPUT:
    2221         - returns the html for the worksheet
     2224
     2225       
     2226        - string -- the html for the worksheet
    22222227       
    22232228        EXAMPLES::
    22242229       
    … …  
    22752280    def html_save_discard_buttons(self):
    22762281        r"""
    22772282        OUTPUT:
    2278         - returns the html for the save, discard, etc. buttons
     2283       
     2284        - string -- the html for the save, discard, etc. buttons
    22792285
    22802286        EXAMPLES::
    22812287
    … …  
    22892295    def html_share_publish_buttons(self, select=None, backwards=False):
    22902296        r"""
    22912297        INPUT:
     2298
     2299       
    22922300        - select - a boolean
     2301       
    22932302        - backwards - a boolean
    22942303
    22952304        OUTPUT:
    2296         - returns the html for the share, publish, etc. buttons
     2305
     2306       
     2307        - string -- the html for the share, publish, etc. buttons
    22972308
    22982309        EXAMPLES::
    22992310
    … …  
    23102321# <option title="Configure this worksheet" value="worksheet_settings();">Worksheet settings</option>
    23112322
    23122323    def html_menu(self):
    2313         """
    2314         OUTPUT:
    2315         - returns the html for the menus of the worksheet
     2324        r"""
     2325        OUTPUT:
     2326       
     2327        - string -- the html for the menus of the worksheet
    23162328
    23172329        EXAMPLES::
    23182330       
    … …  
    23302342                        doc_worksheet = self.is_doc_worksheet())
    23312343
    23322344    def html_worksheet_body(self, do_print, publish=False):
    2333         """
    2334         INPUT:
     2345        r"""
     2346        INPUT:
     2347
     2348       
    23352349        - publish - a boolean stating whether the worksheet is published
     2350       
    23362351        - do_print - a boolean
    23372352
    23382353        OUTPUT:
    2339         - returns the html for the File menu of the worksheet
     2354
     2355       
     2356        - string -- the html for the File menu of the worksheet
    23402357
    23412358        EXAMPLES::
    23422359       
    … …  
    40204037def format_completions_as_html(cell_id, completions):
    40214038    """
    40224039    INPUT:
     4040
     4041   
    40234042    - cell_id - id for the cell of the completions
     4043   
    40244044    - completions - list of completions in row-major order
    40254045   
    40264046    OUTPUT:
    4027     - html for the completions formatted in rows and columns
     4047
     4048   
     4049    - string -- html for the completions formatted in rows and columns
    40284050    """
    40294051    if len(completions) == 0:
    40304052        return ''

  • sage/server/simple/twist.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/simple/twist.py
    a b  
    11r"""
    2 Simple Sage API
     2Simple Sage Server API
    33
    44This module provides a very simple API for interacting with a Sage session
    55over HTTP. It runs as part of the notebook server.

  • sage/server/support.py 

    diff -r 832b46058006 -r 6b319da23983 sage/server/support.py
    a b  
    11"""
    2 Support for the Notebook (introspection and setup)
     2Support for Notebook Introspection and Setup
    33
    44AUTHORS:
    55
    66- William Stein (much of this code is from IPython).
     7
     8- Nick Alexander
    79"""
    810
    911import inspect
    … …  
    7072######################################################################
    7173def help(obj):
    7274    """
    73     Display help on s.
     75    Display HTML help for ``obj``, a Python object, module, etc.  This
     76    help is often more extensive than that given by 'obj?'.  This
     77    function does not return a value --- it prints HTML as a side
     78    effect.
    7479   
    7580    .. note::
    7681
    … …  
    7984   
    8085    INPUT:
    8186   
    82    
    83     -  ``s`` - Python object, module, etc.
    84    
    85    
    86     OUTPUT: prints out help about s; it's often more more extensive
    87     than foo?
     87    -  ``obj`` - a Python object, module, etc.
    8888   
    8989    TESTS::
    9090   
    … …  
    122122   
    123123def completions(s, globs, format=False, width=90, system="None"):
    124124    """
    125     Return a list of completions in the context of globs.
     125    Return a list of completions in the given context.
     126
     127    INPUT:
     128
     129    - ``globs`` - a string:object dictionary; context in which to
     130      search for completions, e.g., :func:`globals()`
     131
     132    - ``format`` - a bool (default: False); whether to tabulate the
     133      list
     134   
     135    - ``width`` - an int; character width of the table
     136   
     137    - ``system`` - a string (default: 'None'); system prefix for the
     138      completions
    126139    """
    127140    if system not in ['sage', 'python']:
    128141        prepend = system + '.'
    … …  
    176189
    177190def docstring(obj_name, globs, system='sage'):
    178191    r"""
    179     Format ``obj_name``'s docstring for printing in Sage
     192    Format an object's docstring to process and display in the Sage
    180193    notebook.
    181194   
     195    INPUT:
     196
     197    - ``obj_name`` - a string; a name of an object
     198
     199    - ``globs`` - a string:object dictionary; a context in which to
     200      evaluate ``obj_name``
     201
     202    - ``system`` - a string (default: 'sage'); the system to which to
     203      confine the search
     204
     205    OUTPUT:
     206
     207    - a string containing the object's file, type, definition, and
     208      docstring or a message stating the object is not defined
     209
    182210    AUTHORS:
    183211
    184212    - William Stein: partly taken from IPython for use in Sage
    … …  
    215243
    216244def source_code(s, globs, system='sage'):
    217245    r"""
    218     Format obj's source code for printing in Sage notebook.
     246    Format an object's source code to process and display in the the
     247    Sage notebook.
    219248   
     249    INPUT:
     250
     251    - ``s`` - a string; a name of an object
     252
     253    - ``globs`` - a string:object dictionary; a context in which to
     254      evaluate ``s``
     255
     256    - ``system`` - a string (default: 'sage'); the system to which to
     257      confine the search
     258
     259    OUTPUT:
     260
     261    - a string containing the object's file, starting line number, and
     262      source code
     263
    220264    AUTHORS:
    221265
    222266    - William Stein: partly taken from IPython for use in Sage
    … …  
    340384
    341385def syseval(system, cmd, dir=None):
    342386    """
     387    Evaluate an input with a "system" object that can evaluate inputs
     388    (e.g., python, gap).
     389
    343390    INPUT:
    344         system -- an object with an eval method that takes as input
    345                   a cmd (a string), and two dictionaries:
    346                            sage_globals and locals.
    347         dir -- an optional directory to change to before
    348                calling system.eval.
     391       
     392    - ``system`` - an object with an eval method that takes an input
     393
     394    - ``cmd`` - a string input
     395
     396    - ``sage_globals`` - a string:object dictionary
     397
     398    - dir - a string (default: None); an optional directory to change
     399      to before calling :func:`system.eval`
    349400
    350401    OUTPUT:
    351         The output of system.eval is returned.
     402
     403    - :func:`system.eval`'s output
    352404                 
    353     EXAMPLES:
     405    EXAMPLES::
     406
    354407        sage: from sage.misc.python import python
    355408        sage: sage.server.support.syseval(python, '2+4/3')
    356409        3
    … …  
    379432def cython_import(filename, verbose=False, compile_message=False,
    380433                 use_cache=False, create_local_c_file=True):
    381434    """
     435    Compile a file containing Cython code, then import and return the
     436    module.  Raises an ``ImportError`` if anything goes wrong.
     437
    382438    INPUT:
    383439   
    384    
    385     -  ``filename`` - name of a file that contains cython
    386        code
    387    
     440    - ``filename`` - a string; name of a file that contains Cython
     441      code
    388442   
    389443    OUTPUT:
    390444   
    391    
    392     -  ``module`` - the module that contains the compiled
    393        cython code.
    394    
    395    
    396     Raises an ``ImportError`` exception if anything goes
    397     wrong.
     445    - the module that contains the compiled Cython code.
    398446    """
    399447    name, build_dir = sage.misc.cython.cython(filename, verbose=verbose,
    400448                                            compile_message=compile_message,
    … …  
    407455def cython_import_all(filename, globals, verbose=False, compile_message=False,
    408456                     use_cache=False, create_local_c_file=True):
    409457    """
     458    Imports all non-private (i.e., not beginning with an underscore)
     459    attributes of the specified Cython module into the given context.
     460    This is similar to::
     461
     462        from module import *
     463
     464    Raises an ``ImportError`` exception if anything goes wrong.
     465
    410466    INPUT:
    411467   
    412    
    413     -  ``filename`` - name of a file that contains cython
    414        code
    415    
    416    
    417     OUTPUT: changes globals using the attributes of the Cython module
    418     that do not begin with an underscore.
    419    
    420     Raises an ``ImportError`` exception if anything goes
    421     wrong.
     468    - ``filename`` - a string; name of a file that contains Cython
     469      code
    422470    """
    423471    m = cython_import(filename, verbose=verbose, compile_message=compile_message,
    424472                     use_cache=use_cache,