Editing TF bridge integration docs (#786)

doc/sphinx/source/framework-integration-guides.rst

@@ -169,12 +169,15 @@ Compile MXNet with nGraph
 TensorFlow\* 
 =============
 
-Build with an XLA plugin to ``libngraph``
-------------------------------------------
+This section describes how install TensorFlow* with the bridge code 
+needed to be able to access nGraph backends. Note that you **do not** 
+need to have already installed nGraph for this procedure to work.  
 
-#. To prepare to build TensorFlow with an XLA plugin capable of running |nGl|, 
-   use the standard build process which is a system called "bazel". These 
-   instructions were tested with `bazel version 0.11.0`_. 
+Bridge TensorFlow/XLA to nGraph
+-------------------------------
+
+#. Prepare your system with the TensorFlow prerequisite, a system called 
+   "bazel". These instructions were tested with `bazel version`_ 0.11.0. 
 
    .. code-block:: console
 
@@ -182,8 +185,8 @@ Build with an XLA plugin to ``libngraph``
       $ chmod +x bazel-0.11.0-installer-linux-x86_64.sh
       $ ./bazel-0.11.0-installer-linux-x86_64.sh --user
 
-#. Add and source the ``bin`` path to your ``~/.bashrc`` file in order to be 
-   able to call bazel from the user's installation we set up:
+#. Add and source the ``bin`` path that bazel just created to your ``~/.bashrc`` 
+   file in order to be able to call bazel from the user's installation we set up:
 
    .. code-block:: bash
    
@@ -193,26 +196,30 @@ Build with an XLA plugin to ``libngraph``
 
       $ source ~/.bashrc   
 
-#. Ensure that all the TensorFlow dependencies are installed, as per the
+#. Ensure that all the other TensorFlow dependencies are installed, as per the
    TensorFlow `installation guide`_:
 
-   .. note:: You do not need CUDA in order to use the nGraph XLA plugin.
+   .. important:: CUDA is not needed. 
 
-#. Once TensorFlow's dependencies are installed, clone the source of the 
+#. After TensorFlow's dependencies are installed, clone the source of the 
    `ngraph-tensorflow`_ repo to your machine; this is the required fork for 
-   this integration:
+   this integration. Many users may prefer to use a Python virtual env from 
+   here forward:  
 
    .. code-block:: console
 
+      $ python3 -m venv frameworks  
+      $ cd frameworks 
+      $ . bin/activate
       $ git clone git@github.com:NervanaSystems/ngraph-tensorflow.git
       $ cd ngraph-tensorflow
       $ git checkout ngraph-tensorflow-preview-0
 
 #. Now run :command:`./configure` and choose `y` when prompted to build TensorFlow
-   with XLA just-in-time compiler.
+   with XLA :abbr:`Just In Time (JIT)` support.
 
    .. code-block:: console
-      :emphasize-lines: 4-5
+      :emphasize-lines: 6-7
 
       . . .
 
@@ -227,25 +234,21 @@ Build with an XLA plugin to ``libngraph``
 
       . . .
 
-#. Next build the pip package
+#. Build and install the pip package:
 
    .. code-block:: console
 
       $ bazel build --config=opt //tensorflow/tools/pip_package:build_pip_package
       $ bazel-bin/tensorflow/tools/pip_package/build_pip_package /tmp/tensorflow_pkg
-
-#. Next install the pip package
-
-   .. code-block:: console
-
       $ pip install -U /tmp/tensorflow_pkg/tensorflow-1.*whl
 
-   .. note::  The actual name of the Python wheel file will be updated to the official 
-   version of TensorFlow as the ngraph-tensorflow repository is synchronized frequently 
-   with the original TensorFlow repository.
 
-#. Now clone the ngraph-tensorflow-bridge repo one level above -- in the parent directory 
-   of the ngraph-tensorflow repo cloned in step 1:
+      .. note::  The actual name of the Python wheel file will be updated to the official 
+         version of TensorFlow as the ngraph-tensorflow repository is synchronized frequently 
+         with the original TensorFlow repository.
+
+#. Now clone the ``ngraph-tensorflow-bridge`` repo one level above -- in the 
+   parent directory of the ngraph-tensorflow repo cloned in step 4:
 
    .. code-block:: console
 
@@ -262,16 +265,20 @@ Build with an XLA plugin to ``libngraph``
       $ cmake ../
       $ make install
 
-This final step automatically downloads the necessary version of ngraph and the dependencies. 
-The resulting plugin DSO named libngraph_plugin.so gets copied to the following directory 
-inside the TensorFlow installation directory: <Python site-packages>/tensorflow/plugins
+This final step automatically downloads the necessary version of ngraph and the 
+dependencies. The resulting plugin `DSO`_ named ``libngraph_plugin.so`` gets copied 
+to the following directory inside the TensorFlow installation directory: 
+
+:: 
+
+   <Python site-packages>/tensorflow/plugins
 
 Once the build and installation steps are complete, you can start experimenting with 
-nGraph backends.
+coding for nGraph. 
 
 
 Run MNIST Softmax with the activated bridge
-------------------------------------------------------------
+----------------------------------------------
 
 To see everything working together, you can run MNIST Softmax example with the now-activated 
 bridge to nGraph. The script named mnist_softmax_ngraph.py can be found under the 
@@ -303,12 +310,14 @@ your cloned version of `ngraph-tensorflow-bridge`_:
 
    $ python mnist_softmax_ngraph.py
 
-   .. note::  The number-of-threads parameter specified in the `OMP_NUM_THREADS` is 
-   a function of number of CPU cores that are available in your system. 
+
+.. note:: The number-of-threads parameter specified in the ``OMP_NUM_THREADS`` 
+   is a function of number of CPU cores that are available in your system. 
 
 
 .. _MXNet: http://mxnet.incubator.apache.org
-.. _bazel version 0.5.4: https://github.com/bazelbuild/bazel/releases/tag/0.5.4
+.. _bazel version: https://github.com/bazelbuild/bazel/releases/tag/0.11.0
+.. _DSO: http://csweb.cs.wfu.edu/%7Etorgerse/Kokua/More_SGI/007-2360-010/sgi_html/ch03.html
 .. _installation guide: https://www.tensorflow.org/install/install_sources#prepare_environment_for_linux
 .. _ngraph-tensorflow: https://github.com/NervanaSystems/ngraph-tensorflow
 .. _ngraph-tensorflow-bridge: https://github.com/NervanaSystems/ngraph-tensorflow-bridge