--- rest25/library/doctest.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/doctest.rst	2009-04-07 00:06:53.000000000 +0900
@@ -1,25 +1,23 @@
-
 :mod:`doctest` --- Test interactive Python examples
 ===================================================
 
 .. module:: doctest
+   :synopsis: Test pieces of code within docstrings.
 .. moduleauthor:: Tim Peters <tim@python.org>
 .. sectionauthor:: Tim Peters <tim@python.org>
 .. sectionauthor:: Moshe Zadka <moshez@debian.org>
 .. sectionauthor:: Edward Loper <edloper@users.sourceforge.net>
 
 
-
-
 The :mod:`doctest` module searches for pieces of text that look like interactive
 Python sessions, and then executes those sessions to verify that they work
 exactly as shown.  There are several common ways to use doctest:
 
 * To check that a module's docstrings are up-to-date by verifying that all
   interactive examples still work as documented.
 
 * To perform regression testing by verifying that interactive examples from a
   test file or a test object work as expected.
 
 * To write tutorial documentation for a package, liberally illustrated with
   input-output examples.  Depending on whether the examples or the expository text
@@ -62,49 +60,42 @@
            ...
        ValueError: n must be exact integer
        >>> factorial(30.0)
        265252859812191058636308480000000L
 
        It must also not be ridiculously large:
        >>> factorial(1e100)
        Traceback (most recent call last):
            ...
        OverflowError: n too large
        """
 
-
-.. % allow LaTeX to break here.
-
-::
-
        import math
        if not n >= 0:
            raise ValueError("n must be >= 0")
        if math.floor(n) != n:
            raise ValueError("n must be exact integer")
        if n+1 == n:  # catch a value like 1e300
            raise OverflowError("n too large")
        result = 1
        factor = 2
        while factor <= n:
            result *= factor
            factor += 1
        return result
 
-   def _test():
-       import doctest
-       doctest.testmod()
 
    if __name__ == "__main__":
-       _test()
+       import doctest
+       doctest.testmod()
 
 If you run :file:`example.py` directly from the command line, :mod:`doctest`
 works its magic::
 
    $ python example.py
    $
 
 There's no output!  That's normal, and it means all the examples worked.  Pass
 :option:`-v` to the script, and :mod:`doctest` prints a detailed log of what
 it's trying, and prints a summary at the end::
 
    $ python example.py -v
@@ -124,80 +115,86 @@
        [1, 1, 2, 6, 24, 120]
    ok
 
 And so on, eventually ending with::
 
    Trying:
        factorial(1e100)
    Expecting:
        Traceback (most recent call last):
            ...
        OverflowError: n too large
    ok
-   1 items had no tests:
-       __main__._test
    2 items passed all tests:
       1 tests in __main__
       8 tests in __main__.factorial
-   9 tests in 3 items.
+   9 tests in 2 items.
    9 passed and 0 failed.
    Test passed.
    $
 
 That's all you need to know to start making productive use of :mod:`doctest`!
 Jump in.  The following sections provide full details.  Note that there are many
 examples of doctests in the standard Python test suite and libraries.
 Especially useful examples can be found in the standard test file
 :file:`Lib/test/test_doctest.py`.
 
 
 .. _doctest-simple-testmod:
 
 Simple Usage: Checking Examples in Docstrings
 ---------------------------------------------
 
 The simplest way to start using doctest (but not necessarily the way you'll
 continue to do it) is to end each module :mod:`M` with::
 
-   def _test():
+   if __name__ == "__main__":
        import doctest
        doctest.testmod()
 
-   if __name__ == "__main__":
-       _test()
-
 :mod:`doctest` then examines docstrings in module :mod:`M`.
 
 Running the module as a script causes the examples in the docstrings to get
 executed and verified::
 
    python M.py
 
 This won't display anything unless an example fails, in which case the failing
 example(s) and the cause(s) of the failure(s) are printed to stdout, and the
 final line of output is ``***Test Failed*** N failures.``, where *N* is the
 number of examples that failed.
 
 Run it with the :option:`-v` switch instead::
 
    python M.py -v
 
 and a detailed report of all examples tried is printed to standard output, along
 with assorted summaries at the end.
 
 You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or
 prohibit it by passing ``verbose=False``.  In either of those cases,
 ``sys.argv`` is not examined by :func:`testmod` (so passing :option:`-v` or not
 has no effect).
 
+Since Python 2.6, there is also a command line shortcut for running
+:func:`testmod`.  You can instruct the Python interpreter to run the doctest
+module directly from the standard library and pass the module name(s) on the
+command line::
+
+   python -m doctest -v example.py
+
+This will import :file:`example.py` as a standalone module and run
+:func:`testmod` on it.  Note that this may not work correctly if the file is
+part of a package and imports other submodules from that package.
+
 For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
 
 
 .. _doctest-simple-testfile:
 
 Simple Usage: Checking Examples in a Text File
 ----------------------------------------------
 
 Another simple application of doctest is testing interactive examples in a text
 file.  This can be done with the :func:`testfile` function::
 
    import doctest
@@ -239,24 +236,34 @@
 example fails.  If an example does fail, then the failing example(s) and the
 cause(s) of the failure(s) are printed to stdout, using the same format as
 :func:`testmod`.
 
 By default, :func:`testfile` looks for files in the calling module's directory.
 See section :ref:`doctest-basic-api` for a description of the optional arguments
 that can be used to tell it to look for files in other locations.
 
 Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
 :option:`-v` command-line switch or with the optional keyword argument
 *verbose*.
 
+Since Python 2.6, there is also a command line shortcut for running
+:func:`testfile`.  You can instruct the Python interpreter to run the doctest
+module directly from the standard library and pass the file name(s) on the
+command line::
+
+   python -m doctest -v example.txt
+
+Because the file name does not end with :file:`.py`, :mod:`doctest` infers that
+it must be run with :func:`testfile`, not :func:`testmod`.
+
 For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
 
 
 .. _doctest-how-it-works:
 
 How It Works
 ------------
 
 This section examines in detail how doctest works: which docstrings it looks at,
 how it finds interactive examples, what execution context it uses, how it
 handles exceptions, and how option flags can be used to control its behavior.
 This is the information that you need to know to write doctest examples; for
@@ -407,28 +414,28 @@
 
 The expected output for an exception must start with a traceback header, which
 may be either of the following two lines, indented the same as the first line of
 the example::
 
    Traceback (most recent call last):
    Traceback (innermost last):
 
 The traceback header is followed by an optional traceback stack, whose contents
 are ignored by doctest.  The traceback stack is typically omitted, or copied
 verbatim from an interactive session.
 
-The traceback stack is followed by the most interesting part:  the line(s)
+The traceback stack is followed by the most interesting part: the line(s)
 containing the exception type and detail.  This is usually the last line of a
-traceback, but can extend across multiple lines if the exception has a multi-
-line detail::
+traceback, but can extend across multiple lines if the exception has a
+multi-line detail::
 
    >>> raise ValueError('multi\n    line\ndetail')
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
    ValueError: multi
        line
    detail
 
 The last three lines (starting with :exc:`ValueError`) are compared against the
 exception's type and detail, and the rest are ignored.
 
 Best practice is to omit the traceback stack, unless it adds significant
@@ -715,30 +722,25 @@
 
 
 .. _doctest-warnings:
 
 Warnings
 ^^^^^^^^
 
 :mod:`doctest` is serious about requiring exact matches in expected output.  If
 even a single character doesn't match, the test fails.  This will probably
 surprise you a few times, as you learn exactly what Python does and doesn't
 guarantee about output.  For example, when printing a dict, Python doesn't
 guarantee that the key-value pairs will be printed in any particular order, so a
-test like
-
-.. % Hey! What happened to Monty Python examples?
-.. % Tim: ask Guido -- it's his example!
-
-::
+test like ::
 
    >>> foo()
    {"Hermione": "hippogryph", "Harry": "broomstick"}
 
 is vulnerable!  One workaround is to do ::
 
    >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
    True
 
 instead.  Another is to do ::
 
    >>> d = foo().items()
@@ -795,32 +797,32 @@
 
 .. function:: testfile(filename[, module_relative][, name][, package][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, parser][, encoding])
 
    All arguments except *filename* are optional, and should be specified in keyword
    form.
 
    Test examples in the file named *filename*.  Return ``(failure_count,
    test_count)``.
 
    Optional argument *module_relative* specifies how the filename should be
    interpreted:
 
-* If *module_relative* is ``True`` (the default), then *filename* specifies an
+   * If *module_relative* is ``True`` (the default), then *filename* specifies an
      OS-independent module-relative path.  By default, this path is relative to the
      calling module's directory; but if the *package* argument is specified, then it
      is relative to that package.  To ensure OS-independence, *filename* should use
      ``/`` characters to separate path segments, and may not be an absolute path
      (i.e., it may not begin with ``/``).
 
-* If *module_relative* is ``False``, then *filename* specifies an OS-specific
+   * If *module_relative* is ``False``, then *filename* specifies an OS-specific
      path.  The path may be absolute or relative; relative paths are resolved with
      respect to the current working directory.
 
    Optional argument *name* gives the name of the test; by default, or if ``None``,
    ``os.path.basename(filename)`` is used.
 
    Optional argument *package* is a Python package or the name of a Python package
    whose directory should be used as the base directory for a module-relative
    filename.  If no package is specified, then the calling module's directory is
    used as the base directory for module-relative filenames.  It is an error to
    specify *package* if *module_relative* is ``False``.
 
@@ -954,90 +956,92 @@
    import my_module_with_doctests, and_another
 
    suite = unittest.TestSuite()
    for mod in my_module_with_doctests, and_another:
        suite.addTest(doctest.DocTestSuite(mod))
    runner = unittest.TextTestRunner()
    runner.run(suite)
 
 There are two main functions for creating :class:`unittest.TestSuite` instances
 from text files and modules with doctests:
 
 
-.. function:: DocFileSuite([module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])
+.. function:: DocFileSuite(*paths, [module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])
 
    Convert doctest tests from one or more text files to a
    :class:`unittest.TestSuite`.
 
    The returned :class:`unittest.TestSuite` is to be run by the unittest framework
    and runs the interactive examples in each file.  If an example in any file
    fails, then the synthesized unit test fails, and a :exc:`failureException`
    exception is raised showing the name of the file containing the test and a
    (sometimes approximate) line number.
 
    Pass one or more paths (as strings) to text files to be examined.
 
    Options may be provided as keyword arguments:
 
    Optional argument *module_relative* specifies how the filenames in *paths*
    should be interpreted:
 
-* If *module_relative* is ``True`` (the default), then each filename specifies
-     an OS-independent module-relative path.  By default, this path is relative to
-     the calling module's directory; but if the *package* argument is specified, then
-     it is relative to that package.  To ensure OS-independence, each filename should
-     use ``/`` characters to separate path segments, and may not be an absolute path
-     (i.e., it may not begin with ``/``).
+   * If *module_relative* is ``True`` (the default), then each filename in
+     *paths* specifies an OS-independent module-relative path.  By default, this
+     path is relative to the calling module's directory; but if the *package*
+     argument is specified, then it is relative to that package.  To ensure
+     OS-independence, each filename should use ``/`` characters to separate path
+     segments, and may not be an absolute path (i.e., it may not begin with
+     ``/``).
+
+   * If *module_relative* is ``False``, then each filename in *paths* specifies
+     an OS-specific path.  The path may be absolute or relative; relative paths
+     are resolved with respect to the current working directory.
+
+   Optional argument *package* is a Python package or the name of a Python
+   package whose directory should be used as the base directory for
+   module-relative filenames in *paths*.  If no package is specified, then the
+   calling module's directory is used as the base directory for module-relative
+   filenames.  It is an error to specify *package* if *module_relative* is
+   ``False``.
 
-* If *module_relative* is ``False``, then each filename specifies an OS-specific
-     path.  The path may be absolute or relative; relative paths are resolved with
-     respect to the current working directory.
-
-   Optional argument *package* is a Python package or the name of a Python package
-   whose directory should be used as the base directory for module-relative
-   filenames.  If no package is specified, then the calling module's directory is
-   used as the base directory for module-relative filenames.  It is an error to
-   specify *package* if *module_relative* is ``False``.
-
-   Optional argument *setUp* specifies a set-up function for the test suite.  This
-   is called before running the tests in each file.  The *setUp* function will be
-   passed a :class:`DocTest` object.  The setUp function can access the test
-   globals as the *globs* attribute of the test passed.
-
-   Optional argument *tearDown* specifies a tear-down function for the test suite.
-   This is called after running the tests in each file.  The *tearDown* function
+   Optional argument *setUp* specifies a set-up function for the test suite.
+   This is called before running the tests in each file.  The *setUp* function
    will be passed a :class:`DocTest` object.  The setUp function can access the
    test globals as the *globs* attribute of the test passed.
 
+   Optional argument *tearDown* specifies a tear-down function for the test
+   suite.  This is called after running the tests in each file.  The *tearDown*
+   function will be passed a :class:`DocTest` object.  The setUp function can
+   access the test globals as the *globs* attribute of the test passed.
+
    Optional argument *globs* is a dictionary containing the initial global
    variables for the tests.  A new copy of this dictionary is created for each
    test.  By default, *globs* is a new empty dictionary.
 
    Optional argument *optionflags* specifies the default doctest options for the
    tests, created by or-ing together individual option flags.  See section
-   :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below for
-   a better way to set reporting options.
+   :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
+   for a better way to set reporting options.
 
-   Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) that
-   should be used to extract tests from the files.  It defaults to a normal parser
-   (i.e., ``DocTestParser()``).
+   Optional argument *parser* specifies a :class:`DocTestParser` (or subclass)
+   that should be used to extract tests from the files.  It defaults to a normal
+   parser (i.e., ``DocTestParser()``).
 
    Optional argument *encoding* specifies an encoding that should be used to
    convert the file to unicode.
 
    .. versionadded:: 2.4
 
    .. versionchanged:: 2.5
-      The global ``__file__`` was added to the globals provided to doctests loaded
-      from a text file using :func:`DocFileSuite`.
+      The global ``__file__`` was added to the globals provided to doctests
+      loaded from a text file using :func:`DocFileSuite`.
 
    .. versionchanged:: 2.5
       The parameter *encoding* was added.
 
 
 .. function:: DocTestSuite([module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker])
 
    Convert doctest tests for a module to a :class:`unittest.TestSuite`.
 
    The returned :class:`unittest.TestSuite` is to be run by the unittest framework
    and runs each doctest in the module.  If any of the doctests fail, then the
    synthesized unit test fails, and a :exc:`failureException` exception is raised
@@ -1046,26 +1050,26 @@
 
    Optional argument *module* provides the module to be tested.  It can be a module
    object or a (possibly dotted) module name.  If not specified, the module calling
    this function is used.
 
    Optional argument *globs* is a dictionary containing the initial global
    variables for the tests.  A new copy of this dictionary is created for each
    test.  By default, *globs* is a new empty dictionary.
 
    Optional argument *extraglobs* specifies an extra set of global variables, which
    is merged into *globs*.  By default, no extra globals are used.
 
-   Optional argument *test_finder* is the :class:`DocTestFinder` object (or a drop-
-   in replacement) that is used to extract doctests from the module.
+   Optional argument *test_finder* is the :class:`DocTestFinder` object (or a
+   drop-in replacement) that is used to extract doctests from the module.
 
    Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for
    function :func:`DocFileSuite` above.
 
    .. versionadded:: 2.3
 
    .. versionchanged:: 2.4
       The parameters *globs*, *extraglobs*, *test_finder*, *setUp*, *tearDown*, and
       *optionflags* were added; this function now uses the same search technique as
       :func:`testmod`.
 
 Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out
@@ -1119,25 +1123,26 @@
 
 Advanced API
 ------------
 
 The basic API is a simple wrapper that's intended to make doctest easy to use.
 It is fairly flexible, and should meet most users' needs; however, if you
 require more fine-grained control over testing, or wish to extend doctest's
 capabilities, then you should use the advanced API.
 
 The advanced API revolves around two container classes, which are used to store
 the interactive examples extracted from doctest cases:
 
-* :class:`Example`: A single python statement, paired with its expected output.
+* :class:`Example`: A single python :term:`statement`, paired with its expected
+  output.
 
 * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
   from a single docstring or text file.
 
 Additional processing classes are defined to find, parse, and run, and check
 doctest examples:
 
 * :class:`DocTestFinder`: Finds all docstrings in a given module, and uses a
   :class:`DocTestParser` to create a :class:`DocTest` from every docstring that
   contains interactive examples.
 
 * :class:`DocTestParser`: Creates a :class:`DocTest` object from a string (such
@@ -1167,129 +1172,129 @@
 DocTest Objects
 ^^^^^^^^^^^^^^^
 
 
 .. class:: DocTest(examples, globs, name, filename, lineno, docstring)
 
    A collection of doctest examples that should be run in a single namespace.  The
    constructor arguments are used to initialize the member variables of the same
    names.
 
    .. versionadded:: 2.4
 
-:class:`DocTest` defines the following member variables.  They are initialized
-by the constructor, and should not be modified directly.
+   :class:`DocTest` defines the following member variables.  They are initialized by
+   the constructor, and should not be modified directly.
 
 
-.. attribute:: DocTest.examples
+   .. attribute:: examples
 
-   A list of :class:`Example` objects encoding the individual interactive Python
-   examples that should be run by this test.
+      A list of :class:`Example` objects encoding the individual interactive Python
+      examples that should be run by this test.
 
 
-.. attribute:: DocTest.globs
+   .. attribute:: globs
 
-   The namespace (aka globals) that the examples should be run in. This is a
-   dictionary mapping names to values.  Any changes to the namespace made by the
-   examples (such as binding new variables) will be reflected in :attr:`globs`
-   after the test is run.
+      The namespace (aka globals) that the examples should be run in. This is a
+      dictionary mapping names to values.  Any changes to the namespace made by the
+      examples (such as binding new variables) will be reflected in :attr:`globs`
+      after the test is run.
 
 
-.. attribute:: DocTest.name
+   .. attribute:: name
 
-   A string name identifying the :class:`DocTest`.  Typically, this is the name of
-   the object or file that the test was extracted from.
+      A string name identifying the :class:`DocTest`.  Typically, this is the name
+      of the object or file that the test was extracted from.
 
 
-.. attribute:: DocTest.filename
+   .. attribute:: filename
 
-   The name of the file that this :class:`DocTest` was extracted from; or ``None``
-   if the filename is unknown, or if the :class:`DocTest` was not extracted from a
-   file.
+      The name of the file that this :class:`DocTest` was extracted from; or
+      ``None`` if the filename is unknown, or if the :class:`DocTest` was not
+      extracted from a file.
 
 
-.. attribute:: DocTest.lineno
+   .. attribute:: lineno
 
-   The line number within :attr:`filename` where this :class:`DocTest` begins, or
-   ``None`` if the line number is unavailable.  This line number is zero-based with
-   respect to the beginning of the file.
+      The line number within :attr:`filename` where this :class:`DocTest` begins, or
+      ``None`` if the line number is unavailable.  This line number is zero-based
+      with respect to the beginning of the file.
 
 
-.. attribute:: DocTest.docstring
+   .. attribute:: docstring
 
-   The string that the test was extracted from, or 'None' if the string is
-   unavailable, or if the test was not extracted from a string.
+      The string that the test was extracted from, or 'None' if the string is
+      unavailable, or if the test was not extracted from a string.
 
 
 .. _doctest-example:
 
 Example Objects
 ^^^^^^^^^^^^^^^
 
 
 .. class:: Example(source, want[, exc_msg][, lineno][, indent][, options])
 
    A single interactive example, consisting of a Python statement and its expected
    output.  The constructor arguments are used to initialize the member variables
    of the same names.
 
    .. versionadded:: 2.4
 
-:class:`Example` defines the following member variables.  They are initialized
-by the constructor, and should not be modified directly.
+   :class:`Example` defines the following member variables.  They are initialized by
+   the constructor, and should not be modified directly.
 
 
-.. attribute:: Example.source
+   .. attribute:: source
 
-   A string containing the example's source code.  This source code consists of a
-   single Python statement, and always ends with a newline; the constructor adds a
-   newline when necessary.
+      A string containing the example's source code.  This source code consists of a
+      single Python statement, and always ends with a newline; the constructor adds
+      a newline when necessary.
 
 
-.. attribute:: Example.want
+   .. attribute:: want
 
-   The expected output from running the example's source code (either from stdout,
-   or a traceback in case of exception).  :attr:`want` ends with a newline unless
-   no output is expected, in which case it's an empty string.  The constructor adds
-   a newline when necessary.
+      The expected output from running the example's source code (either from
+      stdout, or a traceback in case of exception).  :attr:`want` ends with a
+      newline unless no output is expected, in which case it's an empty string.  The
+      constructor adds a newline when necessary.
 
 
-.. attribute:: Example.exc_msg
+   .. attribute:: exc_msg
 
-   The exception message generated by the example, if the example is expected to
-   generate an exception; or ``None`` if it is not expected to generate an
-   exception.  This exception message is compared against the return value of
-   :func:`traceback.format_exception_only`.  :attr:`exc_msg` ends with a newline
-   unless it's ``None``.  The constructor adds a newline if needed.
+      The exception message generated by the example, if the example is expected to
+      generate an exception; or ``None`` if it is not expected to generate an
+      exception.  This exception message is compared against the return value of
+      :func:`traceback.format_exception_only`.  :attr:`exc_msg` ends with a newline
+      unless it's ``None``.  The constructor adds a newline if needed.
 
 
-.. attribute:: Example.lineno
+   .. attribute:: lineno
 
-   The line number within the string containing this example where the example
-   begins.  This line number is zero-based with respect to the beginning of the
-   containing string.
+      The line number within the string containing this example where the example
+      begins.  This line number is zero-based with respect to the beginning of the
+      containing string.
 
 
-.. attribute:: Example.indent
+   .. attribute:: indent
 
-   The example's indentation in the containing string, i.e., the number of space
-   characters that precede the example's first prompt.
+      The example's indentation in the containing string, i.e., the number of space
+      characters that precede the example's first prompt.
 
 
-.. attribute:: Example.options
+   .. attribute:: options
 
-   A dictionary mapping from option flags to ``True`` or ``False``, which is used
-   to override default options for this example.  Any option flags not contained in
-   this dictionary are left at their default value (as specified by the
-   :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
+      A dictionary mapping from option flags to ``True`` or ``False``, which is used
+      to override default options for this example.  Any option flags not contained
+      in this dictionary are left at their default value (as specified by the
+      :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
 
 
 .. _doctest-doctestfinder:
 
 DocTestFinder objects
 ^^^^^^^^^^^^^^^^^^^^^
 
 
 .. class:: DocTestFinder([verbose][, parser][, recurse][, exclude_empty])
 
    A processing class used to extract the :class:`DocTest`\ s that are relevant to
    a given object, from its docstring and the docstrings of its contained objects.
@@ -1302,103 +1307,103 @@
 
    The optional argument *parser* specifies the :class:`DocTestParser` object (or a
    drop-in replacement) that is used to extract doctests from docstrings.
 
    If the optional argument *recurse* is false, then :meth:`DocTestFinder.find`
    will only examine the given object, and not any contained objects.
 
    If the optional argument *exclude_empty* is false, then
    :meth:`DocTestFinder.find` will include tests for objects with empty docstrings.
 
    .. versionadded:: 2.4
 
-:class:`DocTestFinder` defines the following method:
+   :class:`DocTestFinder` defines the following method:
 
 
-.. method:: DocTestFinder.find(obj[, name][, module][, globs][, extraglobs])
+   .. method:: find(obj[, name][, module][, globs][, extraglobs])
 
-   Return a list of the :class:`DocTest`\ s that are defined by *obj*'s docstring,
-   or by any of its contained objects' docstrings.
+      Return a list of the :class:`DocTest`\ s that are defined by *obj*'s
+      docstring, or by any of its contained objects' docstrings.
 
-   The optional argument *name* specifies the object's name; this name will be used
-   to construct names for the returned :class:`DocTest`\ s.  If *name* is not
-   specified, then ``obj.__name__`` is used.
+      The optional argument *name* specifies the object's name; this name will be
+      used to construct names for the returned :class:`DocTest`\ s.  If *name* is
+      not specified, then ``obj.__name__`` is used.
 
-   The optional parameter *module* is the module that contains the given object.
-   If the module is not specified or is None, then the test finder will attempt to
-   automatically determine the correct module.  The object's module is used:
+      The optional parameter *module* is the module that contains the given object.
+      If the module is not specified or is None, then the test finder will attempt
+      to automatically determine the correct module.  The object's module is used:
 
-* As a default namespace, if *globs* is not specified.
+      * As a default namespace, if *globs* is not specified.
 
-* To prevent the DocTestFinder from extracting DocTests from objects that are
-     imported from other modules.  (Contained objects with modules other than
-     *module* are ignored.)
+      * To prevent the DocTestFinder from extracting DocTests from objects that are
+        imported from other modules.  (Contained objects with modules other than
+        *module* are ignored.)
 
-* To find the name of the file containing the object.
+      * To find the name of the file containing the object.
 
-* To help find the line number of the object within its file.
+      * To help find the line number of the object within its file.
 
-   If *module* is ``False``, no attempt to find the module will be made.  This is
-   obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
-   is ``None`` but cannot be found automatically, then all objects are considered
-   to belong to the (non-existent) module, so all contained objects will
-   (recursively) be searched for doctests.
+      If *module* is ``False``, no attempt to find the module will be made.  This is
+      obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
+      is ``None`` but cannot be found automatically, then all objects are considered
+      to belong to the (non-existent) module, so all contained objects will
+      (recursively) be searched for doctests.
 
-   The globals for each :class:`DocTest` is formed by combining *globs* and
-   *extraglobs* (bindings in *extraglobs* override bindings in *globs*).  A new
-   shallow copy of the globals dictionary is created for each :class:`DocTest`.  If
-   *globs* is not specified, then it defaults to the module's *__dict__*, if
-   specified, or ``{}`` otherwise.  If *extraglobs* is not specified, then it
-   defaults to ``{}``.
+      The globals for each :class:`DocTest` is formed by combining *globs* and
+      *extraglobs* (bindings in *extraglobs* override bindings in *globs*).  A new
+      shallow copy of the globals dictionary is created for each :class:`DocTest`.
+      If *globs* is not specified, then it defaults to the module's *__dict__*, if
+      specified, or ``{}`` otherwise.  If *extraglobs* is not specified, then it
+      defaults to ``{}``.
 
 
 .. _doctest-doctestparser:
 
 DocTestParser objects
 ^^^^^^^^^^^^^^^^^^^^^
 
 
 .. class:: DocTestParser()
 
    A processing class used to extract interactive examples from a string, and use
    them to create a :class:`DocTest` object.
 
    .. versionadded:: 2.4
 
-:class:`DocTestParser` defines the following methods:
+   :class:`DocTestParser` defines the following methods:
 
 
-.. method:: DocTestParser.get_doctest(string, globs, name, filename, lineno)
+   .. method:: get_doctest(string, globs, name, filename, lineno)
 
-   Extract all doctest examples from the given string, and collect them into a
-   :class:`DocTest` object.
+      Extract all doctest examples from the given string, and collect them into a
+      :class:`DocTest` object.
 
-   *globs*, *name*, *filename*, and *lineno* are attributes for the new
-   :class:`DocTest` object.  See the documentation for :class:`DocTest` for more
-   information.
+      *globs*, *name*, *filename*, and *lineno* are attributes for the new
+      :class:`DocTest` object.  See the documentation for :class:`DocTest` for more
+      information.
 
 
-.. method:: DocTestParser.get_examples(string[, name])
+   .. method:: get_examples(string[, name])
 
-   Extract all doctest examples from the given string, and return them as a list of
-   :class:`Example` objects.  Line numbers are 0-based.  The optional argument
-   *name* is a name identifying this string, and is only used for error messages.
+      Extract all doctest examples from the given string, and return them as a list
+      of :class:`Example` objects.  Line numbers are 0-based.  The optional argument
+      *name* is a name identifying this string, and is only used for error messages.
 
 
-.. method:: DocTestParser.parse(string[, name])
+   .. method:: parse(string[, name])
 
-   Divide the given string into examples and intervening text, and return them as a
-   list of alternating :class:`Example`\ s and strings. Line numbers for the
-   :class:`Example`\ s are 0-based.  The optional argument *name* is a name
-   identifying this string, and is only used for error messages.
+      Divide the given string into examples and intervening text, and return them as
+      a list of alternating :class:`Example`\ s and strings. Line numbers for the
+      :class:`Example`\ s are 0-based.  The optional argument *name* is a name
+      identifying this string, and is only used for error messages.
 
 
 .. _doctest-doctestrunner:
 
 DocTestRunner objects
 ^^^^^^^^^^^^^^^^^^^^^
 
 
 .. class:: DocTestRunner([checker][, verbose][, optionflags])
 
    A processing class used to execute and verify the interactive examples in a
    :class:`DocTest`.
@@ -1424,133 +1429,137 @@
    The optional keyword argument *verbose* controls the :class:`DocTestRunner`'s
    verbosity.  If *verbose* is ``True``, then information is printed about each
    example, as it is run.  If *verbose* is ``False``, then only failures are
    printed.  If *verbose* is unspecified, or ``None``, then verbose output is used
    iff the command-line switch :option:`-v` is used.
 
    The optional keyword argument *optionflags* can be used to control how the test
    runner compares expected output to actual output, and how it displays failures.
    For more information, see section :ref:`doctest-options`.
 
    .. versionadded:: 2.4
 
-:class:`DocTestParser` defines the following methods:
+   :class:`DocTestParser` defines the following methods:
+
 
+   .. method:: report_start(out, test, example)
 
-.. method:: DocTestRunner.report_start(out, test, example)
+      Report that the test runner is about to process the given example. This method
+      is provided to allow subclasses of :class:`DocTestRunner` to customize their
+      output; it should not be called directly.
 
-   Report that the test runner is about to process the given example. This method
-   is provided to allow subclasses of :class:`DocTestRunner` to customize their
-   output; it should not be called directly.
+      *example* is the example about to be processed.  *test* is the test
+      *containing example*.  *out* is the output function that was passed to
+      :meth:`DocTestRunner.run`.
 
-   *example* is the example about to be processed.  *test* is the test containing
-   *example*.  *out* is the output function that was passed to
-   :meth:`DocTestRunner.run`.
 
+   .. method:: report_success(out, test, example, got)
 
-.. method:: DocTestRunner.report_success(out, test, example, got)
+      Report that the given example ran successfully.  This method is provided to
+      allow subclasses of :class:`DocTestRunner` to customize their output; it
+      should not be called directly.
 
-   Report that the given example ran successfully.  This method is provided to
-   allow subclasses of :class:`DocTestRunner` to customize their output; it should
-   not be called directly.
+      *example* is the example about to be processed.  *got* is the actual output
+      from the example.  *test* is the test containing *example*.  *out* is the
+      output function that was passed to :meth:`DocTestRunner.run`.
 
-   *example* is the example about to be processed.  *got* is the actual output from
-   the example.  *test* is the test containing *example*.  *out* is the output
-   function that was passed to :meth:`DocTestRunner.run`.
 
+   .. method:: report_failure(out, test, example, got)
 
-.. method:: DocTestRunner.report_failure(out, test, example, got)
+      Report that the given example failed.  This method is provided to allow
+      subclasses of :class:`DocTestRunner` to customize their output; it should not
+      be called directly.
 
-   Report that the given example failed.  This method is provided to allow
-   subclasses of :class:`DocTestRunner` to customize their output; it should not be
-   called directly.
+      *example* is the example about to be processed.  *got* is the actual output
+      from the example.  *test* is the test containing *example*.  *out* is the
+      output function that was passed to :meth:`DocTestRunner.run`.
 
-   *example* is the example about to be processed.  *got* is the actual output from
-   the example.  *test* is the test containing *example*.  *out* is the output
-   function that was passed to :meth:`DocTestRunner.run`.
 
+   .. method:: report_unexpected_exception(out, test, example, exc_info)
 
-.. method:: DocTestRunner.report_unexpected_exception(out, test, example, exc_info)
+      Report that the given example raised an unexpected exception. This method is
+      provided to allow subclasses of :class:`DocTestRunner` to customize their
+      output; it should not be called directly.
 
-   Report that the given example raised an unexpected exception. This method is
-   provided to allow subclasses of :class:`DocTestRunner` to customize their
-   output; it should not be called directly.
+      *example* is the example about to be processed. *exc_info* is a tuple
+      containing information about the unexpected exception (as returned by
+      :func:`sys.exc_info`). *test* is the test containing *example*.  *out* is the
+      output function that was passed to :meth:`DocTestRunner.run`.
 
-   *example* is the example about to be processed. *exc_info* is a tuple containing
-   information about the unexpected exception (as returned by
-   :func:`sys.exc_info`). *test* is the test containing *example*.  *out* is the
-   output function that was passed to :meth:`DocTestRunner.run`.
 
+   .. method:: run(test[, compileflags][, out][, clear_globs])
 
-.. method:: DocTestRunner.run(test[, compileflags][, out][, clear_globs])
+      Run the examples in *test* (a :class:`DocTest` object), and display the
+      results using the writer function *out*.
 
-   Run the examples in *test* (a :class:`DocTest` object), and display the results
-   using the writer function *out*.
+      The examples are run in the namespace ``test.globs``.  If *clear_globs* is
+      true (the default), then this namespace will be cleared after the test runs,
+      to help with garbage collection. If you would like to examine the namespace
+      after the test completes, then use *clear_globs=False*.
 
-   The examples are run in the namespace ``test.globs``.  If *clear_globs* is true
-   (the default), then this namespace will be cleared after the test runs, to help
-   with garbage collection. If you would like to examine the namespace after the
-   test completes, then use *clear_globs=False*.
+      *compileflags* gives the set of flags that should be used by the Python
+      compiler when running the examples.  If not specified, then it will default to
+      the set of future-import flags that apply to *globs*.
 
-   *compileflags* gives the set of flags that should be used by the Python compiler
-   when running the examples.  If not specified, then it will default to the set of
-   future-import flags that apply to *globs*.
+      The output of each example is checked using the :class:`DocTestRunner`'s
+      output checker, and the results are formatted by the
+      :meth:`DocTestRunner.report_\*` methods.
 
-   The output of each example is checked using the :class:`DocTestRunner`'s output
-   checker, and the results are formatted by the :meth:`DocTestRunner.report_\*`
-   methods.
 
+   .. method:: summarize([verbose])
 
-.. method:: DocTestRunner.summarize([verbose])
+      Print a summary of all the test cases that have been run by this DocTestRunner,
+      and return a :term:`named tuple` ``TestResults(failed, attempted)``.
 
-   Print a summary of all the test cases that have been run by this DocTestRunner,
-   and return a tuple ``(failure_count, test_count)``.
+      The optional *verbose* argument controls how detailed the summary is.  If the
+      verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is
+      used.
 
-   The optional *verbose* argument controls how detailed the summary is.  If the
-   verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is used.
+      .. versionchanged:: 2.6
+         Use a named tuple.
 
 
 .. _doctest-outputchecker:
 
 OutputChecker objects
 ^^^^^^^^^^^^^^^^^^^^^
 
 
 .. class:: OutputChecker()
 
    A class used to check the whether the actual output from a doctest example
    matches the expected output.  :class:`OutputChecker` defines two methods:
    :meth:`check_output`, which compares a given pair of outputs, and returns true
    if they match; and :meth:`output_difference`, which returns a string describing
    the differences between two outputs.
 
    .. versionadded:: 2.4
 
-:class:`OutputChecker` defines the following methods:
+   :class:`OutputChecker` defines the following methods:
 
 
-.. method:: OutputChecker.check_output(want, got, optionflags)
+   .. method:: check_output(want, got, optionflags)
 
-   Return ``True`` iff the actual output from an example (*got*) matches the
-   expected output (*want*).  These strings are always considered to match if they
-   are identical; but depending on what option flags the test runner is using,
-   several non-exact match types are also possible.  See section
-   :ref:`doctest-options` for more information about option flags.
+      Return ``True`` iff the actual output from an example (*got*) matches the
+      expected output (*want*).  These strings are always considered to match if
+      they are identical; but depending on what option flags the test runner is
+      using, several non-exact match types are also possible.  See section
+      :ref:`doctest-options` for more information about option flags.
 
 
-.. method:: OutputChecker.output_difference(example, got, optionflags)
+   .. method:: output_difference(example, got, optionflags)
 
-   Return a string describing the differences between the expected output for a
-   given example (*example*) and the actual output (*got*).  *optionflags* is the
-   set of option flags used to compare *want* and *got*.
+      Return a string describing the differences between the expected output for a
+      given example (*example*) and the actual output (*got*).  *optionflags* is the
+      set of option flags used to compare *want* and *got*.
 
 
 .. _doctest-debugging:
 
 Debugging
 ---------
 
 Doctest provides several mechanisms for debugging doctest examples:
 
 * Several functions convert doctests to executable Python programs, which can be
   run under the Python debugger, :mod:`pdb`.
 
@@ -1601,25 +1610,25 @@
      [EOF]
      (Pdb) print x
      3
      (Pdb) step
      --Return--
      > <doctest a[2]>(1)?()->None
      -> f(3)
      (Pdb) cont
      (0, 3)
      >>>
 
   .. versionchanged:: 2.4
-     The ability to use ``pdb.set_trace()`` usefully inside doctests was added.
+     The ability to use :func:`pdb.set_trace` usefully inside doctests was added.
 
 Functions that convert doctests to Python code, and possibly run the synthesized
 code under the debugger:
 
 
 .. function:: script_from_examples(s)
 
    Convert text with examples to a script.
 
    Argument *s* is a string containing doctest examples.  The string is converted
    to a Python script, where doctest examples in *s* are converted to regular code,
    and everything else is converted to Python comments.  The generated script is
@@ -1678,28 +1687,28 @@
 
    The *module* and *name* arguments are the same as for function
    :func:`testsource` above.  The synthesized Python script for the named object's
    docstring is written to a temporary file, and then that file is run under the
    control of the Python debugger, :mod:`pdb`.
 
    A shallow copy of ``module.__dict__`` is used for both local and global
    execution context.
 
    Optional argument *pm* controls whether post-mortem debugging is used.  If *pm*
    has a true value, the script file is run directly, and the debugger gets
    involved only if the script terminates via raising an unhandled exception.  If
-   it does, then post-mortem debugging is invoked, via ``pdb.post_mortem()``,
+   it does, then post-mortem debugging is invoked, via :func:`pdb.post_mortem`,
    passing the traceback object from the unhandled exception.  If *pm* is not
    specified, or is false, the script is run under the debugger from the start, via
-   passing an appropriate :func:`execfile` call to ``pdb.run()``.
+   passing an appropriate :func:`execfile` call to :func:`pdb.run`.
 
    .. versionadded:: 2.3
 
    .. versionchanged:: 2.4
       The *pm* argument was added.
 
 
 .. function:: debug_src(src[, pm][, globs])
 
    Debug the doctests in a string.
 
    This is like function :func:`debug` above, except that a string containing
