Ticket #13116: trac_13116-trac-docstring.patch

File trac_13116-trac-docstring.patch, 3.9 KB (added by jhpalmieri, 10 years ago)

Sage library

  • doc/common/conf.py 

    # HG changeset patch
# User J. H. Palmieri <palmieri@math.washington.edu>
# Date 1339700920 25200
# Node ID 762d318f6430611e610cf023daf6bc73ee28bd3e
# Parent  4ea8179d12934e09b7cdca97a354542caaef9cad
Deal with :trac: markup when doing introspection.

diff --git a/doc/common/conf.py b/doc/common/conf.py
    a b pythonversion = sys.version.split(' ')[0 
    127127# Sage trac ticket shortcuts. For example, :trac:`7549` .
    128128extlinks = {
    129129    'python': ('http://docs.python.org/release/'+pythonversion+'/%s', ''),
    130     'trac': ('http://trac.sagemath.org/sage_trac/ticket/%s', 'trac ticket #'),
     130    'trac': ('http://trac.sagemath.org/%s', 'trac ticket #'),
    131131    'wikipedia': ('http://en.wikipedia.org/wiki/%s', 'Wikipedia article ')}
    132132
    133133# Options for HTML output

  • doc/en/introspect/conf.py 

    diff --git a/doc/en/introspect/conf.py b/doc/en/introspect/conf.py
    a b import sys, os 
    66sys.path.append(os.environ['SAGE_DOC'])
    77from common.conf import *
    88
    9 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.jsmath', 'sphinx.ext.todo']
     9extensions = ['sphinx.ext.autodoc', 'sphinx.ext.jsmath', 'sphinx.ext.todo',
     10              'sphinx.ext.extlinks']
    1011
    1112templates_path = ['templates']
    1213html_static_path = ['static']

  • sage/misc/sagedoc.py 

    diff --git a/sage/misc/sagedoc.py b/sage/misc/sagedoc.py
    a b def process_dollars(s): 
    296296            s = s[:m.start()] + "$" + s[m.end():]
    297297    return s
    298298
     299def process_extlinks(s, embedded=False):
     300    r"""nodetex
     301
     302    In docstrings at the command line, process markup related to the
     303    Sphinx extlinks extension. For example, replace ``:trac:`NUM```
     304    with ``http://trac.sagemath.org/NUM``, and similarly with
     305    ``:python:TEXT`` and ``:wikipedia:TEXT``, looking up the url from
     306    the dictionary ``extlinks`` in SAGE_ROOT/devel/doc/common/conf.py.
     307    If ``TEXT`` is of the form ``blah <LINK>``, then it uses ``LINK``
     308    rather than ``TEXT`` to construct the url.
     309
     310    In the notebook, don't do anything: let sphinxify take care of it.
     311
     312    INPUT:
     313
     314    - ``s`` -- string, in practice a docstring
     315    - ``embedded`` -- boolean (optional, default False)
     316
     317    This function is called by :func:`format`, and if in the notebook,
     318    it sets ``embedded`` to be ``True``, otherwise ``False``.
     319
     320    EXAMPLES::
     321
     322        sage: from sage.misc.sagedoc import process_extlinks
     323        sage: process_extlinks('See :trac:`1234` for more information.')
     324        'See http://trac.sagemath.org/1234 for more information.'
     325        sage: process_extlinks('See :trac:`1234` for more information.', embedded=True)
     326        'See :trac:`1234` for more information.'
     327        sage: process_extlinks('see :python:`Implementing Descriptors <reference/datamodel.html#implementing-descriptors>` ...')
     328        'see http://docs.python.org/release/.../reference/datamodel.html#implementing-descriptors ...'
     329    """
     330    if embedded:
     331        return s
     332    oldpath = sys.path
     333    sys.path = oldpath + [os.path.join(SAGE_DOC, 'common')]
     334    from conf import pythonversion, extlinks
     335    sys.path = oldpath
     336    for key in extlinks:
     337        m = re.search(':%s:`([^`]*)`' % key, s)
     338        if m:
     339            link = m.group(1)
     340            m = re.search('.*<([^>]*)>', link)
     341            if m:
     342                link = m.group(1)
     343            s = re.sub(':%s:`([^`]*)`' % key,
     344                       extlinks[key][0].replace('%s', link),
     345                       s)
     346    return s
     347
    299348def process_mathtt(s, embedded=False):
    300349    r"""nodetex
    301350    Replace \\mathtt{BLAH} with either \\verb|BLAH| (in the notebook) or
    … … def format(s, embedded=False): 
    519568    if 'nodetex' not in directives:
    520569        s = process_dollars(s)
    521570        s = process_mathtt(s, embedded=embedded)
     571        s = process_extlinks(s, embedded=embedded)
    522572        s = detex(s, embedded=embedded)
    523573    return embedding_info+s
    524574