reorganize docs

docs/conf.py

@@ -13,6 +13,7 @@
 # serve to show the default.
 
 import sys, os, re
+import mock
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -20,19 +21,6 @@ import sys, os, re
 sys.path.insert(0, os.path.abspath('../'))
 os.environ['TENSORPACK_DOC_BUILDING'] = '1'
 
-import mock
-
-#class AttrMock(mock.Mock):
-    #def __init__(self, name):
-        #self.__dict__['name'] = name
-    #def __getattr__(self, attr):
-        #return AttrMock(self.__dict__['name'] + "." + attr)
-    #def __str__(self):
-        #return self.__dict__['name']
-    #def __call__(self, *args, **kwargs):
-        #return self.__dict__['name'] + '(' + \
-                #', '.join(map(str, args)) + ', ' \
-                #+ ', '.join(["{}={}".format(k,v) for k,v in kwargs.items()]) + ')'
 
 MOCK_MODULES = ['scipy',
                 'tensorflow', 'tensorflow.contrib',
@@ -47,18 +35,17 @@ MOCK_MODULES = ['scipy',
                 'scipy.misc', 'h5py', 'nltk',
                 'cv2', 'scipy.io', 'dill', 'zmq', 'subprocess32', 'lmdb', 'tornado.concurrent',
                 'tornado', 'msgpack', 'msgpack_numpy', 'ale_python_interface',
-                'sklearn']
+                'sklearn', 'functools32']
 for mod_name in MOCK_MODULES:
     sys.modules[mod_name] = mock.Mock(name=mod_name)
 sys.modules['tensorflow'].__version__ = '0.12.0'
 
 import tensorpack
-from tensorpack.models import *
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.4'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -66,26 +53,33 @@ from tensorpack.models import *
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
-    #'sphinx.ext.coverage',
+    # 'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
 ]
+
+# -- Configurations for plugins ------------
 napoleon_google_docstring = True
 napoleon_include_init_with_doc = True
 napoleon_include_special_with_doc = True
 napoleon_numpy_docstring = False
 napoleon_use_rtype = False
 
+intersphinx_timeout = 0.1
+intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None)}
+# -------------------------
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
+# to support markdown
 from recommonmark.parser import CommonMarkParser
 source_parsers = {
     '.md': CommonMarkParser,
 }
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
 source_suffix = ['.rst', '.md']
 
 # The encoding of source files.
@@ -96,7 +90,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'tensorpack'
-copyright = u'2016, Yuxin Wu'
+copyright = u'2015 - 2017, Yuxin Wu'
 author = u'Yuxin Wu'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -104,9 +98,9 @@ author = u'Yuxin Wu'
 # built documents.
 #
 # The short X.Y version.
-version = u'0.1'
+version = u'0.2'
 # The full version, including alpha/beta/rc tags.
-release = u'0.1'
+release = u'0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -130,27 +124,28 @@ exclude_patterns = ['_build']
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#add_module_names = True
+add_module_names = True
+# TODO use module name, but remove `tensorpack.` ?
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
-#show_authors = False
+show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+modindex_common_prefix = ['tensorpack.']
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
+keep_warnings = False
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+todo_include_todos = True
 
 
 # -- Options for HTML output ----------------------------------------------
@@ -197,7 +192,7 @@ html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -211,22 +206,22 @@ html_static_path = ['_static']
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_domain_indices = True
+html_domain_indices = True
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
-#html_split_index = False
+html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+html_show_copyright = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
@@ -240,7 +235,7 @@ html_static_path = ['_static']
 # Sphinx supports the following languages:
 #   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
 #   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
-#html_search_language = 'en'
+html_search_language = 'en'
 
 # A dictionary with options for the search language support, empty by default.
 # Now only 'ja' uses this config value
@@ -273,8 +268,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'tensorpack.tex', u'tensorpack Documentation',
-     u'Yuxin Wu', 'manual'),
+    (master_doc, 'tensorpack.tex', u'tensorpack documentation',
+     author, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -303,7 +298,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'tensorpack', u'tensorpack Documentation',
+    (master_doc, 'tensorpack', u'tensorpack documentation',
      [author], 1)
 ]
 
@@ -317,7 +312,7 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'tensorpack', u'tensorpack Documentation',
+    (master_doc, 'tensorpack', u'tensorpack documentation',
      author, 'tensorpack', 'One line description of project.',
      'Miscellaneous'),
 ]
@@ -334,9 +329,7 @@ texinfo_documents = [
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
-
-intersphinx_timeout = 0.1
-intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None)}
+suppress_warnings = ['image.nonlocal_uri']
 
 def process_signature(app, what, name, obj, options, signature,
             return_annotation):
