Clarified differences between module/test doctest fixtures

1 files changed, 23 insertions, 12 deletions

diff --git a/functional_tests/doc_tests/test_doctest_fixtures/doctest_fixtures.rst b/functional_tests/doc_tests/test_doctest_fixtures/doctest_fixtures.rst
index b691aa0..6ff8fed 100644
--- a/functional_tests/doc_tests/test_doctest_fixtures/doctest_fixtures.rst
+++ b/functional_tests/doc_tests/test_doctest_fixtures/doctest_fixtures.rst
@@ -5,6 +5,9 @@ Doctest files, like other tests, can be made more efficient or meaningful or
 at least easier to write by judicious use of fixtures. nose supports limited
 fixtures for use with doctest files. 
 
+Module-level fixtures
+=====================
+
 Fixtures for a doctest file may define any or all of the following methods for
 module-level setup:
 
@@ -35,13 +38,25 @@ Example::
       module.called[:] = []
       module.done = True
 
+Module-level setup executes **before any tests are loaded** from the doctest
+file. This is the right place to raise :class:`nose.plugins.skip.SkipTest`,
+for example.
+      
+Test-level fixtures
+===================
+
 In addition to module-level fixtures, *test*-level fixtures are
 supported. Keep in mind that in the doctest lexicon, the *test* is the *entire
 doctest file* -- not each individual example within the file. So, like the
-module-level fixtures, test-level fixtures execute *once per file*.
+module-level fixtures, test-level fixtures execute *once per file*. The
+differences are that:
+
+- test-level fixtures execute **after** tests have been loaded, but **before**
+  any tests have executed.
+- test-level fixtures receive the doctest :class:`doctest.DocFileCase` loaded
+  from the file as their one *required* argument.
       
-**setup_test(test)** is called before the test is run. The arrgument is the
-*doctest.DocTest* object, *not* a unittest.TestCase.
+**setup_test(test)** is called before the test is run.
 
 Example::
 
@@ -51,8 +66,8 @@ Example::
   setup_test.__test__ = False
       
 **teardown_test(test)** is alled after the test, unless setup raised an
-uncaught exception. The argument is the *doctest.DocTest* object, *not* a
-unittest.TestCase.
+uncaught exception. The argument is the :class:`doctest.DocFileCase` object,
+*not* a unittest.TestCase.
 
 Example::
 
@@ -61,7 +76,8 @@ Example::
   teardown_test.__test__ = False
   
 Bottom line: setup_test, teardown_test have access to the *doctest test*,
-while setup, setup_module, etc have access to the *fixture* module.
+while setup, setup_module, etc have access to the *fixture*
+module. setup_module runs before tests are loaded, setup_test after.
 
 .. note ::
 
@@ -103,9 +119,4 @@ The ``count`` variable is injected by the test-level fixture.
     1
 
   Thus, ``count`` stays 1 throughout the test, no matter how many examples it
-  includes.
-   
-
-
-
-
+  includes.
\ No newline at end of file