sage -t <filename.py>
to test that all code examples in
filename.py
. Similar remarks apply to .sage
and
.pyx
files.
sage -t [--verbose] [--optional] [files and directories ... ]
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.
William: I changed the doctest behavior recently so that now you can doctest files anywhere (not necessary in \SAGE), and type e.g., sage: from foo import * sage: ... in the doctest blocks and it will work, even if foo.py isn't part of the \SAGE library. It's much better now. Feel free to change the reference manual to reflect this.
See About this document... for information on suggesting changes.