[Python-checkins] python/dist/src/Doc/lib libdoctest.tex,1.16,1.17
fdrake@users.sourceforge.net
fdrake@users.sourceforge.net
Thu, 17 Jul 2003 09:00:03 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv30668
Modified Files:
libdoctest.tex
Log Message:
more markup chages
Index: libdoctest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v
retrieving revision 1.16
retrieving revision 1.17
diff -C2 -d -r1.16 -r1.17
*** libdoctest.tex 17 Jul 2003 15:22:47 -0000 1.16
--- libdoctest.tex 17 Jul 2003 16:00:01 -0000 1.17
***************
*** 86,91 ****
\end{verbatim}
! If you run \file{example.py} directly from the command line, doctest works
! its magic:
\begin{verbatim}
--- 86,91 ----
\end{verbatim}
! If you run \file{example.py} directly from the command line,
! \module{doctest} works its magic:
\begin{verbatim}
***************
*** 94,100 ****
\end{verbatim}
! There's no output! That's normal, and it means all the examples worked.
! Pass \programopt{-v} to the script, and doctest prints a detailed log
! of what it's trying, and prints a summary at the end:
\begin{verbatim}
--- 94,101 ----
\end{verbatim}
! There's no output! That's normal, and it means all the examples
! worked. Pass \programopt{-v} to the script, and \module{doctest}
! prints a detailed log of what it's trying, and prints a summary at the
! end:
\begin{verbatim}
***************
*** 136,142 ****
\end{verbatim}
! That's all you need to know to start making productive use of doctest! Jump
! in. The docstrings in doctest.py contain detailed information about all
! aspects of doctest, and we'll just cover the more important points here.
\subsection{Normal Usage}
--- 137,144 ----
\end{verbatim}
! That's all you need to know to start making productive use of
! \module{doctest}! Jump in. The docstrings in \file{doctest.py} contain
! detailed information about all aspects of \module{doctest}, and we'll
! just cover the more important points here.
\subsection{Normal Usage}
***************
*** 286,291 ****
\begin{funcdesc}{DocTestSuite}{\optional{module}}
! Convert doctest tests for a module to a \refmodule{unittest}
! \class{TestSuite}.
The returned \class{TestSuite} is to be run by the unittest framework
--- 288,293 ----
\begin{funcdesc}{DocTestSuite}{\optional{module}}
! Convert doctest tests for a module to a
! \class{\refmodule{unittest}.TestSuite}.
The returned \class{TestSuite} is to be run by the unittest framework
***************
*** 321,328 ****
\subsection{How are Docstring Examples Recognized?}
! In most cases a copy-and-paste of an interactive console session works fine
! --- just make sure the leading whitespace is rigidly consistent (you can mix
! tabs and spaces if you're too lazy to do it right, but doctest is not in
! the business of guessing what you think a tab means).
\begin{verbatim}
--- 323,331 ----
\subsection{How are Docstring Examples Recognized?}
! In most cases a copy-and-paste of an interactive console session works
! fine---just make sure the leading whitespace is rigidly consistent
! (you can mix tabs and spaces if you're too lazy to do it right, but
! \module{doctest} is not in the business of guessing what you think a tab
! means).
\begin{verbatim}
***************
*** 487,509 ****
\subsection{Soapbox}
! The first word in doctest is "doc", and that's why the author wrote
! doctest: to keep documentation up to date. It so happens that doctest
! makes a pleasant unit testing environment, but that's not its primary
! purpose.
! Choose docstring examples with care. There's an art to this that needs to
! be learned --- it may not be natural at first. Examples should add genuine
! value to the documentation. A good example can often be worth many words.
! If possible, show just a few normal cases, show endcases, show interesting
! subtle cases, and show an example of each kind of exception that can be
! raised. You're probably testing for endcases and subtle cases anyway in an
! interactive shell: doctest wants to make it as easy as possible to capture
! those sessions, and will verify they continue to work as designed forever
! after.
! If done with care, the examples will be invaluable for your users, and will
! pay back the time it takes to collect them many times over as the years go
! by and "things change". I'm still amazed at how often one of my doctest
! examples stops working after a "harmless" change.
For exhaustive testing, or testing boring cases that add no value to the
--- 490,514 ----
\subsection{Soapbox}
! The first word in ``doctest'' is ``doc,'' and that's why the author
! wrote \refmodule{doctest}: to keep documentation up to date. It so
! happens that \refmodule{doctest} makes a pleasant unit testing
! environment, but that's not its primary purpose.
! Choose docstring examples with care. There's an art to this that
! needs to be learned---it may not be natural at first. Examples should
! add genuine value to the documentation. A good example can often be
! worth many words. If possible, show just a few normal cases, show
! endcases, show interesting subtle cases, and show an example of each
! kind of exception that can be raised. You're probably testing for
! endcases and subtle cases anyway in an interactive shell:
! \refmodule{doctest} wants to make it as easy as possible to capture
! those sessions, and will verify they continue to work as designed
! forever after.
! If done with care, the examples will be invaluable for your users, and
! will pay back the time it takes to collect them many times over as the
! years go by and things change. I'm still amazed at how often one of
! my \refmodule{doctest} examples stops working after a ``harmless''
! change.
For exhaustive testing, or testing boring cases that add no value to the