add some docs

examples/ResNet/README.md

@@ -20,10 +20,11 @@ Models can be [downloaded here](http://models.tensorpack.com/ResNet/).
 | ResNet101      		 |     6.04%   |      21.95% |
 | ResNet152      		 |     5.78%   |      21.51% |
 
-To train, just run:
+To train, first decompress ImageNet data into [this structure](http://tensorpack.readthedocs.io/en/latest/modules/dataflow.dataset.html#tensorpack.dataflow.dataset.ILSVRC12), then:
 ```bash
 ./imagenet-resnet.py --data /path/to/original/ILSVRC --gpu 0,1,2,3 -d 50 [--mode resnet/preact/se]
 ```
+
 You should be able to see good GPU utilization (95%~99%), if your data is fast enough.
 The default data pipeline is probably OK for most systems.
 See the [tutorial](http://tensorpack.readthedocs.io/en/latest/tutorial/efficient-dataflow.html) on other options to speed up your data.

tensorpack/dataflow/dataset/ilsvrc.py

@@ -173,17 +173,17 @@ class ILSVRC12(ILSVRC12Files):
                  shuffle=None, dir_structure=None):
         """
         Args:
-            dir (str): A directory containing a subdir named ``name``, where the
-                original ``ILSVRC12_img_{name}.tar`` gets decompressed.
-            name (str): 'train' or 'val' or 'test'.
+            dir (str): A directory containing a subdir named ``name``,
+                containing the images in a structure described below.
+            name (str): One of 'train' or 'val' or 'test'.
             shuffle (bool): shuffle the dataset.
                 Defaults to True if name=='train'.
-            dir_structure (str): The directory structure of 'val' and 'test' directory.
-                'original' means the original decompressed
-                directory, which only has list of image files (as below).
-                If set to 'train', it expects the same two-level
-                directory structure simlar to 'train/'.
+            dir_structure (str): One of 'original' or 'train'.
+                The directory structure for the 'val' directory.
+                'original' means the original decompressed directory, which only has list of image files (as below).
+                If set to 'train', it expects the same two-level directory structure simlar to 'dir/train/'.
                 By default, it tries to automatically detect the structure.
+                You probably do not need to care about this option because 'original' is what people usually have.
 
         Examples:
 
@@ -213,6 +213,25 @@ class ILSVRC12(ILSVRC12Files):
             mkdir test && tar xvf ILSVRC12_img_test.tar -C test
             mkdir train && tar xvf ILSVRC12_img_train.tar -C train && cd train
             find -type f -name '*.tar' | parallel -P 10 'echo {} && mkdir -p {/.} && tar xf {} -C {/.}'
+
+        When `dir_structure=='train'`, `dir` should have the following structure:
+
+        .. code-block:: none
+
+            dir/
+              train/
+                n02134418/
+                  n02134418_198.JPEG
+                  ...
+                ...
+              val/
+                n01440764/
+                  ILSVRC2012_val_00000293.JPEG
+                  ...
+                ...
+              test/
+                ILSVRC2012_test_00000001.JPEG
+                ...
         """
         super(ILSVRC12, self).__init__(
             dir, name, meta_dir, shuffle, dir_structure)

tensorpack/models/regularize.py

@@ -14,8 +14,8 @@ __all__ = ['regularize_cost', 'l2_regularizer', 'l1_regularizer', 'Dropout']
 
 
 @graph_memoized
-def _log_regularizer(name):
-    logger.info("Apply regularizer for {}".format(name))
+def _log_once(msg):
+    logger.info(msg)
 
 
 l2_regularizer = tf.contrib.layers.l2_regularizer
@@ -56,7 +56,7 @@ def regularize_cost(regex, func, name='regularize_cost'):
     else:
         params = tf.trainable_variables()
 
-    to_regularize = []
+    names = []
 
     with tf.name_scope(name + '_internals'):
         costs = []
@@ -64,7 +64,7 @@ def regularize_cost(regex, func, name='regularize_cost'):
             para_name = p.op.name
             if re.search(regex, para_name):
                 costs.append(func(p))
-                to_regularize.append(p.name)
+                names.append(p.name)
         if not costs:
             return tf.constant(0, dtype=tf.float32, name='empty_' + name)
 
@@ -77,9 +77,9 @@ def regularize_cost(regex, func, name='regularize_cost'):
             if name.startswith(prefix):
                 return name[prefixlen:]
             return name
-        to_regularize = list(map(f, to_regularize))
-    to_print = ', '.join(to_regularize)
-    _log_regularizer(to_print)
+        names = list(map(f, names))
+    logger.info("regularize_cost() found {} tensors.".format(len(names)))
+    _log_once("Applying regularizer for {}".format(', '.join(names)))
 
     return tf.add_n(costs, name=name)
 
@@ -106,7 +106,7 @@ def regularize_cost_from_collection(name='regularize_cost'):
     else:
         losses = tf.get_collection(tf.GraphKeys.REGULARIZATION_LOSSES)
     if len(losses) > 0:
-        logger.info("Add REGULARIZATION_LOSSES of {} tensors on the total cost.".format(len(losses)))
+        logger.info("regularize_cost_from_collection() found {} tensors in REGULARIZATION_LOSSES.".format(len(losses)))
         reg_loss = tf.add_n(losses, name=name)
         return reg_loss
     else: