4.3.1 Testing .py, .pyx and .sage Files

Run 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.

  1. Creates the directory .doctest if it doesn't exist and the file .doctest/foo.py.

  2. The file .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.

  3. 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.