refs #2: Move details from README to docs.

README.md

@@ -1,64 +1,21 @@
 # NBA (Network Balancing Act)
 "A High-performance packet processing framework for heterogeneous processors," [EuroSys 2015 paper](http://an.kaist.ac.kr/~sbmoon/paper/intl-conf/2015-eurosys-nba.pdf)
 
-## Disclaimer
+## Notice for paper readers
 
 * The IDS source code is not available to the public, as it contains a derivation from industry-transferred code from [Kargus](http://shader.kaist.edu/kargus/).
   - You could refer to other open-source code, such as [a GPU implementation of the Aho-Corasick algorithm in Snap](https://github.com/wbsun/g4c/blob/master/g4c_ac.h).
-* We used Intel DPDK v1.7 for the EuroSys 2015 paper, but have now upgraded to v1.8.
+* We used Intel DPDK v1.7 for the EuroSys 2015 paper, but have now upgraded to v2.0+.
 
-## How to compile
+## Main Features
 
-We recommend to use Ubuntu 14.04 or newer.  
-First you need to install some prerequisites.
+* 80-Gbps packet processing with modular programming interface similar to Click.
+* GPU offloading to boost complex computations such as IPsec encryption
+* Automatic CPU/GPU load balancing to maximize the overall throughput
 
-* NVIDIA CUDA 7.0 or newer
-  - We recommend to download the latest version of `.bin` package from [the NVIDIA website](https://developer.nvidia.com/cuda-downloads) instead of using system packages.
-  - A small daemon is required to "pin" GPU's interrupts to specific cores.  
-    See details in https://gist.github.com/3404967 .
-  - Add `export PATH=$PATH:/usr/local/cuda/bin` to `/etc/profile` or similar places.
-  - Add `/usr/local/cuda/lib64` to `/etc/ld.so.conf.d/cuda.conf` (create if not exists) and run `ldconfig`.
-* g++ 4.8 or newer (the compiler must support C++11 standard.)
-* Intel DPDK 1.8
-  - Clone from git://dpdk.org/dpdk or download the release tarball.
-  - Install the kernel header/source packages first.
-  - Run `make install T=x86_64-native-linuxapp-gcc` in the checked-out directory.
-* Python 3.4 or newer
-  - `pip install snakemake`
-  - `apt-get install libpython3-dev`
-* Click configuration parser
-  - Just run `git submodule init && git submodule update`
-  - It will be *automatically built* along with NBA when you first build NBA.
-* `sysstat` package (or any package that offers `mpstat` command) to run experiment scripts
-* If all set, then set the environment variable as follows:
-  - `USE_CUDA=1`
-  - `NBA_DPDK_PATH=/home/userid/dpdk/x86_64-native-linuxapp-gcc`
-  - Then run `snakemake`
-* If all is well, the executable is located in `bin/main`.
+## Documentation
 
-### Compile options
-
-Our build script offers a few configurable parameters as environment variables:
-* `NBA_DPDK_PATH`: specifies the path to Intel DPDK (required)
-* `NBA_RANDOM_PORT_ACCESS`: randomizes the RX queue scanning order for each worker thread (default: false)
-* `NBA_OPENSSL_PATH`: specifies the path of OpenSSL library (default: /usr)
-* `USE_CUDA`: activates NVIDIA CUDA support (default: true)
-* `USE_PHI`: activates Intel Xeon Phi support (default: false, not fully implemented yet)
-* `USE_NVPROF`: activates nvprof API calls to track GPU-related timings (default: false)
-* `USE_OPENSSL_EVP`: determines whether to use EVP API for OpenSSL that enables AES-NI support (default: true)
-* `NBA_NO_HUGE`: determines whether to use huge-pages (default: true)
-* `NBA_PMD`: determines what poll-mode driver to use (default: ixgbe)
-
-※ Boolean variables are expressed as 1 or 0.
-
-## How to run
-
-Execute `bin/main` with DPDK EAL arguments and NBA arguments.  
-For example,
-
-```
-$ sudo bin/main -cffff -n4 -- configs/rss.py configs/ipv4-router.click
-```
+[See the documentation online.](http://nba.readthedocs.org/en/latest/)
 
 ## Ongoing work
 

docs/gsg/build.rst

@@ -0,0 +1,82 @@
+Building NBA
+============
+
+We recommend to use Ubuntu 14.04 or newer.  
+
+Supported Platforms
+-------------------
+
+Step-by-step Guide for Ubuntu 14.04 LTS
+---------------------------------------
+
+** Package and software to install **
+
+* NVIDIA CUDA 7.0 or newer
+  - We recommend to download the latest version of `.bin` package from `the NVIDIA website<https://developer.nvidia.com/cuda-downloads>`_ instead of using system packages.
+
+.. note::
+
+  A small daemon is required to "pin" GPU's interrupts to specific cores.  
+  See details in `our gist <https://gist.github.com/3404967>`_.
+
+  - Add `export PATH=$PATH:/usr/local/cuda/bin` to `/etc/profile` or similar places.
+  - Add `/usr/local/cuda/lib64` to `/etc/ld.so.conf.d/cuda.conf` (create if not exists) and run `ldconfig`.
+
+* g++ 4.8 or newer (the compiler must support C++11 standard.)
+
+* Intel DPDK 1.8
+.. code-block:: console
+
+   ~$ git clone git://dpdk.org/dpdk
+   ~$ cd dpdk
+   ~/dpdk$ make install T=x86_64-native-linuxapp-gcc
+
+.. note::
+
+   You need to install the kernel header/source packages first.
+
+* Python 3.4 or newer
+
+.. code-block:: console
+
+  pip install snakemake
+  apt-get install libpython3-dev
+
+.. note::
+
+   We recommend using a separate Python environment contained inside the user directory.
+   See pyenv for more details.
+
+* Click configuration parser
+  - Just run `git submodule init && git submodule update`
+  - It will be *automatically built* along with NBA when you first build NBA.
+
+* `sysstat` package (or any package that offers `mpstat` command) to run experiment scripts
+
+** Compilation **
+
+* Set the environment variable as follows:
+
+.. code-block:: console
+
+  $ export NBA_DPDK_PATH=/home/userid/dpdk/x86_64-native-linuxapp-gcc
+  $ snakemake
+
+* If all is well, the executable is located in `bin/main`.
+
+Customizing Your Build
+----------------------
+
+Our build script offers a few configurable parameters as environment variables:
+
+* `NBA_DPDK_PATH`: specifies the path to Intel DPDK (required)
+* `NBA_RANDOM_PORT_ACCESS`: randomizes the RX queue scanning order for each worker thread (default: false)
+* `NBA_OPENSSL_PATH`: specifies the path of OpenSSL library (default: /usr)
+* `USE_CUDA`: activates NVIDIA CUDA support (default: true)
+* `USE_PHI`: activates Intel Xeon Phi support (default: false, not fully implemented yet)
+* `USE_NVPROF`: activates nvprof API calls to track GPU-related timings (default: false)
+* `USE_OPENSSL_EVP`: determines whether to use EVP API for OpenSSL that enables AES-NI support (default: true)
+* `NBA_NO_HUGE`: determines whether to use huge-pages (default: true)
+* `NBA_PMD`: determines what poll-mode driver to use (default: ixgbe)
+
+※ Boolean variables are expressed as 1 or 0.

docs/gsg/index.rst

@@ -0,0 +1,9 @@
+Getting Started Guide
+=====================
+
+.. toctree::
+    :maxdepth: 2
+    :numbered:
+    sys_reqs
+    build
+    running

docs/gsg/running.rst

@@ -0,0 +1,17 @@
+Running NBA
+===========
+
+Standalone Execution
+--------------------
+
+Execute `bin/main` with DPDK EAL arguments and NBA arguments.  
+For example,
+
+.. code-block:: console
+
+   $ sudo bin/main -cffff -n4 -- configs/rss.py configs/ipv4-router.click
+
+For details about DPDK EAL arguments, see `DPDK's documentation <http://dpdk.readthedocs.org/>`_.
+
+Scripted Execution
+------------------

docs/gsg/sys_reqs.rst

@@ -0,0 +1,10 @@
+System Requirements
+===================
+
+Supported Hardware
+------------------
+
+BIOS Settings
+-------------
+
+

docs/index.rst

@@ -9,7 +9,8 @@ Welcome to Network Balancing Act's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   gsg/index