update docs; bump version

.github/ISSUE_TEMPLATE/unexpected-problems---bugs.md

@@ -20,6 +20,6 @@ __PLEASE ALWAYS INCLUDE__:
   + TF version: `python -c 'import tensorflow as tf; print(tf.GIT_VERSION, tf.VERSION)'`.
   + Tensorpack version: `python -c 'import tensorpack; print(tensorpack.__version__)'`.
       You can install Tensorpack master by `pip install -U git+https://github.com/ppwwyyxx/tensorpack.git`.:
-  + Hardware information, if relevant.
+  + Hardware information, e.g. number of GPUs used.
 
 About efficiency issues, PLEASE first read http://tensorpack.readthedocs.io/en/latest/tutorial/performance-tuning.html

.github/ISSUE_TEMPLATE/using-understanding-tensorpack.md

@@ -4,6 +4,9 @@ about: More general questions about Tensorpack.
 
 ---
 
++ If you did something specific and it failed, please use the "Unexpected Problems /
+  Bugs" category.
+
 + Your question is probably answered in [tutorials](http://tensorpack.readthedocs.io/en/latest/tutorial/index.html#user-tutorials). Read it first.
 
 + We answer "HOW to do X with Tensorpack" for a well-defined X.

docs/modules/callbacks.rst

 tensorpack.callbacks package
 ============================
 
-__Everything__ other than the training iterations happen in the callbacks.
+**Everything** other than the training iterations happen in the callbacks.
 Most of the fancy things you want to do will probably end up here.
 See relevant tutorials: :doc:`../tutorial/callback`.
 

docs/modules/utils.rst

@@ -52,7 +52,7 @@ tensorpack.utils.serialize module
     :show-inheritance:
 
 tensorpack.utils.compatible_serialize module
----------------------------------
+--------------------------------------------
 
 .. automodule:: tensorpack.utils.compatible_serialize
     :members:

docs/tutorial/extend/callback.md

@@ -126,3 +126,8 @@ You can overwrite any of the following methods to define a new callback:
   or [EnableCallbackIf](../../modules/callbacks.html#tensorpack.callbacks.EnableCallbackIf).
 	Of course you also have the freedom to implement "what to do" and "when to do" altogether.
 
+
+### Examples
+
+Check source code of the [existing tensorpack callbacks](../../modules/callbacks.html). 
+Or grep 'Callback' in tensorpack examples for those implemented as extensions.

examples/FasterRCNN/config.py

@@ -22,6 +22,11 @@ class AttrDict():
         setattr(self, name, ret)
         return ret
 
+    def __setattr__(self, name, value):
+        if self._freezed and name not in self.__dict__:
+            raise AttributeError("Cannot create new attribute!")
+        super().__setattr__(name, value)
+
     def __str__(self):
         return pprint.pformat(self.to_dict(), indent=1)
 
@@ -51,6 +56,9 @@ class AttrDict():
 
     def freeze(self):
         self._freezed = True
+        for v in self.__dict__.values():
+            if isinstance(v, AttrDict):
+                v.freeze()
 
     # avoid silent bugs
     def __eq__(self, _):
@@ -229,6 +237,7 @@ def finalize_configs(is_training):
         else:
             assert 'OMPI_COMM_WORLD_SIZE' not in os.environ
             ngpu = get_num_gpu()
+        assert ngpu > 0, "Has to run with GPU!"
         assert ngpu % 8 == 0 or 8 % ngpu == 0, ngpu
         if _C.TRAIN.NUM_GPUS is None:
             _C.TRAIN.NUM_GPUS = ngpu

tensorpack/callbacks/inference.py

@@ -117,7 +117,7 @@ class ScalarStats(Inferencer):
 
 class ClassificationError(Inferencer):
     """
-    Compute __true__ classification error in batch mode, from a ``wrong`` tensor.
+    Compute **true** classification error in batch mode, from a ``wrong`` tensor.
 
     The ``wrong`` tensor is supposed to be an binary vector containing
     whether each sample in the batch is *incorrectly* classified.

tensorpack/callbacks/misc.py

@@ -42,7 +42,7 @@ class InjectShell(Callback):
 
     Example:
 
-    .. code-block:: python
+    .. code-block:: none
 
         callbacks=[InjectShell('/path/to/pause-training.tmp'), ...]
 

tensorpack/callbacks/monitor.py

@@ -16,6 +16,7 @@ import re
 import tensorflow as tf
 from ..utils import logger
 from ..tfutils.summary import create_scalar_summary, create_image_summary
+from ..utils.develop import HIDE_DOC
 from .base import Callback
 
 __all__ = ['TrainingMonitor', 'Monitors',
@@ -242,9 +243,11 @@ class TFEventWriter(TrainingMonitor):
             self._logdir, graph=tf.get_default_graph(),
             max_queue=self._max_queue, flush_secs=self._flush_secs)
 
+    @HIDE_DOC
     def process_summary(self, summary):
         self._writer.add_summary(summary, self.global_step)
 
+    @HIDE_DOC
     def process_event(self, evt):
         self._writer.add_event(evt)
 
@@ -345,6 +348,7 @@ class JSONWriter(TrainingMonitor):
     def _trigger_epoch(self):
         self._trigger()
 
+    @HIDE_DOC
     def process_scalar(self, name, val):
         self._stat_now[name] = val
 
@@ -417,6 +421,7 @@ class ScalarPrinter(TrainingMonitor):
         if self._enable_epoch:
             self._trigger()
 
+    @HIDE_DOC
     def process_scalar(self, name, val):
         self._dic[name] = float(val)
 
@@ -444,6 +449,7 @@ class ScalarHistory(TrainingMonitor):
     def __init__(self):
         self._dic = defaultdict(list)
 
+    @HIDE_DOC
     def process_scalar(self, name, val):
         self._dic[name].append(float(val))
 
@@ -488,6 +494,7 @@ class SendMonitorData(TrainingMonitor):
         self.names = names
         self.dic = {}
 
+    @HIDE_DOC
     def process_scalar(self, name, val):
         if name in self.names:
             self.dic[name] = val

tensorpack/callbacks/summary.py

@@ -114,9 +114,6 @@ def MergeAllSummaries(period=0, run_alone=False, key=tf.GraphKeys.SUMMARIES):
             depend on inputs.
         key (str): the collection of summary tensors. Same as in `tf.summary.merge_all`.
             Default is ``tf.GraphKeys.SUMMARIES``
-
-    Returns:
-        a Callback.
     """
     period = int(period)
     if run_alone:

tensorpack/input_source/input_source.py

@@ -623,7 +623,9 @@ class StagingInput(FeedfreeInput):
 
                 # TODO tensorflow/benchmarks use static shapes here,
                 # though it doesn't seem to help. We can use it when it's known.
-                stage = StagingArea(dtypes, shapes=None)
+                # Setting capacity to 1 to potentially save some memory, because we should
+                # expect the consumers to run slower than the producer.
+                stage = StagingArea(dtypes, shapes=None, capacity=1)
 
             # put & get automatically inherit the name scope from the area
             self._stage_ops.append(stage.put(inputs))

tensorpack/libinfo.py

@@ -54,4 +54,4 @@ except ImportError:
 
 # This line has to be the last line of the file.
 # setup.py will use it to determine the version
-__version__ = '0.8.8'
+__version__ = '0.8.9'

tensorpack/models/tflayer.py

@@ -9,6 +9,8 @@ from ..utils.argtools import get_data_format
 from ..tfutils.common import get_tf_version_tuple
 from ..tfutils.varreplace import custom_getter_scope
 
+__all__ = []
+
 
 def map_common_tfargs(kwargs):
     df = kwargs.pop('data_format', None)

tensorpack/tfutils/sesscreate.py

@@ -34,7 +34,7 @@ class NewSessionCreator(tf.train.ChiefSessionCreator):
         else:
             self.user_provided_config = True
             logger.warn(
-                "Some options in custom session config may not work due to TF \
+                "User-provided custom session config may not work due to TF \
 bugs. See https://github.com/tensorpack/tensorpack/issues/497 for workarounds.")
 
         self.config = config

tensorpack/utils/concurrency.py

@@ -251,15 +251,15 @@ def subproc_call(cmd, timeout=None):
             shell=True, timeout=timeout)
         return output, 0
     except subprocess.TimeoutExpired as e:
-        logger.warn("Command timeout!")
+        logger.warn("Command '{}' timeout!".format(cmd))
         logger.warn(e.output.decode('utf-8'))
         return e.output, -1
     except subprocess.CalledProcessError as e:
-        logger.warn("Command failed: {}".format(e.returncode))
+        logger.warn("Command '{}' failed, return code={}".format(cmd, e.returncode))
         logger.warn(e.output.decode('utf-8'))
         return e.output, e.returncode
     except Exception:
-        logger.warn("Command failed to run: {}".format(cmd))
+        logger.warn("Command '{}' failed to run.".format(cmd))
         return "", -2
 
 

tensorpack/utils/develop.py

@@ -15,6 +15,8 @@ import six
 
 from . import logger
 
+__all__ = []
+
 
 def create_dummy_class(klass, dependency):
     """