3. How to include test in your Python docstrings using doctest

Overview

This page describes the special directive doctest

Date:August 14, 2014 Author:Thomas Cokelaer

3.1. quickstart

you may want to include test directly within your RST documents or Python docstring as follows:

.. doctest::

    >>> import math
    >>> print math.sqrt(2.)
    1.41421356237

which will be displayed like that:

>>> import math
>>> print math.sqrt(2.)
1.41421356237

You can check that the code included that way is correct: in the shell, instead of compiling the HTML doc, type:

make doctest

See http://docs.python.org/library/doctest.html for a complete description.

Analysing the code above, the ‘>>>’ sign means run the command that follows. If a command returns a value then the next line must contain the expected results otherwise an error occurs. This is why we put the results of square root 2 above.

3.2. +SKIP option

Now, you may say that you do not know the expecting result or do not care about it or it may be random. In such case, you ant to skip the correctness of the output. Add this comment: #doctest: +SKIP

>>> import math
>>> print math.log(20.) 

which will be displayed like that:

>>> import math
>>> math.log(20.) 

What’s happen here is that the first line is tested, the second one is ran but the validity of the result is not tested.

If you want to skip all the commands (better to use a code-block directive in such case though), then type:

.. doctest::
    :options: +SKIP

    >>> whatever code