Improve docs (#331)

* check layers docs

* check cost docs

* check prepro

* fixed DeformableConv2d TODO

* check iterate

* check utils

* check nlp

* check rein

* check files

* check visulize

* check activation

* yapf

* fix utils docs

* add ops back

* add supress stdout back for compatibility.

* add an alias for ops.supress_output

* fix indentation

* fix all docs warnings.

* fix luomai comment

* nlp

* fix nlp typos.

Author: zsdonghao

docs/modules/cost.rst

@@ -30,7 +30,8 @@ then you can apply L2 regularization on the weights matrix of first two layer as
 .. code-block:: python
 
   cost = tl.cost.cross_entropy(y, y_)
-  cost = cost + tf.contrib.layers.l2_regularizer(0.001)(network.all_params[0]) + tf.contrib.layers.l2_regularizer(0.001)(network.all_params[2])
+  cost = cost + tf.contrib.layers.l2_regularizer(0.001)(network.all_params[0])
+          + tf.contrib.layers.l2_regularizer(0.001)(network.all_params[2])
 
 Besides, TensorLayer provides a easy way to get all variables by a given name, so you can also
 apply L2 regularization on some weights as follow.
@@ -44,6 +45,7 @@ apply L2 regularization on some weights as follow.
 
 
 
+
 Regularization of Weights
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -75,12 +77,11 @@ Then max-norm regularization on W1 and W2 can be performed as follow.
 
 .. code-block:: python
 
-  y = network.outputs
-  # Alternatively, you can use tl.cost.cross_entropy(y, y_) instead.
-  cross_entropy = tf.reduce_mean(tf.nn.sparse_softmax_cross_entropy_with_logits(y, y_))
-  cost = cross_entropy
-  cost = cost + tl.cost.maxnorm_regularizer(1.0)(network.all_params[0]) +
-            tl.cost.maxnorm_regularizer(1.0)(network.all_params[2])
+  max_norm = 0
+  for w in tl.layers.get_variables_with_name('W', train_only=True, printable=False):
+      max_norm += tl.cost.maxnorm_regularizer(1)(w)
+  cost = tl.cost.cross_entropy(y, y_) + max_norm
+
 
 In addition, all TensorFlow's regularizers like
 ``tf.contrib.layers.l2_regularizer`` can be used with TensorLayer.

docs/modules/prepro.rst

@@ -108,7 +108,7 @@ Images
 
 - These functions only apply on a single image, use ``threading_data`` to apply multiple threading see ``tutorial_image_preprocess.py``.
 - All functions have argument ``is_random``.
-- All functions end with `multi` , usually be used for image segmentation i.e. the input and output image should be matched.
+- All functions end with ``*_multi`` process all images together, usually be used for image segmentation i.e. the input and output image should be matched.
 
 Rotation
 ^^^^^^^^^

docs/modules/utils.rst

@@ -14,6 +14,10 @@ API - Utility
    dict_to_one
    list_string_to_dict
    flatten_list
+   exit_tensorflow
+   open_tensorboard
+   clear_all_placeholder_variables
+   set_gpu_fraction
 
 Training, testing and predicting
 ----------------------------------
@@ -58,17 +62,17 @@ Flatten a list
 .. autofunction:: flatten_list
 
 Close TF session and associated processes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------------------
 .. autofunction:: exit_tensorflow
 
 Open TensorBoard
-^^^^^^^^^^^^^^^^^^^
+----------------
 .. autofunction:: open_tensorboard
 
 Clear TensorFlow placeholder
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------
 .. autofunction:: clear_all_placeholder_variables
 
 Set GPU functions
----------------------------
-.. autofunction:: set_gpu_fraction
+-----------------
+.. autofunction:: set_gpu_fraction

tensorlayer/activation.py

@@ -112,8 +112,8 @@ def pixel_wise_softmax(x, name='pixel_wise_softmax'):
     ----------
     x : Tensor
         input.
-        - For 2d image, 4D tensor (batch_size, height, weight, channel), where channel >= 2.
-        - For 3d image, 5D tensor (batch_size, depth, height, weight, channel), where channel >= 2.
+            - For 2d image, 4D tensor (batch_size, height, weight, channel), where channel >= 2.
+            - For 3d image, 5D tensor (batch_size, depth, height, weight, channel), where channel >= 2.
     name : str
         function name (optional)
 

tensorlayer/cost.py

@@ -6,14 +6,14 @@
 
 
 def cross_entropy(output, target, name=None):
-    """It is a softmax cross-entropy operation, returns the TensorFlow expression of cross-entropy of two distributions, implement
+    """Softmax cross-entropy operation, returns the TensorFlow expression of cross-entropy for two distributions, it implements
     softmax internally. See ``tf.nn.sparse_softmax_cross_entropy_with_logits``.
 
     Parameters
     ----------
-    output : Tensorflow variable
+    output : Tensor
         A batch of distribution with shape: [batch_size, num of classes].
-    target : Tensorflow variable
+    target : Tensor
         A batch of index with shape: [batch_size, ].
     name : string
         Name of this loss.
@@ -36,7 +36,7 @@ def cross_entropy(output, target, name=None):
 
 
 def sigmoid_cross_entropy(output, target, name=None):
-    """It is a sigmoid cross-entropy operation, see ``tf.nn.sigmoid_cross_entropy_with_logits``.
+    """Sigmoid cross-entropy operation, see ``tf.nn.sigmoid_cross_entropy_with_logits``.
 
     Parameters
     ----------
@@ -55,11 +55,7 @@ def sigmoid_cross_entropy(output, target, name=None):
 
 
 def binary_cross_entropy(output, target, epsilon=1e-8, name='bce_loss'):
-    """It is a binary cross entropy operation.
-
-    # For brevity, let `x = output`, `z = target`.  The binary cross entropy loss is
-    #
-    #     loss(x, z) = - sum_i (x[i] * log(z[i]) + (1 - x[i]) * log(1 - z[i]))
+    """Binary cross entropy operation.
 
     Parameters
     ----------
@@ -74,7 +70,7 @@ def binary_cross_entropy(output, target, epsilon=1e-8, name='bce_loss'):
 
     References
     -----------
-    - `DRAW <https://github.com/ericjang/draw/blob/master/draw.py#L73>`__
+    - `ericjang-DRAW <https://github.com/ericjang/draw/blob/master/draw.py#L73>`__
 
     """
     #     from tensorflow.python.framework import ops
@@ -84,6 +80,10 @@ def binary_cross_entropy(output, target, epsilon=1e-8, name='bce_loss'):
     with tf.name_scope(name):
         return tf.reduce_mean(tf.reduce_sum(-(target * tf.log(output + epsilon) + (1. - target) * tf.log(1. - output + epsilon)), axis=1))
 
+    # For brevity, let `x = output`, `z = target`.  The binary cross entropy loss is
+    #
+    #     loss(x, z) = - sum_i (x[i] * log(z[i]) + (1 - x[i]) * log(1 - z[i]))
+
 
 def mean_squared_error(output, target, is_mean=False, name="mean_squared_error"):
     """Return the TensorFlow expression of mean-square-error (L2) of two batch of data.
@@ -96,8 +96,8 @@ def mean_squared_error(output, target, is_mean=False, name="mean_squared_error")
         The target distribution, format the same with `output`.
     is_mean : boolean
         Whether compute the mean or sum for each example.
-        - If True, use ``tf.reduce_mean`` to compute the loss between one target and predict data.
-        - If False, use ``tf.reduce_sum`` (default).
+            - If True, use ``tf.reduce_mean`` to compute the loss between one target and predict data.
+            - If False, use ``tf.reduce_sum`` (default).
 
     References
     ------------
@@ -161,8 +161,8 @@ def absolute_difference_error(output, target, is_mean=False):
         The target distribution, format the same with `output`.
     is_mean : boolean
         Whether compute the mean or sum for each example.
-        - If True, use ``tf.reduce_mean`` to compute the loss between one target and predict data.
-        - If False, use ``tf.reduce_sum`` (default).
+            - If True, use ``tf.reduce_mean`` to compute the loss between one target and predict data.
+            - If False, use ``tf.reduce_sum`` (default).
 
     """
     with tf.name_scope("mean_squared_error_loss"):
@@ -203,10 +203,8 @@ def dice_coe(output, target, loss_type='jaccard', axis=[1, 2, 3], smooth=1e-5):
         All dimensions are reduced, default ``[1,2,3]``.
     smooth : float
         This small value will be added to the numerator and denominator.
-        If both output and target are empty, it makes sure dice is 1.
-        If either output or target are empty (all pixels are background), dice = ```smooth/(small_value + smooth)``,
-        then if smooth is very small, dice close to 0 (even the image values lower than the threshold),
-        so in this case, higher smooth can have a higher dice.
+            - If both output and target are empty, it makes sure dice is 1.
+            - If either output or target are empty (all pixels are background), dice = ```smooth/(small_value + smooth)``, then if smooth is very small, dice close to 0 (even the image values lower than the threshold), so in this case, higher smooth can have a higher dice.
 
     Examples
     ---------
@@ -359,8 +357,8 @@ def cross_entropy_seq(logits, target_seqs, batch_size=None):  #, batch_size=1, n
         The target sequence, 2D tensor `[batch_size, n_steps]`, if the number of step is dynamic, please use ``tl.cost.cross_entropy_seq_with_mask`` instead.
     batch_size : None or int.
         Whether to divide the cost by batch size.
-        - If integer, the return cost will be divided by `batch_size`.
-        - If None (default), the return cost will not be divided by anything.
+            - If integer, the return cost will be divided by `batch_size`.
+            - If None (default), the return cost will not be divided by anything.
 
     Examples
     --------
@@ -401,8 +399,8 @@ def cross_entropy_seq_with_mask(logits, target_seqs, input_mask, return_details=
         The mask to compute loss, it has the same size with `target_seqs`, normally 0 or 1.
     return_details : boolean
         Whether to return detailed losses.
-        - If False (default), only returns the loss.
-        - If True, returns the loss, losses, weights and targets (see source code).
+            - If False (default), only returns the loss.
+            - If True, returns the loss, losses, weights and targets (see source code).
 
     Examples
     --------
@@ -581,7 +579,7 @@ def lo(weights, name='lo_regularizer'):
 def maxnorm_regularizer(scale=1.0, scope=None):
     """Max-norm regularization returns a function that can be used to apply max-norm regularization to weights.
 
-    More about max-norm, see `<https://en.wikipedia.org/wiki/Matrix_norm#Max_norm>`__.
+    More about max-norm, see `wiki-max norm <https://en.wikipedia.org/wiki/Matrix_norm#Max_norm>`_.
     The implementation follows `TensorFlow contrib <https://github.com/tensorflow/tensorflow/blob/master/tensorflow/contrib/layers/python/layers/regularizers.py>`__.
 
     Parameters

tensorlayer/files.py

@@ -316,7 +316,7 @@ def load_matt_mahoney_text8_dataset(path='data'):
 
     Returns
     --------
-    word_list : list of str
+    list of str
         The raw text data e.g. [.... 'their', 'families', 'who', 'were', 'expelled', 'from', 'jerusalem', ...]
 
     Examples
@@ -439,13 +439,16 @@ def load_imdb_dataset(path='data', nb_words=None, skip_top=0, maxlen=None, test_
 def load_nietzsche_dataset(path='data'):
     """Load Nietzsche dataset.
 
-    Returns a string.
-
     Parameters
     ----------
     path : str
         The path that the data is downloaded to, defaults is ``data/nietzsche/``.
 
+    Returns
+    --------
+    str
+        The content.
+
     Examples
     --------
     >>> see tutorial_generate_text.py
@@ -544,8 +547,8 @@ def load_flickr25k_dataset(tag='sky', path="data", n_threads=50, printable=False
     ------------
     tag : str or None
         What images to return.
-        - If you want to get images with tag, use string like 'dog', 'red', see `Flickr Search <https://www.flickr.com/search/>`__.
-        - If you want to get all images, set to ``None``.
+            - If you want to get images with tag, use string like 'dog', 'red', see `Flickr Search <https://www.flickr.com/search/>`__.
+            - If you want to get all images, set to ``None``.
 
     path : str
         The path that the data is downloaded to, defaults is ``data/flickr25k/``.
@@ -612,8 +615,8 @@ def load_flickr1M_dataset(tag='sky', size=10, path="data", n_threads=50, printab
     ------------
     tag : str or None
         What images to return.
-        - If you want to get images with tag, use string like 'dog', 'red', see `Flickr Search <https://www.flickr.com/search/>`__.
-        - If you want to get all images, set to ``None``.
+            - If you want to get images with tag, use string like 'dog', 'red', see `Flickr Search <https://www.flickr.com/search/>`__.
+            - If you want to get all images, set to ``None``.
 
     size : int
         integer between 1 to 10. 1 means 100k images ... 5 means 500k images, 10 means all 1 million images. Default is 10.
@@ -1202,7 +1205,7 @@ def load_npz(path='', name='model.npz'):
 
     Returns
     --------
-    params : list of array
+    list of array
         A list of parameters in order.
 
     Examples
@@ -1247,7 +1250,7 @@ def assign_params(sess, params, network):
 
     Returns
     --------
-    ops : list of operations
+    list of operations
         A list of tf ops in order that assign params. Support sess.run(ops) manually.
 
     Examples
@@ -1281,7 +1284,8 @@ def load_and_assign_npz(sess=None, name=None, network=None):
 
     Returns
     --------
-    Returns False if faild to model is not exist.
+    False or network
+        Returns False, if the model is not exist.
 
     Examples
     --------
@@ -1646,7 +1650,8 @@ def exists_or_mkdir(path, verbose=True):
 
     Returns
     --------
-    True if folder exist, otherwise, returns False and create the folder
+    boolean
+        True if folder already exist, otherwise, returns False and create the folder.
 
     Examples
     --------
@@ -1683,7 +1688,8 @@ def maybe_download_and_extract(filename, working_directory, url_source, extract=
 
     Returns
     ----------
-    Filepath to dowloaded (uncompressed) file
+    str
+        File path of the dowloaded (uncompressed) file.
 
     Examples
     --------