Doc improvements

1 files changed, 70 insertions, 45 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 2e15eb4..b691aa0 100644
--- a/functional_tests/doc_tests/test_doctest_fixtures/doctest_fixtures.rst
+++ b/functional_tests/doc_tests/test_doctest_fixtures/doctest_fixtures.rst
@@ -1,41 +1,33 @@
 Doctest Fixtures
 ----------------
 
-FIXME blah blah FIXME
+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. 
 
-.. include :: doctest_fixtures_fixtures.py
-   :literal:
-
-FIXME examples
-   
-    >>> something
-    'Something?'
-    
-    >>> 1
-    1
-    >>> count
-    1
-
-This whole file is one doctest test. setup_test doesn't do what you think!
-It exists to give you access to the test case and examples, but it runs
-*once*, before all of them, not before each.
-
-    >>> count
-    1
+Fixtures for a doctest file may define any or all of the following methods for
+module-level setup:
 
-   
-Fixtures for a doctest file may define any or all of the following methods:
+* setup
+* setup_module
+* setupModule
+* setUpModule
 
-setup/setup_module/setupModule/setUpModule (module)
-===================================================
+Each module-level setup function may optionally take a single argument, the
+fixtures module itself.
 
 Example::
 
   def setup_module(module):
       module.called[:] = []
 
-teardown/teardown_module/teardownModule/tearDownModule (module)
-===============================================================
+Similarly, module-level teardown methods are available, which also optionally
+take the fixtures module as an argument:
+      
+* teardown
+* teardown_module
+* teardownModule
+* tearDownModule
 
 Example::
 
@@ -43,11 +35,13 @@ Example::
       module.called[:] = []
       module.done = True
 
-setup_test(test)
-================
-
-Called before each test. Argument is the *doctest.DocTest* object, *not* a
-unittest.TestCase.
+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*.
+      
+**setup_test(test)** is called before the test is run. The arrgument is the
+*doctest.DocTest* object, *not* a unittest.TestCase.
 
 Example::
 
@@ -56,18 +50,9 @@ Example::
       test.globs['count'] = len(called)
   setup_test.__test__ = False
       
-
-This is another example.
-
-
-And this is yet another example.
-
-
-teardown_test(test)
-===================
-
-Called after each test, unless setup raised an uncaught exception. Argument is
-the *doctest.DocTest* object, *not* a unittest.TestCase.
+**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.
 
 Example::
 
@@ -78,8 +63,48 @@ Example::
 Bottom line: setup_test, teardown_test have access to the *doctest test*,
 while setup, setup_module, etc have access to the *fixture* module.
 
-globs(globs)
-============
+.. note ::
+
+   As in the examples, it's a good idea to tag your setup_test/teardown_test
+   functions with ``__test__ = False`` to avoid them being collected as tests.
+
+Lastly, the fixtures for a doctest file may supply a **globs(globs)**
+function. The dict returned by this function will be passed to the doctest
+runner as the globals available to the test. You can use this, for example, to
+easily inject a module's globals into a doctest that has been moved from the
+module to a separate file. 
+
+Example
+=======
+
+This doctest has some simple fixtures:
+
+.. include :: doctest_fixtures_fixtures.py
+   :literal:
+
+The ``globs`` defined in the fixtures make the variable ``something``
+available in all examples.
+   
+    >>> something
+    'Something?'
+
+The ``count`` variable is injected by the test-level fixture.
+    
+    >>> count
+    1
+
+.. warning ::
+
+  This whole file is one doctest test. setup_test doesn't do what you think!
+  It exists to give you access to the test case and examples, but it runs
+  *once*, before all of them, not before each.
+
+    >>> count
+    1
+
+  Thus, ``count`` stays 1 throughout the test, no matter how many examples it
+  includes.
+