first cut at trace module doc

Doc/lib/lib.tex

@@ -360,7 +360,7 @@ and how to embed it in other applications.
 \input{libprofile}              % The Python Profiler
 \input{libhotshot}              % unmaintained C profiler
 \input{libtimeit}
-
+\input{libtrace}
 
 % =============
 % PYTHON ENGINE

Doc/lib/libtrace.tex

+\section{\module{trace} ---
+         Trace or track Python statement execution}
+
+\declaremodule{standard}{trace}
+\modulesynopsis{Trace or track Python statement execution.}
+
+The \module{trace} module allows you to trace program execution, generate
+annotated statement coverage listings, print caller/callee relationships and
+list functions executed during a program run.  It can be used in another
+program or from the command line.
+
+\subsection{Command Line Usage}
+
+The \module{trace} module can be invoked from the command line.  It can be
+as simple as
+
+\begin{verbatim}
+python -m trace --count somefile.py ...
+\end{verbatim}
+
+The above will generate annotated listings of all Python modules imported
+during the execution of somefile.py.
+
+\subsection{Command Line Arguments}
+
+\begin{description}
+\item[--trace, -t]{Display lines as they are executed.}
+\item[--count, -c]{Produce a set of  annotated listing files upon program
+completion that shows how many times each statement was executed.}
+\item[--report, -r]{Produce an annotated list from an earlier program run that
+used the \code{--count} and \code{--file} arguments.}
+\item[--no-report, -R]{Do not generate annotated listings.  This is useful
+if you intend to make several runs with \code{--count} then produce a single
+set of annotated listings at the end.}
+\item[--listfuncs, -l]{List the functions executed by running the program.}
+\item[--trackcalls, -T]{Generate calling relationships exposed by running the
+program.}
+\item[--file, -f]{Name a file containing (or to contain) counts.}
+\item[--coverdir, -C]{Name a directory in which to save annotated listing
+files.}
+\item[--missing, -m]{When generating annotated listings, mark lines which
+were not executed with \code{>>>>>>}.}
+\item[--summary -s]{When using \code{--count} or \code{--report}, write a
+brief summary to stdout for each file processed.}
+\item[--ignore-module]{Ignore the named module and its submodules (if it is
+a package).  May be given multiple times.}
+\item[--ignore-dir]{Ignore all modules and packages in the named directory
+and subdirectories.  May be given multiple times.}
+\end{description}
+
+\subsection{Program Usage}
+
+\begin{classdesc}{Trace}{\optional{count=1\optional{,trace=1\optional{,countfuncs=0\optional{,countcallers=0\optional{,ignoremods=()\optional{,ignoredirs=()\optional{,infile=None\optional{,outfile=None}}}}}}}}}
+
+Create an object to trace execution of a single statement or expression.
+All parameters are optional.  \var{count} enables counting of line numbers.
+\var{trace} enables line execution tracing.  \var{countfuncs} enables
+listing of the functions called during the run.  \var{countcallers} enables
+call relationship tracking.  \var{ignoremods} is a list of modules or
+packages to ignore.  \var{ignoredirs} is a list of directories whose modules
+or packages should be ignored.  \var{infile} is the file from which to read
+stored count information.  \var{outfile} is a file in which to write updated
+count information.
+
+\end{classdesc}
+
+\begin{methoddesc}[Trace]{run}{cmd}
+Run \code{cmd} under control of the Trace object with the current tracing
+parameters.
+\end{methoddesc}
+
+\begin{methoddesc}[Trace]{run}{cmd\optional{,globals=None\optional{,locals=None}}}
+Run \code{cmd} under control of the Trace object with the current tracing
+parameters in the defined global and local environments.  If not defined,
+\code{globals} and \code{locals} default to empty dictionaries.
+\end{methoddesc}
+
+\begin{methoddesc}[Trace]{runfunc}{func, *args, **kwds}
+Call \code{function} with the given arguments under control of the Trace
+object with the current tracing parameters.
+\end{methoddesc}
+
+\subsubsection{Example}
+
+\begin{verbatim}
+# create a Trace object, telling it what to ignore, and whether to
+# do tracing or line-counting or both.
+trace = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,], trace=0,
+		    count=1)
+# run the new command using the given trace
+trace.run('main()')
+# make a report, telling it where you want output
+r = trace.results()
+r.write_results(show_missing=True)
+\end{verbatim}