doctest.rst

rest

sphinx.ext.doctest -- Test snippets in the documentation

sphinx.ext.doctest

pair: automatic; testing single: doctest pair: testing; snippets

It is often helpful to include snippets of code in your documentation and demonstrate the results of executing them. But it is important to ensure that the documentation stays up-to-date with the code.

This extension allows you to test such code snippets in the documentation in a natural way. If you mark the code blocks as shown here, the doctest builder will collect them and run them as doctest tests.

Within each document, you can assign each snippet to a group. Each group consists of:

• zero or more setup code blocks (e.g. importing the module to test)
• one or more test blocks

When building the docs with the doctest builder, groups are collected for each document and run one after the other, first executing setup code blocks, then the test blocks in the order they appear in the file.

There are two kinds of test blocks:

• doctest-style blocks mimic interactive sessions by interleaving Python code (including the interpreter prompt) and output.
• code-output-style blocks consist of an ordinary piece of Python code, and optionally, a piece of output for that code.

Directives

The group argument below is interpreted as follows: if it is empty, the block is assigned to the group named default. If it is *, the block is assigned to all groups (including the default group). Otherwise, it must be a comma-separated list of group names.

The following is an example for the usage of the directives. The test via :rstdoctest and the test via :rsttestcode and :rsttestoutput are equivalent. :

The parrot module
=================

.. testsetup:: *

   import parrot

The parrot module is a module about parrots.

Doctest example:

.. doctest::

   >>> parrot.voom(3000)
   This parrot wouldn't voom if you put 3000 volts through it!

Test-Output example:

.. testcode::

   parrot.voom(3000)

This would output:

.. testoutput::

   This parrot wouldn't voom if you put 3000 volts through it!

Skipping tests conditionally

skipif, a string option, can be used to skip directives conditionally. This may be useful e.g. when a different set of tests should be run depending on the environment (hardware, network/VPN, optional dependencies or different versions of dependencies). The skipif option is supported by all of the doctest directives. Below are typical use cases for skipif when used for different directives:

• :rsttestsetup and :rsttestcleanup
  • conditionally skip test setup and/or cleanup
  • customize setup/cleanup code per environment
• :rstdoctest
  • conditionally skip both a test and its output verification
• :rsttestcode
  • conditionally skip a test
  • customize test code per environment
• :rsttestoutput
  • conditionally skip output assertion for a skipped test
  • expect different output depending on the environment

The value of the skipif option is evaluated as a Python expression. If the result is a true value, the directive is omitted from the test run just as if it wasn't present in the file at all.

Instead of repeating an expression, the doctest_global_setup configuration option can be used to assign it to a variable which can then be used instead.

Here's an example which skips some tests if Pandas is not installed:

extensions = ['sphinx.ext.doctest']
doctest_global_setup = '''
try:
    import pandas as pd
except ImportError:
    pd = None
'''

.. testsetup::
   :skipif: pd is None

   data = pd.Series([42])

.. doctest::
   :skipif: pd is None

   >>> data.iloc[0]
   42

.. testcode::
   :skipif: pd is None

   print(data.iloc[-1])

.. testoutput::
   :skipif: pd is None

   42

Configuration

The doctest extension uses the following configuration values:

doctest_default_flags

By default, these options are enabled:

• ELLIPSIS, allowing you to put ellipses in the expected output that match anything in the actual output;
• IGNORE_EXCEPTION_DETAIL, causing everything following the leftmost colon and any module information in the exception name to be ignored;
• DONT_ACCEPT_TRUE_FOR_1, rejecting "True" in the output where "1" is given -- the default behavior of accepting this substitution is a relic of pre-Python 2.2 times.

1.5

doctest_path

A list of directories that will be added to sys.path when the doctest builder is used. (Make sure it contains absolute paths.)

doctest_global_setup

Python code that is treated like it were put in a testsetup directive for every file that is tested, and for every group. You can use this to e.g. import modules you will always need in your doctests.

0.6

doctest_global_cleanup

Python code that is treated like it were put in a testcleanup directive for every file that is tested, and for every group. You can use this to e.g. remove any temporary files that the tests leave behind.

1.1

doctest_test_doctest_blocks

If this is a nonempty string (the default is 'default'), standard reST doctest blocks will be tested too. They will be assigned to the group name given.

reST doctest blocks are simply doctests put into a paragraph of their own, like so:

Some documentation text.

>>> print(1)
1

Some more documentation text.

(Note that no special :: is used to introduce a doctest block; docutils recognizes them from the leading >>>. Also, no additional indentation is used, though it doesn't hurt.)

If this value is left at its default value, the above snippet is interpreted by the doctest builder exactly like the following:

Some documentation text.

.. doctest::

   >>> print(1)
   1

Some more documentation text.

This feature makes it easy for you to test doctests in docstrings included with the ~sphinx.ext.autodoc extension without marking them up with a special directive.

Note though that you can't have blank lines in reST doctest blocks. They will be interpreted as one block ending and another one starting. Also, removal of <BLANKLINE> and # doctest: options only works in :rstdoctest blocks, though you may set trim_doctest_flags to achieve that in all code blocks with Python console content.