If you run \file{example.py} directly from the command line, doctest works

its magic:

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:

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.

Convert doctest tests for a module to a \refmodule{unittest}

\class{TestSuite}.

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

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.