@@ -353,7 +346,7 @@ def setup(app):
     app.add_config_value(
         'recommonmark_config',
         {'url_resolver': lambda url: \
-         "https://github.com/ppwwyyxx/tensorpack/blob/master/tensorpack/" + url,
+         "https://github.com/ppwwyyxx/tensorpack/blob/master/" + url,
          'auto_toc_tree_section': 'Contents',
          'enable_math': True,
          'enable_inline_math': True,

docs/index.rst

-.. tensorpack documentation master file, created by
-   sphinx-quickstart on Sun Mar 27 01:41:24 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to tensorpack
+Welcome to tensorpack!
 ======================================
 
-Tensorpack is in early development.
-
-Contents:
+tensorpack is in early development.
 
 .. toctree::
-   :maxdepth: 2
-
-   user/dataflow
-   user/models
-
-.. toctree::
-  :maxdepth: 1
-
-
-  modules/tensorpack.models
-  modules/tensorpack.dataflow
-  modules/tensorpack.callbacks
-  modules/tensorpack.train
-  modules/tensorpack.utils
-  modules/tensorpack.tfutils
-  modules/tensorpack.predict
-  modules/tensorpack.RL
+  :maxdepth: 2
 
+  user/tutorials
+  modules/index
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/update.sh

@@ -10,4 +10,4 @@ cd "$PROG_DIR"
 make clean
 #sphinx-apidoc -o modules ../tensorpack -f -d 10
 make html
-xdotool windowactivate --sync $(xdotool search --desktop 0 Chromium) key F5
+#xdotool windowactivate --sync $(xdotool search --desktop 0 Chromium) key F5

docs/user/dataflow.md

 
-## Dataflow
+# Dataflow
 
 Dataflow uses Python generator to produce data.
 
-A Dataflow has to implement the `get_data()` generator method, which generates a `datapoint` when called.
-A datapoint must be a list of picklable Python object, each is called a `component` of the datapoint.
-For example to train on MNIST dataset, you can define a Dataflow that produces datapoints of shape `[(BATCH, 28, 28), (BATCH,)]`.
+A Dataflow has to implement the `get_data()` generator method, which yields `datapoints` when called.
+A datapoint must be a list of Python object, each is called a `component` of the datapoint.
+For example, to train on MNIST dataset, you can define a Dataflow that produces datapoints of shape `[(BATCH, 28, 28), (BATCH,)]`.
 
 Then, multiple Dataflows can be composed together to build a complex data-preprocessing pipeline,
 including __reading from disk, batching, augmentations, prefetching__, etc. These components written in Python

tensorpack/callbacks/param.py

@@ -220,10 +220,9 @@ class ScheduledHyperParamSetter(HyperParamSetter):
         """
         Args:
             param: same as in :class:`HyperParamSetter`.
-            schedule(list): with the format ``[(epoch1, val1), (epoch2, val2),
-                (epoch3, val3), ...]``.
+            schedule (list): with the format ``[(epoch1, val1), (epoch2, val2), (epoch3, val3)]``.
                 Each ``(ep, val)`` pair means to set the param
-                to "val" after the `ep`th epoch.
+                to "val" after the `ep` th epoch.
                 If ep == 0, the value will be set before training.
             interp: None: no interpolation. 'linear': linear interpolation
 

tensorpack/dataflow/imgaug/imgproc.py

@@ -144,7 +144,7 @@ class Clip(ImageAugmentor):
 class Saturation(ImageAugmentor):
     """ Randomly adjust saturation.
         Follows the implementation in `fb.resnet.torch
-        <https://github.com/facebook/fb.resnet.torch/blob/master/datasets/transforms.lua#L218>`_
+        <https://github.com/facebook/fb.resnet.torch/blob/master/datasets/transforms.lua#L218>`__.
     """
 
     def __init__(self, alpha=0.4):
@@ -169,7 +169,7 @@ class Lighting(ImageAugmentor):
         `ImageNet Classification with Deep Convolutional Neural Networks
         <https://papers.nips.cc/paper/4824-imagenet-classification-with-deep-convolutional-neural-networks.pdf>`_.
         The implementation follows `fb.resnet.torch
-        <https://github.com/facebook/fb.resnet.torch/blob/master/datasets/transforms.lua#L184>`_.
+        <https://github.com/facebook/fb.resnet.torch/blob/master/datasets/transforms.lua#L184>`__.
     """
 
     def __init__(self, std, eigval, eigvec):