Ticket #14376: trac_14376.patch

File trac_14376.patch, 12.5 KB (added by jhpalmieri, 9 years ago)
  • doc/en/reference/conf.py

    # HG changeset patch
    # User J. H. Palmieri <palmieri@math.washington.edu>
    # Date 1364527779 25200
    # Node ID 993c41f39eb58d36aba2e116d546b63bba29c257
    # Parent  bfa0ea8f50ee02a33e3de625a1d1f1177958b66c
    Add doctesting framework to the reference manual.
    
    diff --git a/doc/en/reference/conf.py b/doc/en/reference/conf.py
    a b  
    7676    'constants',
    7777    'cryptography',
    7878    'databases',
     79    'doctest',
    7980    'finance',
    8081    'finite_rings',
    8182    'function_fields',
  • new file doc/en/reference/doctest/conf.py

    diff --git a/doc/en/reference/doctest/conf.py b/doc/en/reference/doctest/conf.py
    new file mode 120000
    - +  
     1../conf_sub.py
     2 No newline at end of file
  • new file doc/en/reference/doctest/index.rst

    diff --git a/doc/en/reference/doctest/index.rst b/doc/en/reference/doctest/index.rst
    new file mode 100644
    - +  
     1Sage's Doctesting Framework
     2===========================
     3
     4.. toctree::
     5   :maxdepth: 2
     6
     7   sage/doctest/control
     8   sage/doctest/sources
     9   sage/doctest/forker
     10   sage/doctest/parsing
     11   sage/doctest/reporting
     12   sage/doctest/test
     13   sage/doctest/util
     14
     15.. include:: ../footer.txt
  • doc/en/reference/index.rst

    diff --git a/doc/en/reference/index.rst b/doc/en/reference/index.rst
    a b  
    117117* :doc:`Quantitative Finance <finance/index>`
    118118* :doc:`Coding Theory <coding/index>`
    119119
    120 Interfaces, Databases, Miscellany
    121 ---------------------------------
     120Doctesting, Interfaces, Databases, Miscellany
     121---------------------------------------------
    122122
     123* :doc:`Doctesting <doctest/index>`
    123124* :doc:`Interpreter Interfaces <interfaces/index>`
    124125* :doc:`C/C++ Library Interfaces <libs/index>`
    125126* :doc:`Databases <databases/index>`
  • sage/doctest/control.py

    diff --git a/sage/doctest/control.py b/sage/doctest/control.py
    a b  
    11"""
     2Classes involved in doctesting
     3
    24This module controls the various classes involved in doctesting.
    35
    46AUTHORS:
     
    134136    """
    135137    This class controls doctesting of files.
    136138
    137     After creating it with appropriate options, call the :meth:run() method to run the doctests.
     139    After creating it with appropriate options, call the :meth:`run` method to run the doctests.
    138140    """
    139141    def __init__(self, options, args):
    140142        """
     
    350352        self.log("Running doctests with ID %s."%self.run_id)
    351353
    352354    def add_files(self):
    353         """
     355        r"""
    354356        Checks for the flags '--all', '--new' and '--sagenb'.
    355357
    356358        For each one present, this function adds the appropriate directories and files to the todo list.
     
    499501            self.sources = filter(is_failure, self.sources)
    500502
    501503    def sort_sources(self):
    502         """
     504        r"""
    503505        This function sorts the sources so that slower doctests are run first.
    504506
    505507        EXAMPLES::
     
    539541        """
    540542        Actually runs the doctests.
    541543
    542         This function is called by :meth:run().
     544        This function is called by :meth:`run`.
    543545
    544546        EXAMPLES::
    545547
  • sage/doctest/forker.py

    diff --git a/sage/doctest/forker.py b/sage/doctest/forker.py
    a b  
    11"""
     2Processes for running doctests
     3
    24This module controls the processes started by Sage that actually run
    35the doctests.
    46
     
    9597
    9698
    9799def warning_function(file):
    98     """
     100    r"""
    99101    Creates a function that prints warnings to the given file.
    100102
    101103    INPUT:
     
    126128
    127129
    128130class SageSpoofInOut(SageObject):
    129     """
     131    r"""
    130132    We replace the standard :class:`doctest._SpoofOut` for three reasons:
    131133
    132134    - we need to divert the output of C programs that don't print
     
    141143    INPUT:
    142144
    143145    - ``outfile`` -- (default: ``os.tmpfile()``) a seekable open file
    144      object to which stdout and stderr should be redirected.
     146      object to which stdout and stderr should be redirected.
    145147
    146148    - ``infile`` -- (default: ``open(os.devnull)``) an open file object
    147149      from which stdin should be redirected.
     
    211213        self.stop_spoofing()
    212214
    213215    def start_spoofing(self):
    214         """
     216        r"""
    215217        Set stdin to read from ``self.infile`` and stdout to print to
    216218        ``self.outfile``.
    217219
     
    288290            self.spoofing = False
    289291
    290292    def getvalue(self):
    291         """
     293        r"""
    292294        Gets the value that has been printed to ``outfile`` since the
    293295        last time this function was called.
    294296
     
    785787            sage: globs.got
    786788            set(['Integer'])
    787789
    788         Now we can execute some more doctests to see the dependencies.
     790        Now we can execute some more doctests to see the dependencies. ::
    789791
    790792            sage: ex1 = doctests[0].examples[1]
    791793            sage: compiled = compile(ex1.source, '<doctest sage.doctest.forker[1]>', 'single', 32768, 1)
     
    864866            sage: ex = doctests[0].examples[0]
    865867            sage: print DTR._failure_header(doctests[0], ex)
    866868            **********************************************************************
    867             File ".../sage/doctest/forker.py", line 9, in sage.doctest.forker
     869            File ".../sage/doctest/forker.py", line 11, in sage.doctest.forker
    868870            Failed example:
    869871                doctest_var = 42; doctest_var^2
    870872            <BLANKLINE>
     
    874876            sage: import doctest
    875877            sage: print doctest.DocTestRunner._failure_header(DTR, doctests[0], ex)
    876878            **********************************************************************
    877             File ".../sage/doctest/forker.py", line 9, in sage.doctest.forker
     879            File ".../sage/doctest/forker.py", line 11, in sage.doctest.forker
    878880            Failed example:
    879881                doctest_var = Integer(42); doctest_var**Integer(2)
    880882            <BLANKLINE>
     
    912914            sage: doctests, extras = FDS.create_doctests(globals())
    913915            sage: ex = doctests[0].examples[0]
    914916            sage: DTR.report_start(sys.stdout.write, doctests[0], ex)
    915             Trying (line 9):    doctest_var = 42; doctest_var^2
     917            Trying (line 11):    doctest_var = 42; doctest_var^2
    916918            Expecting:
    917919                1764
    918920        """
     
    968970            out("ok [%.2f s]\n"%example.walltime)
    969971
    970972    def report_failure(self, out, test, example, got, globs):
    971         """
     973        r"""
    972974        Called when a doctest fails.
    973975
    974976        INPUT:
     
    10031005            sage: DTR.no_failure_yet = True
    10041006            sage: DTR.report_failure(sys.stdout.write, doctests[0], ex, 'BAD ANSWER\n', {})
    10051007            **********************************************************************
    1006             File ".../sage/doctest/forker.py", line 9, in sage.doctest.forker
     1008            File ".../sage/doctest/forker.py", line 11, in sage.doctest.forker
    10071009            Failed example:
    10081010                doctest_var = 42; doctest_var^2
    10091011            Expected:
     
    10161018            doctest.DocTestRunner.report_failure(self, out, test, example, got)
    10171019
    10181020    def report_overtime(self, out, test, example, got):
    1019         """
     1021        r"""
    10201022        Called when the ``warn_long`` option flag is set and a doctest
    10211023        runs longer than the specified time.
    10221024
     
    10511053            sage: ex.walltime = 1.23
    10521054            sage: DTR.report_overtime(sys.stdout.write, doctests[0], ex, 'BAD ANSWER\n')
    10531055            **********************************************************************
    1054             File ".../sage/doctest/forker.py", line 9, in sage.doctest.forker
     1056            File ".../sage/doctest/forker.py", line 11, in sage.doctest.forker
    10551057            Failed example:
    10561058                doctest_var = 42; doctest_var^2
    10571059            Test ran for 1.23 s
     
    10601062            "Test ran for %.2f s\n"%example.walltime)
    10611063
    10621064    def report_unexpected_exception(self, out, test, example, exc_info):
    1063         """
     1065        r"""
    10641066        Called when a doctest raises an exception that's not matched by the expected output.
    10651067
    10661068        If debugging has been turned on, starts an interactive debugger.
     
    12681270        """
    12691271        Run the doctests from the controller's specified sources in parallel.
    12701272
    1271         This creates :class:DocTestWorker subprocesses, while the master
     1273        This creates :class:`DocTestWorker` subprocesses, while the master
    12721274        process checks for timeouts and collects and displays the results.
    12731275
    12741276        EXAMPLES::
     
    15641566
    15651567    INPUT:
    15661568
    1567     - ``source`` -- a :class:DocTestSource instance
     1569    - ``source`` -- a :class:`DocTestSource` instance
    15681570
    15691571    - ``options`` -- an object representing doctest options.
    15701572
  • sage/doctest/parsing.py

    diff --git a/sage/doctest/parsing.py b/sage/doctest/parsing.py
    a b  
    11"""
     2Parsing docstrings
     3
    24This module contains functions and classes that parse docstrings.
    35
    46AUTHORS:
     
    320322        self.example = example
    321323
    322324    def __enter__(self):
    323         """
     325        r"""
    324326        EXAMPLES::
    325327
    326328            sage: from sage.doctest.sources import FileDocTestSource
  • sage/doctest/reporting.py

    diff --git a/sage/doctest/reporting.py b/sage/doctest/reporting.py
    a b  
    11"""
     2Reporting doctest results
     3
    24This module determines how doctest results are reported to the user.
    35
    46It also computes the exit status in the ``error_status`` attribute of
  • sage/doctest/sources.py

    diff --git a/sage/doctest/sources.py b/sage/doctest/sources.py
    a b  
    11"""
     2Classes for sources of doctests
     3
    24This module defines various classes for sources from which doctests
    35originate, such as files, functions or database entries.
    46
     
    306308            return doctests, extras
    307309
    308310class StringDocTestSource(DocTestSource):
    309     """
     311    r"""
    310312    This class creates doctests from a string.
    311313
    312314    INPUT:
     
    341343        []
    342344    """
    343345    def __init__(self, basename, source, options, printpath, lineno_shift=0):
    344         """
     346        r"""
    345347        Initialization
    346348
    347349        TESTS::
     
    383385            yield lineno + self.lineno_shift, line + '\n'
    384386
    385387    def create_doctests(self, namespace):
    386         """
     388        r"""
    387389        Creates doctests from this string.
    388390
    389391        INPUT:
     
    464466            self.__class__ = dynamic_class('RestFileSource',(FileDocTestSource,RestSource))
    465467
    466468    def __iter__(self):
    467         """
     469        r"""
    468470        Iterating over this source yields pairs ``(lineno, line)``.
    469471
    470472        EXAMPLES::
     
    822824        self.code_wrapping = False
    823825
    824826    def _update_quotetype(self, line):
    825         """
     827        r"""
    826828        Updates the track of what kind of quoted string we're in.
    827829
    828830        We need to track whether we're inside a triple quoted
     
    987989        return quotematch
    988990
    989991    def ending_docstring(self, line):
    990         """
     992        r"""
    991993        Determines whether the input line ends a docstring.
    992994
    993995        INPUT:
     
    10231025        return quotematch
    10241026
    10251027    def _neutralize_doctests(self, reindent):
    1026         """
     1028        r"""
    10271029        Returns a string containing the source of self, but with
    10281030        doctests modified so they aren't tested.
    10291031
     
    11751177        return bool(begin_verb.match(line))
    11761178
    11771179    def ending_docstring(self, line, check_skip=True):
    1178         """
     1180        r"""
    11791181        Determines whether the input line ends a docstring.
    11801182
    11811183        Docstring blocks in tex files are defined by verbatim
     
    13721374        return indent < self.last_indent
    13731375
    13741376    def parse_docstring(self, docstring, namespace, start):
    1375         """
     1377        r"""
    13761378        Return a list of doctest defined in this docstring.
    13771379
    13781380        Code blocks in a REST file can contain python functions with
  • sage/doctest/test.py

    diff --git a/sage/doctest/test.py b/sage/doctest/test.py
    a b  
    11"""
    2 Various tests for the doctesting framework.
     2Test the doctesting framework
    33
    44Many tests (with expected failures or crashes) are run in a
    55subprocess, those tests can be found in the ``tests/`` subdirectory.
     
    9393    ...
    9494    4
    9595
    96 Test handling of ``KeyboardInterrupt``s in doctests::
     96Test handling of ``KeyboardInterrupt`` in doctests::
    9797
    9898    sage: subprocess.call(["sage", "-t", "keyboardinterrupt.rst"], **kwds)  # long time
    9999    Running doctests...
  • sage/doctest/util.py

    diff --git a/sage/doctest/util.py b/sage/doctest/util.py
    a b  
    11"""
     2Utility functions
     3
    24This module contains various utility functions and classes used in doctesting.
    35
    46AUTHORS: