[Python-checkins] python/dist/src/Doc/lib libdoctest.tex,1.46,1.47

[tim_one at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv12175/Doc/lib

Modified Files:
	libdoctest.tex 
Log Message:
Beef up the section on testfile(), giving a complete example in
reStructuredText format.  Remove words describing the return value of
testmod() and testfile() in the intro sections, since it's never
useful in such simple cases.


Index: libdoctest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v
retrieving revision 1.46
retrieving revision 1.47
diff -u -d -r1.46 -r1.47
--- libdoctest.tex	25 Sep 2004 00:11:43 -0000	1.46
+++ libdoctest.tex	25 Sep 2004 00:49:53 -0000	1.47
@@ -165,14 +165,13 @@
 \begin{verbatim}
 def _test():
     import doctest
-    return doctest.testmod()
+    doctest.testmod()
 
 if __name__ == "__main__":
     _test()
 \end{verbatim}
 
-\module{doctest} then examines docstrings in the module calling
-\function{testmod()}.
+\module{doctest} then examines docstrings in module \module{M}.
 
 Running the module as a script causes the examples in the docstrings
 to get executed and verified:
@@ -184,7 +183,7 @@
 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
-\samp{'***Test Failed*** \var{N} failures.'}, where \var{N} is the
+\samp{***Test Failed*** \var{N} failures.}, where \var{N} is the
 number of examples that failed.
 
 Run it with the \programopt{-v} switch instead:
@@ -199,12 +198,8 @@
 You can force verbose mode by passing \code{verbose=True} to
 \function{testmod()}, or
 prohibit it by passing \code{verbose=False}.  In either of those cases,
-\code{sys.argv} is not examined by \function{testmod()}.
-
-In any case, \function{testmod()} returns a 2-tuple of ints
-\samp{(\var{failure_count}, \var{test_count})}, where
-\var{failure_count} is the number of docstring examples that failed
-and \var{test_count} is the total number of docstring examples tested.
+\code{sys.argv} is not examined by \function{testmod()} (so passing
+\programopt{-v} or not has no effect).
 
 For more information on \function{testmod()}, see
 section~\ref{doctest-basic-api}.
@@ -218,15 +213,50 @@
 
 \begin{verbatim}
 import doctest
-doctest.testfile("mytests.txt")
+doctest.testfile("example.txt")
 \end{verbatim}
 
-This short script will execute and verify any interactive Python
-examples contained in the file \file{mytests.txt}.  As with
-\function{testmod()}, it won't display anything unless an 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 \function{testmod()}.
+That short script executes and verifies any interactive Python
+examples contained in the file \file{example.txt}.  The file content
+is treated as if it were a single giant docstring; the file doesn't
+need to contain a Python program!   For example, perhaps \file{example.txt}
+contains this:
+
+\begin{verbatim}
+The ``example`` module
+======================
+
+Using ``factorial``
+-------------------
+
+This is an example text file in reStructuredText format.  First import
+``factorial`` from the ``example`` module:
+
+    >>> from example import factorial
+
+Now use it:
+
+    >>> factorial(6)
+    120
+\end{verbatim}
+
+Running \code{doctest.testfile("example.txt")} then finds the error
+in this documentation:
+
+\begin{verbatim}
+File "./example.txt", line 14, in example.txt
+Failed example:
+    factorial(6)
+Expected:
+    120
+Got:
+    720
+\end{verbatim}
+
+As with \function{testmod()}, \function{testfile()} won't display anything
+unless an 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 \function{testmod()}.
 
 By default, \function{testfile()} looks for files in the calling
 module's directory.  See section~\ref{doctest-basic-api} for a
@@ -235,11 +265,7 @@
 
 Like \function{testmod()}, \function{testfile()}'s verbosity can be
 set with the \programopt{-v} command-line switch or with the optional
-keyword argument \var{verbose}.  And like \function{testmod()},
-\function{testfile()} returns a 2-tuple of ints
-\samp{(\var{failure_count}, \var{test_count})}, where
-\var{failure_count} is the number of docstring examples that failed
-and \var{test_count} is the total number of docstring examples tested.
+keyword argument \var{verbose}.
 
 For more information on \function{testfile()}, see
 section~\ref{doctest-basic-api}.