update docs

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

@@ -11,9 +11,9 @@ __PLEASE DO NOT DELETE THIS TEMPLATE, FILL IT__:
 
 (1) **If you're using examples, what's the command you run:**
 
-(2) **If you're using examples, have you made any changes to the examples? Paste them here:**
+(2) **If you're using examples, have you made any changes to the examples? Paste `git diff` here:**
 
-(3) **If not using examples, tell us what you did here:**
+(3) **If not using examples, tell us what you did:**
 
 Note that we may not be able to investigate it if there is no reproducible code.
 It's always better to paste what you did instead of describing them.
@@ -24,15 +24,19 @@ It's always better to paste what you did instead of describing them.
 
 It's always better to paste what you observed instead of describing them.
 
-A part of logs is sometimes enough, but it's always better to paste as much as possible.
+It's always better to paste **as much as possible**, although sometimes a partial log is OK.
 
-You can run a command with `CMD 2>&1 | tee logs.txt` to save all stdout & stderr logs to one file.
+Tensorpack typically saves stdout to its training log.
+If stderr is relevant, you can run a command with `CMD 2>&1 | tee logs.txt`
+to save both stdout and stderr to one file.
 
 (2) **Other observations, if any:**
 For example, CPU/GPU utilization, output images, tensorboard curves, if relevant to your issue.
 
 ### 3. What you expected, if not obvious.
 
+If you expect higher speed, please first read http://tensorpack.readthedocs.io/en/latest/tutorial/performance-tuning.html
+
 If you expect higher accuracy, only in one of the two conditions can we help with it:
 (1) You're unable to match the accuracy documented in tensorpack examples.
 (2) It appears to be a tensorpack bug.
@@ -50,4 +54,5 @@ not our responsibility to figure out.
     using an IDE or jupyter notebook), please retry under a normal command line shell. 
   + Hardware information, e.g. number of GPUs used.
 
-About efficiency issues, PLEASE first read http://tensorpack.readthedocs.io/en/latest/tutorial/performance-tuning.html
+Feel free to add extra information related to your issue, but
+please try to provide the above information __accurately__ to save effort in the investigation.

docs/README.md

@@ -14,3 +14,7 @@ will build the docs in `build/html`.
 
 1. `pip install doc2dash`
 2. `make docset` produces `tensorpack.docset`.
+
+### Subscribe to docset updates in Dash/Zeal:
+
+Add this feed in Dash/Zeal: `https://github.com/tensorpack/tensorpack/raw/master/docs/tensorpack.xml`.

docs/tensorpack.xml

+
+<entry>
+  <version>0.9.0.1</version>
+  <url>https://github.com/tensorpack/tensorpack/releases/download/doc-v0.9.0.1/tensorpack.docset.tgz</url>
+</entry>

examples/ImageNetModels/imagenet_utils.py

@@ -387,7 +387,7 @@ class ImageNetModel(ModelDesc):
             nclass = logits.shape[-1]
             loss = tf.losses.softmax_cross_entropy(
                 tf.one_hot(label, nclass),
-                logits, label_smoothing=label_smoothing)
+                logits, label_smoothing=label_smoothing, reduction=tf.losses.Reduction.NONE)
         loss = tf.reduce_mean(loss, name='xentropy-loss')
 
         def prediction_incorrect(logits, label, topk=1, name='incorrect_vector'):

tensorpack/contrib/keras.py

@@ -279,7 +279,7 @@ class KerasModel(object):
             validation_data (DataFlow or InputSource): to be used for inference.
                 The inference callback is added as the first in the callback list.
                 If you need to use it in a different order, please write it in the callback list manually.
-            kwargs: same as `self.trainer.train_with_defaults`.
+            kwargs: same arguments as :meth:`Trainer.train_with_defaults`.
         """
         callbacks = kwargs.pop('callbacks', [])
         if validation_data is not None:

tensorpack/predict/base.py

@@ -133,7 +133,19 @@ class OnlinePredictor(PredictorBase):
 
 class OfflinePredictor(OnlinePredictor):
     """ A predictor built from a given config.
-        A single-tower model will be built without any prefix. """
+        A single-tower model will be built without any prefix.
+
+        Example:
+
+        .. code-block:: python
+
+            config = PredictConfig(model=my_model,
+                                   inputs_names=['image'],
+                                   output_names=['linear/output', 'prediction'])
+            predictor = OfflinePredictor(config)
+            batch_image = np.random.rand(1, 100, 100, 3)
+            batch_output, batch_prediction = predictor(batch_image)
+    """
 
     def __init__(self, config):
         """

tensorpack/predict/config.py

@@ -33,6 +33,14 @@ class PredictConfig(object):
         They are needed to construct the graph.
         You'll also have to set `output_names` as it does not have a default.
 
+        Example:
+
+        .. code-block:: python
+
+            config = PredictConfig(model=my_model,
+                                   inputs_names=['image'],
+                                   output_names=['linear/output', 'prediction'])
+
         Args:
             model (ModelDescBase): to be used to obtain inputs_desc and tower_func.
             tower_func: a callable which takes input tensors (by positional args) and construct a tower.

tensorpack/train/config.py

@@ -178,6 +178,12 @@ class AutoResumeTrainConfig(TrainConfig):
 
     You can choose to let the above two option to either overwrite or
     not overwrite user-provided arguments, as explained below.
+
+    Note that the functionality requires the logging directory to obtain
+    necessary information from a previous run.
+    In some cases (e.g. when using Horovod), the directory is not
+    available or different for different workers and this class may not function
+    properly.
     """
     def __init__(self, always_resume=True, **kwargs):
         """