Ticket #11817: trac11817_question_mark_using_sage_getdoc.2.patch

File trac11817_question_mark_using_sage_getdoc.2.patch, 11.6 KB (added by vbraun, 8 years ago)

Rediffed for sage-5.0.rc0

  • sage/misc/interpreter.py

    # HG changeset patch
    # User Simon King <simon.king@uni-jena.de>
    # Date 1316514289 -7200
    # Node ID a4fc208910ab8352fe96a26a47cd875cf18fcea8
    # Parent  aa148c3c0d7b06fd049b9e845eebeda2421d32bf
    #11817: Improve formatting of sage docstrings, and use sage_getdoc, so that embedding info is not printed.
    
    diff --git a/sage/misc/interpreter.py b/sage/misc/interpreter.py
    a b  
    2222  -- the R.<x,y,z> = ... notation
    2323
    2424TODO:
     25
    2526  I have no plans for anything further, except to improve the
    2627  robustness of the above.  Preparsing may work incorrectly for
    2728  multi-line input lines in some cases; this will be fixed.
     
    4748Finally, I added back the M.n notation for the n-th generator
    4849of object M, again like in MAGMA.
    4950
    50 EXAMPLE:
     51EXAMPLE::
     52
    5153    sage: 2/3
    5254    2/3
    5355    sage: type(2/3)
     
    6668A fix would be to only not make what's in the brackets an
    6769Integer if what's before the bracket is a valid identifier,
    6870so the w = [5] above would work right.
     71::
    6972
    7073    sage: s = "x^3 + x + 1"
    7174    sage: s
     
    137140
    138141    INPUT:
    139142   
    140         - ``line`` -- a single line; must *not* have any newlines in it
    141         - ``continuation`` -- whether the input line is really part
    142           of the previous line, because of open parens or backslash.
     143    - ``line`` -- a single line; must *not* have any newlines in it
     144    - ``continuation`` -- whether the input line is really part
     145      of the previous line, because of open parens or backslash.
    143146    """
    144147    if '\n' in line:
    145148        raise RuntimeError, "bug in function that calls do_prefilter_paste -- there can be no newlines in the input"
     
    272275        # -*- coding: utf-8 -*-
    273276        'import os, sys\n...'
    274277
    275     TESTS::
     278    TESTS:
    276279
    277     These are some of the tests listed in PEP 263.
     280    These are some of the tests listed in PEP 263::
    278281
    279282        sage: contents = '#!/usr/bin/python\n# -*- coding: latin-1 -*-\nimport os, sys'
    280283        sage: handle_encoding_declaration(contents, sys.stdout)
     
    323326        '#!/usr/local/bin/python\nimport os, sys'
    324327
    325328
    326     NOTES::
     329    NOTES:
    327330
    328         PEP 263: http://www.python.org/dev/peps/pep-0263/
     331    - PEP 263: http://www.python.org/dev/peps/pep-0263/
     332    - PEP 263 says that Python will interpret a UTF-8 byte order mark
     333      as a declaration of UTF-8 encoding, but I don't think we do
     334      that; this function only sees a Python string so it can't
     335      account for a BOM.
     336    - We default to UTF-8 encoding even though PEP 263 says that
     337      Python files should default to ASCII.
     338    - Also see http://docs.python.org/ref/encodings.html.
    329339
    330         PEP 263 says that Python will interpret a UTF-8 byte order mark
    331         as a declaration of UTF-8 encoding, but I don't think we do
    332         that; this function only sees a Python string so it can't
    333         account for a BOM.
     340    AUTHORS:
    334341
    335         We default to UTF-8 encoding even though PEP 263 says that
    336         Python files should default to ASCII.
    337 
    338         Also see http://docs.python.org/ref/encodings.html.
    339 
    340     AUTHORS::
    341 
    342         - Lars Fischer
    343         - Dan Drake (2010-12-08, rewrite for ticket #10440)
     342    - Lars Fischer
     343    - Dan Drake (2010-12-08, rewrite for ticket #10440)
    344344    """
    345345    lines = contents.splitlines()
    346346    for num, line in enumerate(lines[:2]):
     
    392392    line), return the preparsed version of it. 
    393393
    394394    INPUT:
    395         block -- string (usually a single line, but not always)
    396         continuation -- whether or not this line is a continuation.
     395
     396    - block -- string (usually a single line, but not always)
     397    - continuation -- whether or not this line is a continuation.
    397398    """
    398399    try:
    399400        block2 = ''
     
    435436    Turn on or off the Sage preparser.
    436437
    437438    INPUT:
    438         - ``on`` -- bool (default: True) if True turn on preparsing; if False, turn it off.
    439439
    440     EXAMPLES:
     440    - ``on`` -- bool (default: True) if True turn on preparsing; if False, turn it off.
     441
     442    EXAMPLES::
     443
    441444        sage: 2/3
    442445        2/3
    443446        sage: preparser(False)
     
    459462import sagedoc
    460463import sageinspect
    461464import IPython.OInspect
    462 IPython.OInspect.getdoc = sagedoc.my_getdoc
     465IPython.OInspect.getdoc = sageinspect.sage_getdoc #sagedoc.my_getdoc
    463466IPython.OInspect.getsource = sagedoc.my_getsource
    464467IPython.OInspect.getargspec = sageinspect.sage_getargspec
    465468
  • sage/misc/sagedoc.py

    diff --git a/sage/misc/sagedoc.py b/sage/misc/sagedoc.py
    a b  
    1010- John Palmieri (2009-04-11): fix for #5754 plus doctests
    1111- Dan Drake (2009-05-21): refactor search_* functions, use system 'find' instead of sage -grep
    1212- John Palmieri (2009-06-28): don't use 'find' -- use Python (os.walk, re.search) instead.
    13 - Simon King (2011-09-19): use os.linesep, avoid destruction of embedding information,
    14   enable nodetex in a docstring.
     13- Simon King (2011-09): Use os.linesep, avoid destruction of embedding information,
     14  enable nodetex in a docstring. Consequently use sage_getdoc.
    1515
    1616TESTS:
    1717
     
    162162    ``math_substitutes`` and ``nonmath_substitutes``.  If True, then
    163163    only do ``nonmath_substitutes``.
    164164
    165     OUTPUT: string
     165    OUTPUT:
     166
     167    string
    166168
    167169    EXAMPLES::
    168170
     
    331333    return s
    332334
    333335def format(s, embedded=False):
    334     r"""
     336    r"""noreplace
    335337    Format Sage documentation ``s`` for viewing with IPython.
    336338
    337339    This calls ``detex`` on ``s`` to convert LaTeX commands to plain
    338     text, and if ``s`` contains a string of the form "<<<obj>>>",
    339     then it replaces it with the docstring for "obj".
     340    text, unless the directive ``nodetex`` is given in the first line
     341    of the string.
     342
     343    Also, if ``s`` contains a string of the form ``<<<obj>>>``, then
     344    it replaces it with the docstring for ``obj``, unless the
     345    directive ``noreplace`` is given in the first line. If an error
     346    occurs under the attempt to find the docstring for ``obj``, then
     347    the substring ``<<<obj>>>`` is preserved.
     348
     349    Directives must be separated by a comma.
    340350
    341351    NOTE:
    342352
     
    366376    don't modify any TeX commands::
    367377   
    368378        sage: format("nodetex\n`x \\geq y`")
    369         '\n`x \\geq y`'
     379        '`x \\geq y`'
    370380
    371381    Testing a string enclosed in triple angle brackets::
    372382
     
    389399    a ``nodetex`` directive in the first "essential" line of the doc string
    390400    is recognised. That has been implemented in trac ticket #11815::
    391401
    392         sage: r = 'File: _local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx (starting at line 6)\nnodetex\nsome doc for a cython method\n`x \\geq y`'
     402        sage: r = 'File: _local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx (starting at line 6)\nnodetex\nsome doc for a cython method\n`x \geq y`'
    393403        sage: print format(r)
    394404        File: _local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx (starting at line 6)
    395405        <BLANKLINE>
     
    416426            `x \geq y`
    417427        <BLANKLINE>
    418428
     429    We check that the ``noreplace`` directive works, even combined with ``nodetex`` and
     430    an embedding information (see trac ticket #11817)::
     431
     432        sage: print format('File: bla.py (starting at line 1)\nnodetex, noreplace\n<<<identity_matrix>>>`\\not= 0`')
     433        File: bla.py (starting at line 1)
     434        <<<identity_matrix>>>`\not= 0`
     435
     436    If replacement is impossible, then no error is raised::
     437
     438        sage: print format('<<<bla\n<<<bla>>>\n<<<identity_matrix>>>')
     439        <<<bla <<<bla>>>
     440        <BLANKLINE>
     441        Definition: identity_matrix(ring, n=0, sparse=False)
     442        <BLANKLINE>
     443           Return the n x n identity matrix over the given ring.
     444        ...
     445
    419446    """
    420447    if not isinstance(s, str):
    421448        raise TypeError, "s must be a string"
     
    431458        from sage.misc.sageinspect import _extract_embedded_position
    432459        if _extract_embedded_position(first_line) is not None:
    433460            embedding_info = first_line + os.linesep
    434             s = s[first_newline+1:]
     461            s = s[first_newline+len(os.linesep):]
    435462            # Hence, by now, s starts with the second line.
    436463    else:
    437464        from sage.misc.sageinspect import _extract_embedded_position
     
    443470    s = s.lstrip(os.linesep)
    444471
    445472    # parse directives at beginning of docstring
    446     # currently, only 'nodetex' is supported.
     473    # currently, only 'nodetex' and 'noreplace' are supported.
    447474    # 'no' + 'doctest' may be supported eventually (don't type that as
    448475    # one word, or the whole file will not be doctested).
    449476    first_newline = s.find(os.linesep)
     
    454481    # Moreover, we must strip blank space in order to get the directives
    455482    directives = [ d.strip().lower() for d in first_line.split(',') ]
    456483
     484    if 'noreplace' in directives or 'nodetex' in directives:
     485        s = s[first_newline+len(os.linesep):]
     486
    457487    import sage.all
    458488    import sage.server.support
    459489    docs = set([])
    460     while True:
    461         i = s.find("<<<")
    462         if i == -1: break
    463         j = s[i+3:].find('>>>')
    464         if j == -1: break
    465         obj = s[i+3:i+3+j]
    466         if obj in docs:
    467             t = ''
    468         else:
    469             x = eval('sage.all.%s'%obj, locals())
    470             t0 = sage.misc.sageinspect.sage_getdef(x, obj)
    471             t1 = my_getdoc(x)
    472             t = 'Definition: ' + t0 + '\n\n' + t1
    473             docs.add(obj)
    474         s = s[:i] + '\n' + t + s[i+6+j:]
     490    if 'noreplace' not in directives:
     491        i_0 = 0
     492        while True:
     493            i = s[i_0:].find("<<<")
     494            if i == -1: break
     495            j = s[i_0+i+3:].find('>>>')
     496            if j == -1: break
     497            obj = s[i_0+i+3 : i_0+i+3+j]
     498            if obj in docs:
     499                t = ''
     500            else:
     501                try:
     502                    x = eval('sage.all.%s'%obj, locals())
     503                except AttributeError:
     504                    # A pair <<<...>>> has been found, but the object not.
     505                    i_0 += i+6+j
     506                    continue
     507                except SyntaxError:
     508                    # This is a simple heuristics to cover the case of
     509                    # a non-matching set of <<< and >>>
     510                    i_0 += i+3
     511                    continue
     512                t0 = sage.misc.sageinspect.sage_getdef(x, obj)
     513                t1 = sage.misc.sageinspect.sage_getdoc(x)
     514                t = 'Definition: ' + t0 + '\n\n' + t1
     515                docs.add(obj)
     516            s = s[:i_0+i] + '\n' + t + s[i_0+i+6+j:]
     517            i_0 += i
    475518
    476519    if 'nodetex' not in directives:
    477520        s = process_dollars(s)
    478521        s = process_mathtt(s, embedded=embedded)
    479522        s = detex(s, embedded=embedded)
    480     else:
    481         # strip the 'nodetex' directive from s
    482         s = s.replace('nodetex', '', 1)
    483523    return embedding_info+s
    484524
    485525def format_src(s):
     
    10761116#######################################
    10771117import sageinspect
    10781118
    1079 def my_getdoc(obj):
    1080     """
    1081     Retrieve the documentation for ``obj``.
    1082 
    1083     INPUT: ``obj`` - a Sage object, function, etc.
    1084 
    1085     OUTPUT: its documentation (string)
    1086    
    1087     EXAMPLES::
    1088 
    1089         sage: from sage.misc.sagedoc import my_getdoc
    1090         sage: s = my_getdoc(identity_matrix)
    1091         sage: type(s)
    1092         <type 'str'>
    1093     """
    1094     try:
    1095         ds = obj._sage_doc_()
    1096     except (AttributeError, TypeError):  # TypeError for interfaces
    1097         try:
    1098             ds = sageinspect.sage_getdoc(obj)
    1099         except:
    1100             return None
    1101     if ds is None:
    1102         return None
    1103     return ds
    1104 
    11051119def my_getsource(obj, is_binary):
    11061120    """
    11071121    Retrieve the source code for ``obj``.