Sphinx doctest vs autodoc

Question

I am seemingly unable to make the Sphinx autodoc and doctest extensions play nicely together.

I have a doctested Python project in which the docstrings are working just fine. That is, calling doctest.testmod() on my modules and submodules works well.

In the Sphinx documentation of the project, I am using the ext.autodoc extension and the automodule directive to automatically import the modules' documentation into the .rst documents for each module.

I wanted to start using the ext.doctest Sphinx extension to write some user documentation and tutorials, and to have them automatically checked for correctness. However, the problem is that apparently the doctest extension parses the docstrings from the automodule d docs, tries to run them and fails (a lot of errors about being unable to find the types referred in the docstrings, and other problems like this).

I don't really want ext.doctest to run the doctests from the Python code (they are already run as part of the test suite). Is there a way to tell Sphinx not to try running doctests appearing in certain files?

Answer 1

I was having a similar issue. Adding the "testsetup" directive to my module's docstring solved that issue for me. Though, it's unfortunate you have to do this.

"""Foo module types and functions

.. testsetup:: *

   from foo import *
   from foo.bar import *
"""

http://sphinx-doc.org/ext/doctest.html#directive-testsetup

Answer 2

If you wish to tell Sphinx NOT to run the doctests from autodoc/automodule, modify the doctest_test_doctest_blocks parameter in your conf.py file

doctest_test_doctest_blocks = None

Note that this will also disable any ''plain'' doctest blocks in your rst files (ie doctests which are not explicitly marked with the .. doctest: directive).