better documentation for lazyimports

closes nipy#102

nitime/lazy.py

@@ -29,9 +29,9 @@
 file, and then ``from nitime.lazy import your_new_package``.
 
 If there's a package that you would like to lazily load in your own code that
-is not listed here, use the LazyImport class (which is in nitime.lazyimports).
+is not listed here, use the :class:`LazyImport` class (which is in
+:mod:`nitime.lazyimports`).
 """
-import sys
 from .lazyimports import LazyImport
 
 # matplotlib
@@ -46,3 +46,8 @@
 scipy_signal_signaltools = LazyImport('scipy.signal.signaltools')
 scipy_stats = LazyImport('scipy.stats')
 scipy_stats_distributions = LazyImport('scipy.stats.distributions')
+
+def enabled():
+    "Are LazyImports globally enabled?"
+    import nitime.lazyimports as l
+    return not l.disable_lazy_imports

nitime/lazyimports.py

@@ -7,7 +7,7 @@
 (including inside IPython with respect to introspection and tab completion)
 with the *exception* of reload() - reloading a LazyImport has no effect.
 
-Commonly used nitime lazy imports are also defined in lazy.py, so they can be
+Commonly used nitime lazy imports are also defined in :mod:`nitime.lazy`, so they can be
 reused throughout nitime.
 """
 import sys
@@ -71,16 +71,20 @@ def __repr__(self):
                 object.__getattribute__(self,'__name__')
 
 if disable_lazy_imports:
-    extra_doc = ''
+    lazy_doc = """LazyImports have been globally disabled.
+    Please modify ``disable_lazy_imports`` boolean variable in
+    ``nitime.lazyimports`` in order to leverage lazy loading of modules.
+    """
     if 'sphinx' in sys.modules:
-        extra_doc = """
-                    WARNING: To get Sphinx documentation to build we disable
-                    LazyImports, which makes Sphinx incorrectly report this
-                    class as have a base class of object. In reality,
-                    ``LazyImport``'s base class is ``types.ModuleType``
-                    """
+        lazy_doc = """
+                   WARNING: To get Sphinx documentation to build we disable
+                   LazyImports, which makes Sphinx incorrectly report this
+                   class as having a base class of object. In reality,
+                   ``LazyImport``'s base class is ``types.ModuleType``
+                   """
+        lazy_doc += LazyImport.__doc__
     class LazyImport(object):
-        __doc__ = extra_doc + LazyImport.__doc__
+        __doc__ = lazy_doc
         def __init__(self, x):
             __import__(x)
             self.module = sys.modules[x]