Add doctests

.travis.yml

@@ -62,6 +62,8 @@ script:
   - nose2 tests --start-dir $HOME/blocks
   - nose2 doctests --start-dir $HOME/blocks
   # Running nose2 within coverage makes imports count towards coverage
-  - coverage run --source=fuel -m nose2.__main__ -v tests
+  - coverage run -p --source=fuel -m nose2.__main__ -v tests
+  - coverage run -p --source=fuel -m nose2.__main__ -v doctests
 after_script:
+  - coverage combine
   - coveralls

docs/index.rst

@@ -88,8 +88,8 @@ iterator is called an *epoch iterator*.
 
 This iterator behaves like any other Python iterator, so we call :func:`next` on it
 
->>> next(epoch)
-batch
+>>> next(epoch)  # doctest: +ELLIPSIS
+(array([[ 0.,  0.,  0., ...,  0.,  0.,  0.],...
 
 and we can use a ``for`` loop
 
@@ -99,6 +99,8 @@ and we can use a ``for`` loop
 Once we have completed the epoch, the iterator will be exhausted
 
 >>> next(epoch)
+Traceback (most recent call last):
+  ...
 StopIteration
 
 but we can ask the stream for a new one, which will provide a complete
@@ -109,7 +111,7 @@ different set of minibatches.
 We can iterate over epochs as well, providing our model with an endless stream
 of MNIST batches.
 
->>> for epoch in stream.iterate_epochs():
+>>> for epoch in stream.iterate_epochs():  # doctest: +SKIP
 ...     for batch in epoch:
 ...         pass
 

doctests/__init__.py

@@ -0,0 +1,44 @@
+from __future__ import absolute_import, print_function
+
+import doctest
+import fnmatch
+import importlib
+import os
+import pkgutil
+
+import fuel
+from tests import skip_if_not_available
+
+
+def setup(testobj):
+    skip_if_not_available(modules=['nose2'])
+    # Not importing unicode_literal because it gives problems
+    # If needed, see https://dirkjan.ochtman.nl/writing/2014/07/06/
+    # single-source-python-23-doctests.html for a solution
+    testobj.globs['absolute_import'] = absolute_import
+    testobj.globs['print_function'] = print_function
+
+
+def load_tests(loader, tests, ignore):
+    # This function loads doctests from all submodules and runs them
+    # with the __future__ imports necessary for Python 2
+    for _, module, _ in pkgutil.walk_packages(path=fuel.__path__,
+                                              prefix=fuel.__name__ + '.'):
+        try:
+            tests.addTests(doctest.DocTestSuite(
+                module=importlib.import_module(module), setUp=setup,
+                optionflags=doctest.IGNORE_EXCEPTION_DETAIL))
+        except:
+            pass
+
+    # This part loads the doctests from the documentation
+    docs = []
+    for root, _, filenames in os.walk(os.path.join(fuel.__path__[0],
+                                                   '../docs')):
+        for doc in fnmatch.filter(filenames, '*.rst'):
+            docs.append(os.path.abspath(os.path.join(root, doc)))
+    tests.addTests(doctest.DocFileSuite(
+        *docs, module_relative=False, setUp=setup,
+        optionflags=doctest.IGNORE_EXCEPTION_DETAIL))
+
+    return tests