tutorials

docs/requirements.txt

@@ -3,5 +3,7 @@ numpy
 tqdm
 decorator
 tensorflow
-Sphinx==1.5.1
+Sphinx>=1.5.1
 recommonmark==0.4.0
+sphinx_rtd_theme
+mock

docs/tutorial/callback.md

 
-# Callback
+# Callbacks
 
 Apart from the actual training iterations that minimizes the cost,
 you almost surely would like to do something else during training.
@@ -40,12 +40,12 @@ TrainConfig(
                'val-error-top1')
   ],
   extra_callbacks=[    # these callbacks are enabled by default already
-    # maintain and summarize moving average of some tensors (e.g. training loss, training error)
+    # maintain and summarize moving average of some tensors defined in the model (e.g. training loss, training error)
     MovingAverageSummary(),
     # draw a nice progress bar
     ProgressBar(),
-		# run `tf.summary.merge_all` and save results every epoch
-		MergeAllSummaries(),
+    # run `tf.summary.merge_all` and save results every epoch
+    MergeAllSummaries(),
   ]
 )
 ```

docs/tutorial/dataflow.md

@@ -38,11 +38,16 @@ without worrying about adding operators to TensorFlow.
 In the mean time, thanks to the prefetching, it can still run fast enough for
 tasks as large as ImageNet training.
 
+Unless you're working with standard data types (image folders, LMDB, etc),
+you would usually want to write your own DataFlow.
+See [another tutorial](http://tensorpack.readthedocs.io/en/latest/tutorial/extend/dataflow.html)
+for details.
+
 <!--
    - TODO mention RL, distributed data, and zmq operator in the future.
 	 -->
 
-### Reuse in other frameworks
+### Use DataFlow outside Tensorpack
 Another good thing about DataFlow is that it is independent of
 tensorpack internals. You can just use it as an efficient data processing pipeline,
 and plug it into other frameworks.
@@ -50,14 +55,10 @@ and plug it into other frameworks.
 To use a DataFlow independently, you'll need to call `reset_state()` first to initialize it,
 and then use the generator however you want:
 ```python
-df = get_some_df()
+df = SomeDataFlow()
+
 df.reset_state()
 generator = df.get_data()
 for dp in generator:
 	# dp is now a list. do whatever
 ```
-
-Unless you're working with standard data types (image folders, LMDB, etc),
-you would usually want to write your own DataFlow.
-See [another tutorial](http://tensorpack.readthedocs.io/en/latest/tutorial/extend/dataflow.html)
-for details.

docs/tutorial/glance.md

-
-## A High-Level Glance
-
-TBD.
-
-You're recommended to glance at the [examples](../examples) to get a feeling about the
-structure.

docs/tutorial/index.rst

@@ -2,9 +2,31 @@
 Tutorials
 ---------------------
 
-To be completed.
+A High Level Glance
+====================
 
-user tutorials
+* :doc:`dataflow` is a set of extensible tools to help you define your input data with ease and speed.
+
+  It provides a uniformed interface so data processing modules can be chained together.
+  It allows you to load and process your data in pure Python and accelerate it by multiprocess prefetch.
+  See also :doc:`tf-queue`  and :doc:`efficient-dataflow` for more details about efficiency of data
+  processing.
+
+* You can use any TF-based symbolic function library to define a model in tensorpack.
+  :doc:`model` introduces where and how you define the model for tensorpack trainers to use,
+  and how you can benefit from the symbolic function library in tensorpack.
+
+Both DataFlow and models can be used outside tensorpack, as just a data processing library and a symbolic
+function library. Tensopack trainers integrate these two components and add more convenient features.
+
+* tensorpack :doc:`trainer` manages the training loops for you so you won't have to worry about
+  details such as multi-GPU training. At the same time it keeps the power of customization to you
+  through callbacks.
+
+* :doc:`callback` are like ``tf.train.SessionRunHook`` plugins, or extensions. During training,
+  everything you want to do other than the main iterations can be defined through callbacks.
+
+User Tutorials
 ========================
 
 .. toctree::
@@ -17,7 +39,7 @@ user tutorials
   trainer
   callback
 
-extend tensorpack
+Extend Tensorpack
 =================
 
 .. toctree::

docs/tutorial/model.md

@@ -28,7 +28,7 @@ such as conv/deconv, fc, batch normalization, pooling layers, and some custom lo
 Using the tensorpack implementations, you can also benefit from `argscope` and `LinearWrap` to
 simplify the code.
 
-## argscope and LinearWrap
+### argscope and LinearWrap
 `argscope` gives you a context with default arguments.
 `LinearWrap` allows you to simplify "linear structure" models by
 adding the layers one by one.
@@ -59,3 +59,15 @@ l = tf.multiply(l, 0.5)
 l = func(l, *args, **kwargs)
 l = FullyConnected('fc1', l, 10, nl=tf.identity)
 ```
+
+### Use Models outside Tensorpack
+
+You can use the tensorpack models alone as a simple symbolic function library, and write your own
+training code instead of using tensorpack trainers.
+
+To do this, just enter a [TowerContext](http://tensorpack.readthedocs.io/en/latest/modules/tfutils.html#tensorpack.tfutils.TowerContext)
+when you define your model:
+```python
+with TowerContext('', is_training=True):
+	# call any tensorpack symbolic functions
+```