Why could doctests raise a NameError when run with Sphinx's `make doctest`?

Question

I have a simple function with a doctest, which, when run with Sphinx's make doctest, gives me the following error:

File "scheemey.rst", line ?, in default
Failed example:
    verify_balanced('asdf (foo [bar] [[baz], {}, ()]')
Exception raised:
    Traceback (most recent call last):
      File "/usr/local/Cellar/python/2.7.8/Frameworks/Python.framework/Versions/2.7/lib/python2.7/doctest.py", line 1315, in __run
        compileflags, 1) in test.globs
      File "<doctest default[0]>", line 1, in <module>
        verify_balanced('asdf (foo [bar] [[baz], {}, ()]')
    NameError: name 'verify_balanced' is not defined

What could be causing this?

Answer 1

I can reproduce the error in the question if the module with the tested function is not imported properly.

To make it work, you can use a testsetup directive:

.. testsetup:: 

   from yourmodule import verify_balanced

>>> verify_balanced('asdf (foo) [bar] [[baz], {}, ()]')
>>> verify_balanced('asdf (foo [bar] [[baz], {}, ()]')
5

Note that doctest ignores None return values (see Python doctests: test for None).