add docs for NanGuardMode

doc/library/compile/nanguardmode.txt

@@ -16,4 +16,55 @@ Guide
 
 The NanGuardMode aims to prevent the model from outputing NaNs or Infs. It has
 a number of self-checks, which can help to find out which apply node is
-generating those incorrect outputs.
+generating those incorrect outputs. It provides automatic detection on 3 types
+of abnormal values: NaNs, Infs, and abnormally big values.
+
+NanGuardMode can be used as follows:
+
+.. code-block:: python
+
+    x = T.matrix()
+    w = theano.shared(numpy.random.randn(5, 7).astype(theano.config.floatX))
+    y = T.dot(x, w)
+    fun = theano.function(
+        [x], y,
+        mode=NanGuardMode(nan_is_error=True, inf_is_error=True, big_is_error=True)
+    )
+
+While using the theano function ``fun``, it will monitor the values of each
+input and output variable of each node. As long as the abnormal values are
+detected, it raises an error to indicate which node yields the NaNs. For
+example, if we pass the following values to ``fun``:
+
+.. code-block:: python
+
+    infa = numpy.tile(
+        (numpy.asarray(100.) ** 1000000).astype(theano.config.floatX), (3, 5))
+    fun(infa)
+
+It will raise an AssertionError indicating that Inf value is detected while
+executing the function.
+
+You can also set the three parameters in ``NanGuardMode()`` to indicate which
+kind of abnormal values to monitor. ``nan_is_error`` and ``inf_is_error`` has
+no default values, so they need to be set explicitly, but ``big_is_error`` is
+set to be ``True`` by default.
+
+Reference
+=========
+
+.. class:: NanGuardMode(Mode)
+
+    A Theano compilation Mode that makes the compiled function automatically
+    detect NaNs and Infs and raise an error if they occur.
+
+    Parameters
+    ----------
+    nan_is_error : bool
+        If True, raise an error anytime a NaN is encountered
+    inf_is_error: bool
+        If True, raise an error anytime an Inf is encountered.  Note that some
+        modules might use np.inf as a default value (e.g. mlp.max_pool in
+        pylearn2) and these will cause an error if inf_is_error is True.
+    big_is_error: bool
+        If True, raise an error when a value greater than 1e10 is encountered.

doc/tutorial/nan_tutorial.txt

@@ -33,19 +33,24 @@ those weights are not initialized in a proper range, then it is not surprising
 that the model ends up with yielding NaNs. 
 
 
-Run in DebugMode
------------------
+Run in NanGuardMode, DebugMode, or MonitorMode
+-----------------------------------------------
 
 If adjusting hyperparameters doesn't work for you, you can still get help from
-Theano's DebugMode. Run your code in DebugMode with flag mode=DebugMode,
+Theano's NanGuardMode. change the mode of your theano function to NanGuardMode,
+and run them again. The NanGuardMode will monitor all input/output variables in
+each node, and raises an error if NaNs are detected. For how to use the
+``NanGuardMode``, please refer to :ref:`nanguardmode`.
+
+DebugMode can also help. Run your code in DebugMode with flag mode=DebugMode,
 DebugMode.check_py=False. This will give you clue about which op is causing this
 problem, and then you can inspect into that op in more detail. For a detailed
 of using DebugMode, please refere to :ref:`debugmode`.
 
-Theano's MonitorMode can also help. It can be used to step through the execution
-of a function. You can inspect the inputs and outputs of each node being
-executed when the function is called. For how to use that, please check
-:ref:`faq_monitormode`. 
+Theano's MonitorMode provides another helping hand. It can be used to step
+through the execution of a function. You can inspect the inputs and outputs of
+each node being executed when the function is called. For how to use that,
+please check :ref:`faq_monitormode`.
 
 
 Numerical Stability