[Doc] faq & env (#263)

* faq & env

* add update version script; 0.0.1 -> 0.1.0

conda/dgl/meta.yaml

 package:
   name: dgl
-  version: "0.0.1"
+  version: "0.1.0"
 
 source:
   git_url: https://github.com/jermainewang/dgl.git

docs/source/conf.py

@@ -23,10 +23,9 @@ project = 'DGL'
 copyright = '2018, DGL Team'
 author = 'DGL Team'
 
-# The short X.Y version
-version = '0.0.1'
-# The full version, including alpha/beta/rc tags
-release = '0.0.1'
+import dgl
+version = dgl.__version__
+release = dgl.__version__
 
 
 # -- General configuration ---------------------------------------------------

docs/source/env_var.rst

@@ -3,7 +3,7 @@ Environment Variables
 
 Backend Options
 ---------------
-* DGLBACKEND
+* ``DGLBACKEND``
     * Values: String (default='pytorch')
     * The backend deep lerarning framework for DGL.
     * Choices:
@@ -12,7 +12,7 @@ Backend Options
 
 Data Repository
 ---------------
-* DGL_REPO
+* ``DGL_REPO``
     * Values: String (default='https://s3.us-east-2.amazonaws.com/dgl.ai/')
     * The repository url to be used for DGL datasets and pre-trained models.
     * Suggested values:

docs/source/faq.rst

+FAQ
+===
+
+Trouble Shooting
+----------------
+
+DGL is still in its alpha stage, so expect some trial and error. Keep in mind that
+DGL is a framework atop other frameworks (e.g. Pytorch, MXNet), so it is important
+to figure out whether the bug is due to DGL or the backend framework. For example,
+DGL will usually complain and throw a ``DGLError`` if anything goes wrong. If you
+are pretty confident that it is a bug, feel free to raise an issue.
+
+
+Out-of-memory
+-------------
+
+Graph can be very large and training on graph may cause OOM. There are several
+tips to check when you get an OOM error.
+
+* Try to avoid propagating node features to edges. Number of edges are usually
+  much larger than number of nodes. Try to use out built-in functions whenever
+  it is possible.
+* Look out for cyclic references due to user-defined functions. Usually we recommend
+  using global function or module class for the user-defined functions. Pay
+  attention to the variables in function closure. Also, it is usually better to
+  directly provide the UDFs in the message passing APIs rather than register them:
+
+  ::
+
+     # define a message function
+     def mfunc(edges): return edges.data['x']
+
+     # better as the graph `mfunc` does not hold a reference to `mfunc`
+     g.send(some_edges, mfunc)
+
+     # the graph hold a reference to `mfunc` so as all the variables in its closure
+     g.register(mfunc)
+     g.send(some_edges)
+
+* If your scenario does not require autograd, you can use ``inplace=True`` flag
+  in the message passing APIs. This will update features inplacely that might
+  save memory.

docs/source/index.rst

@@ -76,6 +76,13 @@ credit, see `here <https://www.dgl.ai/ack>`_.
 
    api/python/index
 
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   faq
+   env_var
+
 Index
 -----
 * :ref:`genindex`

include/dgl/runtime/c_runtime_api.h

@@ -33,7 +33,7 @@
 #endif
 
 // DGL version
-#define DGL_VERSION "0.5.dev"
+#define DGL_VERSION "0.1.0"
 
 
 // DGL Runtime is DLPack compatible.

python/dgl/_ffi/libinfo.py

@@ -87,4 +87,4 @@ def find_lib_path(name=None, search_path=None, optional=False):
 # We use the version of the incoming release for code
 # that is under development.
 # The following line is set by dgl/python/update_version.py
-__version__ = "0.0.1"
+__version__ = "0.1.0"

python/update_version.py

+"""
+This is the global script that set the version information of DGL.
+This script runs and update all the locations that related to versions
+List of affected files:
+- dgl-root/python/dgl/_ffi/libinfo.py
+- dgl-root/include/dgl/runtime/c_runtime_api.h
+- dgl-root/conda/dgl/meta.yaml
+"""
+import os
+import re
+# current version
+# We use the version of the incoming release for code
+# that is under development
+__version__ = "0.1.0"
+
+# Implementations
+def update(file_name, pattern, repl):
+    update = []
+    hit_counter = 0
+    need_update = False
+    for l in open(file_name):
+        result = re.findall(pattern, l)
+        if result:
+            assert len(result) == 1
+            hit_counter += 1
+            if result[0] != repl:
+                l = re.sub(pattern, repl, l)
+                need_update = True
+                print("%s: %s->%s" % (file_name, result[0], repl))
+            else:
+                print("%s: version is already %s" % (file_name, repl))
+
+        update.append(l)
+    if hit_counter != 1:
+        raise RuntimeError("Cannot find version in %s" % file_name)
+
+    if need_update:
+        with open(file_name, "w") as output_file:
+            for l in update:
+                output_file.write(l)
+
+
+def main():
+    curr_dir = os.path.dirname(os.path.abspath(os.path.expanduser(__file__)))
+    proj_root = os.path.abspath(os.path.join(curr_dir, ".."))
+    # python path
+    update(os.path.join(proj_root, "python", "dgl", "_ffi", "libinfo.py"),
+           r"(?<=__version__ = \")[.0-9a-z]+", __version__)
+    # C++ header
+    update(os.path.join(proj_root, "include", "dgl", "runtime", "c_runtime_api.h"),
+           "(?<=DGL_VERSION \")[.0-9a-z]+", __version__)
+    # conda
+    for path in ["dgl"]:
+        update(os.path.join(proj_root, "conda", path, "meta.yaml"),
+               "(?<=version: \")[.0-9a-z]+", __version__)
+
+if __name__ == "__main__":
+    main()