Document set_unittest_reportflags().

Doc/lib/libdoctest.tex

@@ -933,8 +933,8 @@ had a barely documented \class{Tester} class that supplied a rudimentary
 way to combine doctests from multiple modules. \class{Tester} was feeble,
 and in practice most serious Python testing frameworks build on the
 \module{unittest} module, which supplies many flexible ways to combine
-tests from multiple sources.  So, in Python 2.4, module{doctest}'s
-\class{Tester} class is deprecated, and \module{doctest} provides several
+tests from multiple sources.  So, in Python 2.4, \module{doctest}'s
+\class{Tester} class is deprecated, and \module{doctest} provides two
 functions that can be used to create \module{unittest} test suites from
 modules and text files containing doctests.  These test suites can then be
 run using \module{unittest} test runners:
@@ -951,6 +951,9 @@ runner = unittest.TextTestRunner()
 runner.run(suite)
 \end{verbatim}
 
+There are two main functions for creating \class{unittest.TestSuite}
+instances from text files and modules with doctests:
+
 \begin{funcdesc}{DocFileSuite}{*paths, **kw}
   Convert doctest tests from one or more text files to a
   \class{\refmodule{unittest}.TestSuite}.
@@ -1011,6 +1014,8 @@ runner.run(suite)
   Optional argument \var{optionflags} specifies the default
   doctest options for the tests, created by or-ing together
   individual option flags.  See section~\ref{doctest-options}.
+  See function \function{set_unittest_reportflags()} below for
+  a better way to set reporting options.
 
   \versionadded{2.4}
 \end{funcdesc}
@@ -1049,12 +1054,64 @@ runner.run(suite)
   are the same as for function \function{DocFileSuite()} above.
 
   \versionadded{2.3}
+
   \versionchanged[The parameters \var{globs}, \var{extraglobs},
     \var{test_finder}, \var{setUp}, \var{tearDown}, and
     \var{optionflags} were added; this function now uses the same search
     technique as \function{testmod()}]{2.4}
 \end{funcdesc}
 
+Under the covers, \function{DocTestSuite()} creates a
+\class{unittest.TestSuite} out of \class{doctest.DocTestCase} instances,
+and \class{DocTestCase} is a subclass of \class{unittest.TestCase}.
+\class{DocTestCase} isn't documented here (it's an internal detail), but
+studying its code can answer questions about the exact details of
+\module{unittest} integration.
+
+Similarly, \function{DocFileSuite()} creates a \class{unittest.TestSuite}
+out of \class{doctest.DocFileCase} instances, and \class{DocFileCase}
+is a subclass of \class{DocTestCase}.
+
+So both ways of creating a \class{unittest.TestSuite} run instances of
+\class{DocTestCase}.  This is important for a subtle reason:  when you
+run \module{doctest} functions yourself, you can control the
+\module{doctest} options in use directly, by passing option flags to
+\module{doctest} functions.  However, if you're writing a \module{unittest}
+framework, \module{unittest} ultimately controls when and how tests
+get run.  The framework author typically wants to control \module{doctest}
+reporting options (perhaps, e.g., specified by command line options),
+but there's no way to pass options through \module{unittest} to
+\module{doctest} test runners.
+
+For this reason, \module{doctest} also supports a notion of
+\module{doctest} reporting flags specific to \module{unittest} support,
+via this function:
+
+\begin{funcdesc}{set_unittest_reportflags}{flags}
+  Set the \module{doctest} reporting flags to use.
+
+  Argument \var{flags} or's together option flags.  See
+  section~\ref{doctest-options}.  Only "reporting flags" can be used.
+
+  This is a module-global setting, and affects all future doctests run
+  by module \module{unittest}:  the \method{runTest()} method of
+  \class{DocTestCase} looks at the option flags specified for the test
+  case when the \class{DocTestCase} instance was constructed.  If no
+  reporting flags were specified (which is the typical and expected case),
+  \module{doctest}'s \module{unittest} reporting flags are or'ed into the
+  option flags, and the option flags so augmented are passed to the
+  \class{DocTestRunner} instance created to run the doctest.  If any
+  reporting flags were specified when the \class{DocTestCase} instance
+  was constructed, \module{doctest}'s \module{unittest} reporting flags
+  are ignored.
+
+  The value of the \module{unittest} reporting flags in effect before the
+  function was called is returned by the function.
+
+  \versionadded{2.4}
+\end{funcdesc}
+
+
 \subsection{Advanced API\label{doctest-advanced-api}}
 
 The basic API is a simple wrapper that's intended to make doctest easy