Add installation, instructions and getting involved in README, add local cluster docs (#51)

* add install, instructions in readme, add local cluster to install docs

Author: qinxuye

README.rst

@@ -5,6 +5,24 @@ Mars
 
 Mars is a tensor-based unified framework for large-scale data computation.
 
+Installation
+------------
+
+Mars is easy to install by
+
+.. code-block:: bash
+
+    pip install pymars
+
+The distributed version can be installed by
+
+.. code-block:: bash
+
+    pip install 'pymars[distributed]'
+
+For now, distributed version is only available on Linux and Mac OS.
+
+
 Mars tensor
 -----------
 
@@ -56,6 +74,102 @@ Mars can scale in to a single machine, and scale out to a cluster with thousands
 Both the local and distributed version share the same piece of code,
 it's fairly simple to migrate from a single machine to a cluster due to the increase of data.
 
+Running on a single machine including thread-based scheduling,
+local cluster scheduling which bundles the whole distributed components.
+Mars is also easy to scale out to a cluster by starting different components of
+mars distributed runtime on different machines in the cluster.
+
+Threaded
+````````
+
+``execute`` method will by default run on the thread-based scheduler on a single machine.
+
+.. code-block:: python
+
+    import mars.tensor as mt
+
+    a = mt.ones(10, 10)
+    a.execute()
+
+Users can create a session explicitly.
+
+.. code-block:: python
+
+    from mars.session import new_session
+
+    session = new_session()
+    session.run(a + 1)
+    (a * 2).execute(session=session)
+
+    # session will be released when out of with statement
+    with new_session() as session2:
+        session2.run(a / 3)
+
+
+Local cluster
+`````````````
+
+Users can start the local cluster bundled with the distributed runtime on a single machine.
+Local cluster mode requires mars distributed version.
+
+.. code-block:: python
+
+    from mars.deploy.local import new_cluster
+
+    # cluster will create a session and set it as default
+    cluster = new_cluster()
+
+    # run on the local cluster
+    (a + 1).execute()
+
+    # create a session explicitly by specifying the cluster's endpoint
+    session = new_session(cluster.endpoint)
+    session.run(a * 3)
+
+
+Distributed
+```````````
+
+After installing the distributed version on every node in the cluster,
+A node can be selected as scheduler and another as web service,
+leaving other nodes as workers.  The scheduler can be started with the following command:
+
+.. code-block:: bash
+
+    mars-scheduler -a <scheduler_ip> -p <scheduler_port>
+
+Web service can be started with the following command:
+
+.. code-block:: bash
+
+    mars-web -a <web_ip> -s <scheduler_ip> --ui-port <ui_port_exposed_to_user>
+
+Workers can be started with the following command:
+
+.. code-block:: bash
+
+    mars-worker -a <worker_ip> -p <worker_port> -s <scheduler_ip>
+
+After all mars processes are started, users can run
+
+.. code-block:: python
+
+    sess = new_session('http://<web_ip>:<ui_port>')
+    a = mt.ones((2000, 2000), chunks=200)
+    b = mt.inner(a, a)
+    sess.run(b)
+
+
+Getting involved
+----------------
+
+- Join the mailing list: send an email to `mars-dev@googlegroups.com`_.
+- Please report bugs by submitting a `GitHub issue`_.
+- Submit contributions using `pull requests`_.
+
+Thank you in advance for your contributions!
+
+
 .. |Build| image:: https://img.shields.io/travis/mars-project/mars.svg?style=flat-square
    :target: https://travis-ci.org/mars-project/mars
 .. |Coverage| image:: https://img.shields.io/coveralls/github/mars-project/mars.svg?style=flat-square
@@ -67,3 +181,6 @@ it's fairly simple to migrate from a single machine to a cluster due to the incr
 .. |License| image:: https://img.shields.io/pypi/l/pymars.svg?style=flat-square
    :target: https://github.com/mars-project/mars/blob/master/LICENSE
 .. |Implementation| image:: https://img.shields.io/pypi/implementation/pymars.svg?style=flat-square
+.. _`mars-dev@googlegroups.com`: https://groups.google.com/forum/#!forum/mars-dev
+.. _`GitHub issue`: https://github.com/mars-project/mars/issues
+.. _`pull requests`: https://github.com/mars-project/mars/pulls

docs/source/install.rst

@@ -1,5 +1,9 @@
-Standalone install
-==================
+Standalone mode
+===============
+
+Threaded
+--------
+
 You can install Mars via pip:
 
 .. code-block:: bash
@@ -12,10 +16,51 @@ After installation, you can simply open a Python console and run
 
     import mars.tensor as mt
     from mars.session import new_session
-    sess = new_session()
+
     a = mt.ones((5, 5), chunks=3)
     b = a * 4
-    sess.run(b)
+    # if there isn't a local session,
+    # execute will create a default one first
+    b.execute()
+
+    # or create a session explicitly
+    sess = new_session()
+    sess.run(b)  # run b
+
+
+Local cluster
+-------------
+
+Users can start the distributed runtime of Mars on a single machine.
+First, install Mars distributed by run
+
+.. code-block:: bash
+
+    pip install 'pymars[distributed]'
+
+For now, local cluster mode can only run on Linux and Mac OS.
+
+Then start a local cluster by run
+
+.. code-block:: python
+
+    from mars.deploy.local import new_cluster
+
+    cluster = new_cluster()
+
+    # new cluster will start a session and set it as default one
+    # execute will then run in the local cluster
+    a = mt.random.rand(10, 10)
+    a.dot(a.T).execute()
+
+    # cluster.session is the session created
+    cluster.session.run(a + 1)
+
+    # users can also create a session explicitly
+    # cluster.endpoint needs to be passed to new_session
+    session2 = new_session(cluster.endpoint)
+    session2.run(a * 2)
+
 
 Run on Clusters
 ===============