update the readme file

2 files changed, 64 insertions, 55 deletions

diff --git a/README.md b/README.md
deleted file mode 100644
index d3843c9..0000000
--- a/README.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# The Nerv Toolkit User Manual
-NOTE: This readme is obsolete and will be rearranged, for further information, please check http://nerv-sjtu.github.io/nerv/
-
-This user manual will information about how to use __Nerv__ and __Nerv__'s interface.
-
-## How to make and start using
-First make sure you have __lua__ and __CUDA__ installed on your computer.  
-__Nerv__ is currently developed via github.You can download and make __Nerv__ by doing the following:
-```
-cd ~
-git clone https://github.com/Nerv-SJTU/nerv.git
-cd nerv
-git submodule init && git submodule update
-make
-#To include some new CUDA feature(e.x. atomicCAS), use "make CFLAGS=-D__NERV_FUTURE_CUDA_7"
-
-#further, if you want the speech modules
-git clone https://github.com/Nerv-SJTU/nerv-speech.git speech 
-make speech
-```
-The `git submodule` command is for the __luajit__ repository inside __Nerv__.  
-Now, you can try to run some example scripts.  
-```
-./install/bin/nerv examples/cumatrix_example.lua
-```
-To get an example of DNN(for ASR) training, run(this requires the speech modules)  
-You need to be at or (copy files from) `/slfs1`(SJTU speechlab cluster) to get this running.  
-```
-./install/bin/nerv nerv/examples/asr_trainer.lua nerv/examples/swb_baseline.lua
-```
-
-## How to contribute
-Fork the original repository, then use the __pull&merge__ function in github to contribute.  
-The pull&merge request can be found on your dashboard in github. See this [sync-help] to sync with the original repository.
-
-## Nerv Packages
-* __luaT__  
-Nerv uses [luaT]\(a [Torch] library\) to define lua class in C.
-* __[The Nerv OOP](nerv/doc/nerv_class.md)__  
-Enables object-oriented programming in Nerv.
-* __[The Nerv utility functions](nerv/doc/nerv.md)__  
-Inlcudes some utility functions from luaT to implement __Nerv.Class__.
-* __[The Nerv Matrix Package](nerv/doc/nerv_matrix.md)__  
-The matrix package is a basic package in __Nerv__ that is used to store and manipulate matrices.
-* __[The Nerv IO Package](nerv/doc/nerv_io.md)__  
-The IO package is used to read and write parameters to file.
-* __[The Nerv Parameter Package](nerv/doc/nerv_param.md)__  
-The parameter package is used to store, read model parameters from file.
-* __[The Nerv Layer Package](nerv/doc/nerv_layer.md)__  
-The layer package is used to define propagation and backpropagation of different type of layers.
-* __[The Nerv NN Package](nerv/doc/nerv_nn.md)__  
-The nn package is for organizing a neural network, it contains __nerv.LayerRepo__, __nerv.ParamRepo__, and __nerv.DAGLayer__.
-[luaT]:https://github.com/torch/torch7/tree/master/lib/luaT
-[Torch]:https://github.com/torch
-[sync-help]:https://help.github.com/articles/syncing-a-fork/
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..1aa0775
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,64 @@
+NERV Toolkit
+============
+
+NOTE: This readme is in-progress.
+
+Installation
+------------
+First, make sure you have at least one implementation of BLAS and CUDA installed
+on your computer.
+
+- Checkout NERV:
+  
+  ::
+
+    bash
+    git clone https://speechlab.sjtu.edu.cn/gitlab/Nerv-SJTU/nerv.git
+
+- Checkout submodules (luajit, luarocks, Penlight, etc.):
+
+  ::
+
+    cd nerv
+    git submodule init && git submodule update
+
+- Build NERV: you can specify either ``mkl`` or ``atlas`` to ``BLAS_TYPE``.
+  ``BLAS_BASE`` is the directory containing BLAS ``.so`` files. By default,
+  ``atlas`` is used for ``BLAS_TYPE``, ``/usr/lib/`` is used for ``BLAS_BASE``,
+  and ``/usr/local/cuda`` is used for ``CUDA_BASE``.
+
+  ::
+
+    # an example for compiling on SJTU Speechlab major cluster
+    make BLAS_TYPE=mkl BLAS_BASE=/home/intel/mkl/lib/intel64/ CUDA_BASE=/usr/lib/cuda
+
+- To include some new features (e.g. ``atomicCAS`` in CUDA), add corresponding flags to
+  ``NERV_FEAT`` (e.g. ``NERV_FEAT=-D__NERV_FUTURE_CUDA_7``) while making:
+
+  ::
+
+    make NERV_FEAT=-D__NERV_FUTURE_CUDA_7 BLAS_TYPE=mkl BLAS_BASE=/home/intel/mkl/lib/intel64/ CUDA_BASE=/usr/lib/cuda
+
+- For speech tasks, you need to install related lua rocks (Lua packages):
+
+  ::
+
+    # checkout speech repository to local directory nerv/speech (suppose you're
+    # still at the root directory of NERV repo)
+    git clone https://speechlab.sjtu.edu.cn/gitlab/Nerv-SJTU/nerv-speech.git speech
+    # build and install HTK I/O support, Kaldi I/O support, Kaldi decoding support, etc.
+    make speech
+
+Example & Tutorial
+------------------
+For speech tasks, please refer to ``tutorial/`` in ``nerv-speech`` repository.
+
+Contribution
+------------
+The basic rule is simple: just fork the original repository, then create a pull
+request (merge request) to the administrator of the project. If you want to fix
+any bugs in existing code, don't hesitate to create a pull (merge) request to
+the repository with clear and detailed analysis of the problem. If you want to
+add additional task-specific functionalities (modules) for speech to NERV,
+please create a luarocks-compliant package and also a pull (merge) request to
+the ``nerv-speech`` repository instead of ``nerv``.