sage -t <file>
to test that the examples in <file>
behave exactly as claimed. This will test files of the following
types: .py .pyx .sage .tex
.
See Section 3.3 for a discussion of how to include
examples in documentation strings and what conventions to follow.
sage -t <filename.py>
to test that all code examples
in filename.py
. Similar remarks apply to .sage
and .pyx
files.
When you run sage -t <filename.py>
, SAGE makes a copy of
<filename.py>
with all the sage
prompts replaced by
>>>
, then uses the standard Python doctest framework to test
the documentation. More precisely,
the Python script local/bin/sage-doctest
implements
documentation testing. It does the following when asked
to test a file foo.py
or foo.sage
.
.doctest
if it doesn't
exist and the file .doctest/foo.py
.
.doctest/foo.py
contains functions for
each docstring in foo.py
, but with all SAGE preparsing
applied and with from sage.all import *
at the top.
The function documentation is thus standard Python with
>>>
prompts.
sage-doctest
then runs SAGE's Python interpreter
on .doctest/foo.py
.
Note:
Note that line numbers in the errors
you might see apply to the file .doctest/foo.py
, not
to the original file foo.py
! If you get errors,
feel free to inspect .doctest/foo.py
; it is never
automatically deleted by SAGE.
Your file passes these tests if the code in it will run when entered
at the sage:
prompt with no special imports. Thus users are
guaranteed to be able to exactly copy code out of the examples you
write for the documentation and have them work.
Run sage -t <filename.tex>
to test the examples in
verbatim environments in LaTeX documentation. Put
%skip
on the line right before a verbatim environment to have that
example skipped when testing the file.
SAGE creates a file .doctest/filename.py
and tests
it just as for .py
, .pyx
and .sage
files. In order to skip testing of a block of code
in a verbatim environment, put the LaTeX comment
%skip
on the previous line.
One difference is that in LaTeX files one
often inserts explanatory texts between different
verbatim environments. To link together verbatim
environments use the %link
comment. For
example4.1
\begin{verbatim} sage: a = 1 \end{verbatim_}%link Next we add 1 to \code{a}. %link \begin{verbatim} sage: 1 + a 2 \end{verbatim_}
See $SAGE_ROOT/doc/tut/tut.tex
for many examples
of how to include automated testing in LaTeX documentation
for SAGE.