update docs

docs/tutorial/callback.md

@@ -25,9 +25,7 @@ Therefore these features can be reused with one single line, as long as you are
 For example, these are the callbacks I used when training a ResNet:
 
 ```python
-TrainConfig(
-  # ...
-  callbacks=[
+callbacks=[
 	# save the model every epoch
 	ModelSaver(),
 	# backup the model with best validation error
@@ -39,7 +37,7 @@ TrainConfig(
 	# schedule the learning rate based on epoch number
 	ScheduledHyperParamSetter('learning_rate',
 														[(30, 1e-2), (60, 1e-3), (85, 1e-4), (95, 1e-5)]),
-    # can manually set the learning rate during training
+	# can manually change the learning rate through a file during training
 	HumanHyperParamSetter('learning_rate'),
 	# send validation error to my phone through pushbullet
 	SendStat('curl -u your_id_xxx: https://api.pushbullet.com/v2/pushes \\
@@ -50,8 +48,7 @@ TrainConfig(
 	GPUUtilizationTracker(),
 	# can pause the training and start a debug shell, to observe what's going on
 	InjectShell(shell='ipython')
-  ],
-  extra_callbacks=[    # these callbacks are enabled by default already
+] + [    # these callbacks are enabled by default already, though you can customize them
 	# maintain those moving average summaries already defined in the model (e.g. training loss, training error)
 	MovingAverageSummary(),
 	# draw a nice progress bar
@@ -60,23 +57,22 @@ TrainConfig(
 	MergeAllSummaries(),
 	# run ops in GraphKeys.UPDATE_OPS collection along with training, if any
 	RunUpdateOps(),
-  ],
-  monitors=[        # monitors are a special kind of callbacks. these are also enabled by default
+],
+monitors=[        # monitors are a special kind of callbacks. these are also enabled by default
 	# write everything to tensorboard
 	TFEventWriter(),
 	# write all scalar data to a json file, for easy parsing
 	JSONWriter(),
 	# print all scalar data every epoch (can be configured differently)
 	ScalarPrinter(),
-  ]
-)
+]
 ```
 
 Notice that callbacks cover every detail of training, ranging from graph operations to the progress bar.
 This means you can customize every part of the training to your preference, e.g. display something
 different in the progress bar, evaluating part of the summaries at a different frequency, etc.
 These features may not be always useful, but think about how messy the main loop would look like if you
-were to write the logic together with the loops, and how easy your life will be if you could enable
+were to write these logic together with the loops, and how easy your life will be if you could enable
 these features with one line when you need them.
 
 See [Write a callback](http://tensorpack.readthedocs.io/en/latest/tutorial/extend/callback.html)

docs/tutorial/extend/trainer.md

 
 ## Write a Trainer
 
-**These contents are subject to change in later versions soon**.
-
-The existing trainers should be enough for single-cost optimization tasks.
-If you want to do something different during training, first consider writing it as a callback,
+The existing trainers should be enough for single-tower single-cost optimization tasks.
+If you just want to do some extra work during training, first consider writing it as a callback,
 or write an issue to see if there is a better solution than creating new trainers.
-If your task is fundamentally different from single-cost optimization, you may need to write a trainer.
-
-Trainers are recently being redesigned, the they best wayt to customize the trainer will likely to change.
-We leave the tutorial empty for now.
-
-<!--
-   -Trainers just run __some__ iterations, so there is no limit in where the data come from or what to do in an iteration.
-   -The existing common trainers all implement two things:
-   -1. Setup the graph and input pipeline, using the given `TrainConfig`.
-   -2. Minimize `model.cost` in each iteration.
-   -
-   -But you can customize it by using the base `Trainer` class.
-   -
-   -* To customize the graph:
-   -
-   -  Add any tensors and ops you like, either before creating the trainer or inside `Trainer.__init__`.
-	 -  In this case you don't need to set model/data in `TrainConfig` any more.
-   -
-   -* Two ways to customize the iteration:
-   -
-	 -  1. Set `Trainer.train_op`. This op will be run by default.
-	 -  2. Subclass `Trainer` and override the `run_step()` method. This way you can do something more than running an op.
-   -
-   -There are several different [GAN trainers](../../examples/GAN/GAN.py) for reference.
-   -The implementation of [SimpleTrainer](../../tensorpack/train/simple.py) may also be helpful.
-	 -->
+If your task is fundamentally different from single-cost optimization, you will need to write a trainer.
+
+
+Trainers just run __some__ iterations, so there is no limit in where the data come from or what to do in an iteration.
+The existing common trainers all implement two things:
+1. Setup the graph and input pipeline, using the given `InputSource` and `get_cost_fn`.
+2. Minimize `model.cost` in each iteration.
+
+But you can customize it by using or inheriting the base `Trainer` class.
+You will need to define two things for a new Trainer:
+
+1. What is the graph.
+	Add any tensors and ops you like, either before creating the trainer or inside `Trainer.__init__`.
+
+* What is the iteration. There are 2 ways to define an iteration:
+	1. Set `Trainer.train_op`. This op will be run by default.
+	2. Subclass `Trainer` and override the `run_step()` method. This way you can do something more than running an op.
+
+There are several different [GAN trainers](../../examples/GAN/GAN.py) for reference.

tensorpack/train/interface.py

@@ -8,7 +8,7 @@ from ..input_source import (
     InputSource, FeedInput, QueueInput, StagingInput, DummyConstantInput)
 
 from ..trainv1.config import TrainConfig
-from .base import SingleCostTrainer
+from .tower import SingleCostTrainer
 from .trainers import SimpleTrainer, DistributedTrainerReplicated
 
 __all__ = ['launch_train_with_config', 'apply_default_prefetch']