Document need to call doctest_reload() with older Python versions

IPython/utils/doctestreload.py

@@ -1,80 +1,80 b''
 # encoding: utf-8
 """
 A utility for handling the reloading of doctest.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import sys
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 def dhook_wrap(func,*a,**k):
     """Wrap a function call in a sys.displayhook controller.
 
     Returns a wrapper around func which calls func, with all its arguments and
     keywords unmodified, using the default sys.displayhook.  Since IPython
     modifies sys.displayhook, it breaks the behavior of certain systems that
     rely on the default behavior, notably doctest.
     """
 
     def f(*a,**k):
 
         dhook_s = sys.displayhook
         sys.displayhook = sys.__displayhook__
         try:
             out = func(*a,**k)
         finally:
             sys.displayhook = dhook_s
 
         return out
 
     f.__doc__ = func.__doc__
     return f
 
 
 def doctest_reload():
     """Properly reload doctest to reuse it interactively.
 
     This routine:
 
       - imports doctest but does NOT reload it (see below).
 
       - resets its global 'master' attribute to None, so that multiple uses of
-      the module interactively don't produce cumulative reports.
+        the module interactively don't produce cumulative reports.
 
       - Monkeypatches its core test runner method to protect it from IPython's
-      modified displayhook.  Doctest expects the default displayhook behavior
-      deep down, so our modification breaks it completely.  For this reason, a
-      hard monkeypatch seems like a reasonable solution rather than asking
-      users to manually use a different doctest runner when under IPython.
+        modified displayhook.  Doctest expects the default displayhook behavior
+        deep down, so our modification breaks it completely.  For this reason, a
+        hard monkeypatch seems like a reasonable solution rather than asking
+        users to manually use a different doctest runner when under IPython.
 
     Notes
     -----
     
     As of Python 2.6.6, 2.7.1 and 3.2, this monkeypatching is no longer required.
     doctest now takes care of resetting sys.displayhook itself. This function
     remains for now in case anyone has to work with older versions, but it's
     no longer called during IPython startup.
 
     This function *used to* reload doctest, but this has been disabled because
     reloading doctest unconditionally can cause massive breakage of other
     doctest-dependent modules already in memory, such as those for IPython's
     own testing system.  The name wasn't changed to avoid breaking people's
     code, but the reload call isn't actually made anymore."""
 
     import doctest
     doctest.master = None
     doctest.DocTestRunner.run = dhook_wrap(doctest.DocTestRunner.run)
 

docs/source/whatsnew/development.txt

@@ -1,42 +1,46 b''
 =====================
  Development version
 =====================
 
 This document describes in-flight development work.
 
 The CodeMirror js library has been updated fron 2.23 to 2.32 
 this might induce a few changes in behavior of keymaps in the notebook, 
 especially intenting/deindenting blocks that is now bound to Ctrl+] and ctr+[
 
 * Exception types can now be displayed with a custom traceback, by defining a
   ``_render_traceback_()`` method which returns a list of strings, each
   containing one line of the traceback.
 * A new command, ``ipython history trim`` can be used to delete everything but
   the last 1000 entries in the history database.
 
 In-process kernels
 ------------------
 
 The Python-language frontends, particularly the Qt console, may now communicate
 with in-process kernels, in addition to the traditional out-of-process
 kernels. An in-process kernel permits direct access to the kernel namespace,
 which is necessary in some applications. It should be understood, however, that
 the in-process kernel is not robust to bad user input and will block the main
 (GUI) thread while executing. Developers must decide on a case-by-case basis
 whether this tradeoff is appropriate for their application.
 
 Backwards incompatible changes
 ------------------------------
 
 * Calling :meth:`InteractiveShell.prefilter` will no longer perform static
   transformations - the processing of escaped commands such as ``%magic`` and
   ``!system``, and stripping input prompts from code blocks. This functionality
   was duplicated in :mod:`IPython.core.inputsplitter`, and the latter version
   was already what IPython relied on. A new API to transform input will be ready
   before release.
 * Functions from :mod:`IPython.lib.inputhook` to control integration with GUI
   event loops are no longer exposed in the top level of :mod:`IPython.lib`.
   Code calling these should make sure to import them from
   :mod:`IPython.lib.inputhook`.
 * For all kernel managers, the ``sub_channel`` attribute has been renamed to
   ``iopub_channel``.
+* Users on Python versions before 2.6.6, 2.7.1 or 3.2 will now need to call
+  :func:`IPython.utils.doctestreload.doctest_reload` to make doctests run 
+  correctly inside IPython. Python releases since those versions are unaffected.
+  For details, see :ghpull:`3068` and `Python issue 8048 <http://bugs.python.org/issue8048>`_.