Update document (#66)

* Update doc and pylint

* Update doc

.pylintrc

@@ -122,7 +122,7 @@ function-rgx=[a-z_][a-z0-9_]{2,30}$
 function-name-hint=[a-z_][a-z0-9_]{2,30}$
 
 # Regular expression matching correct variable names
-variable-rgx=[a-z_][a-z0-9_]{2,30}$
+variable-rgx=[a-z_][a-z0-9_]{1,30}$
 
 # Naming hint for variable names
 variable-name-hint=[a-z_][a-z0-9_]{2,30}$

luchador/agent/recorder.py

@@ -117,7 +117,8 @@ def _create_transition(self, index, length):
 
             For performance reason, argument validity check is omitted, but
             arguments must satisfy the following condition:
-              0 < length <= index < len(self.actions)
+
+                0 < length <= index < len(self.actions)
 
         length : int
             The number of observations included in the state

luchador/nn/core/base/cost.py

@@ -89,10 +89,15 @@ class BaseSSE2(BaseCost):
         Clip the difference between target value and prediction values
 
     elementwise : Bool
-        When true, the cost tesnor returned by `build` method has the same
-        shape as its input Tensors. When False, the cost tensor is flattened
+        When true, the cost tesnor returned by this method has the same shape
+        as its input Tensors. When False, the cost tensor is flattened
         to scalar shape by taking average over batch and sum over feature.
         Default: False.
+
+    Notes
+    -----
+    In case ``elementwise=True``, this cost is reduced to squared difference
+    between target and prediction.
     """
     def __init__(self, max_delta=None, min_delta=None, elementwise=False):
         super(BaseSSE2, self).__init__(

luchador/nn/core/base/layer.py

@@ -13,7 +13,7 @@
 
 
 class BaseLayer(common.SerializeMixin, object):
-    """Define common interface (`build`, `parameters` etc) of Layer classes"""
+    """Define common interface (``build``, ``parameters`` ...) of Layer"""
     __metaclass__ = abc.ABCMeta
 
     def __init__(self, **kwargs):
@@ -165,15 +165,23 @@ class BaseConv2D(BaseLayer):
         #filters (#output channels)
 
     strides : (int, tuple of two ints, or tuple of four ints)
-        - When given type is int, the output is subsampled by this factor
-          in both width and height direction.
-        - When given type is tuple of two int, the output is subsapmled by
-          `strides[0]` in height  and `striders[1]` in width.
-        - (Tensorflow backend only)
-          when given type is tuple of four int, it must be consistent with
-          the input data format. That is:
-            - NHWC: (batch, height, width, channel)
-            - NCHW: (batch, channel, height, width)
+        * **When given type is int**
+        The output is subsampled by this factor in both width and
+        height direction.
+
+        * **When given type is tuple of two int**
+        The output is subsapmled by ``strides[0]`` in height  and
+        ``striders[1]`` in width.
+
+        Note
+            [Tensorflow only]
+
+            When given type is tuple of four int, their order must be
+            consistent with the input data format.
+
+            **NHWC**: (batch, height, width, channel)
+
+            **NCHW**: (batch, channel, height, width)
 
     padding : (str or int or tuple of two ints)
         - Tensorflow : Either 'SAME' or 'VALID'
@@ -182,8 +190,9 @@ class BaseConv2D(BaseLayer):
     with_bias : bool
         When True bias term is added after convolution
 
-    kwargs :
-        Tensorflow: Arguments passed to tf.nn.conv2d. 'use_cudnn_on_gpu'
+    kwargs
+        use_cudnn_on_gpu
+            [Tensorflow only] : Arguments passed to ``tf.nn.conv2d``
     """
     def __init__(self, filter_height, filter_width, n_filters, strides,
                  padding='VALID', initializers=None, with_bias=True, **kwargs):

luchador/nn/core/base/optimizer.py

@@ -158,7 +158,7 @@ def __init__(self, learning_rate, name='SGD', **kwargs):
 
 
 class BaseRMSProp(BaseOptimizer):
-    """Implement RMSProp with momentum
+    """Tensorflow style RMSProp with momentum
 
     Scale learning rates by dividing with the moving average of the root mean
     squared (RMS) gradients. See [1]_ for further description.
@@ -182,10 +182,12 @@ class BaseRMSProp(BaseOptimizer):
         Decay factor at which rate accumurated RMS decays.
     momentum : float
         Momentum coefficient at which rate parameter update is accumurated.
+    epsilon : float
+        Small value added for numerical stability
     name : str
         Used to create scope which contains parameter variables
     kwargs
-        - use_lock : [TF only] passed to underlying TF native optimizer
+        use_lock : [Tensorflow only] passed to underlying TF native optimizer
 
     References
     ----------
@@ -202,6 +204,37 @@ def __init__(self, learning_rate,
 
 
 class BaseNeonRMSProp(BaseOptimizer):
+    """Neon style RMSProp
+
+    The update rule is similar to :any:`BaseRMSProp` without moemntum, but
+    epsilon appears twice.
+
+    .. math::
+        rms_t &= \\rho * rms_{t-1} + (1- \\rho) * grad ^2 \\\\
+        lr_t &= \\frac{lr}{\\sqrt{rms_t + \\epsilon} + \\epsilon} \\\\
+        var_t &= var_{t-1} - lr * grad  \\\\
+
+    where :math:`\\rho` is decay ratio
+
+    Parameters
+    ----------
+    learning_rate : float
+        The learning rate controlling the size of update steps
+    decay : float
+        Decay factor at which rate accumurated RMS decays.
+    epsilon : float
+        Small value added for numerical stability
+    name : str
+        Used to create scope which contains parameter variables
+    kwargs
+        use_lock : [Tensorflow only] passed to underlying TF native optimizer
+
+    References
+    ----------
+    .. [1] Tieleman, T. and Hinton, G. (2012):
+           Neural Networks for Machine Learning, Lecture 6.5 - rmsprop.
+           Coursera. http://www.youtube.com/watch?v=O3sxAc4hxZU (formula @5:20)
+    """
     def __init__(self, learning_rate, decay=0.95, epsilon=1e-6,
                  name='NeonRMSProp', **kwargs):
         super(BaseNeonRMSProp, self).__init__(
@@ -210,10 +243,17 @@ def __init__(self, learning_rate, decay=0.95, epsilon=1e-6,
 
 
 class BaseGravesRMSProp(BaseOptimizer):
-    """RMSProp used in DQN paper[1] and described in A.Graves paper [2]
+    """RMSProp used in DQN paper [1]_ and described in A.Graves paper [2]_
 
-    [1] https://github.com/kuz/DeepMind-Atari-Deep-Q-Learner/blob/4b9f5a79b03ea0cfc512ed1c11f1b00bc875bc57/dqn/NeuralQLearner.lua#L265  # nopep8
-    [2] http://arxiv.org/pdf/1308.0850v5.pdf
+    References
+    ----------
+    .. [1] Mnih, V et. al (2015)
+           Human-level control through deep reinforcement learning
+           https://storage.googleapis.com/deepmind-media/dqn/DQNNaturePaper.pdf
+           https://github.com/kuz/DeepMind-Atari-Deep-Q-Learner/blob/4b9f5a79b03ea0cfc512ed1c11f1b00bc875bc57/dqn/NeuralQLearner.lua#L265
+    .. [2] Graves, A. (2014):
+           Generating Sequences With Recurrent Neural Networks
+           http://arxiv.org/pdf/1308.0850v5.pdf
     """
     def __init__(self, learning_rate,
                  decay1=0.95, decay2=0.95,