documentation update!

reSTructured (no pun intended) the sphinx docs,
and trimmed README

1 files changed, 63 insertions, 109 deletions

diff --git a/README.rst b/README.rst
index cc30c544..d8e055da 100644
--- a/README.rst
+++ b/README.rst
@@ -4,168 +4,122 @@ The LEAP Encryption Access Project Client
 
 *your internet encryption toolkit*
 
-Installation
+Read the docs!
+==============
+
+You can read the documentation online at `http://leap-client.readthedocs.org <http://http://leap-client.readthedocs.org/en/latest/>`_. If you prefer to build it locally, run::
+
+    $ cd docs
+    $ make html
+
+Quick Start
 =============
 
-Base Dependencies
+Dependencies
 ------------------
+
 Leap client depends on these libraries:
 
-* python 2.6 or 2.7
-* qt4 libraries (see installing Qt section below)
-* libgnutls
-* openvpn
+* ``python 2.6`` or ``2.7``
+* ``qt4 libraries`` (see installing Qt section below)
+* ``libgnutls``
+* ``openvpn``
 
 Python packages are listed in ``pkg/requirements.pip`` and ``pkg/test-requirements.pip``
 
-Debian systems
---------------
-# XXX TODO: move to packaging doc.
-
-* python-qt4
-* python-crypto
-* python setuptools
-* python-nose, python-mock, python-coverage (if you want to run tests)
-
-Note: these two need a version that is not found in the current debian stable or in ubuntu 12.04. 
-
-* python-gnutls == 1.1.9
-* python-keyring
+Debian
+^^^^^^
 
 Under a debian-based system, you can run::
 
-  # apt-get install openvpn python-qt4 python-crypto
+  $ apt-get install openvpn python-qt4 python-crypto python-requests python-gnutls
 
-For testing:
+For *testing*::
 
-  python-nose python-mock python-coverage
+  $ apt-get install python-nose python-mock python-coverage
 
-For _building_ the package you will need to install also::
+For *building* the package you will need to install also::
 
-  pyqt4-dev-tools libgnutls-dev python-setuptools python-all-dev
+  $ apt-get install pyqt4-dev-tools libgnutls-dev python-setuptools python-all-dev
 
 
-Install python dependencies with pip
--------------------------------------
-# XXX TODO: move to developers doc.
+pip
+^^^
 
-Use pip (preferrable inside a virtualenv) to install the required python packages::
+Use pip to install the required python packages::
 
-  # apt-get install python-pip python-dev libgnutls-dev
-  % pip install -r pkg/requirements.pip
+  $ apt-get install python-pip python-dev libgnutls-dev
+  $ pip install -r pkg/requirements.pip
 
 
-Install leap-client
--------------------
+Installing
+-----------
 
 After getting the source and installing all the dependencies, proceed to install ``leap-client`` package:
 
-# run this if you have installed previous versions before::
-
-  python setup.py clean
+.. note::
+   if you have installed previous versions before::
+   python setup.py clean
 
 And finally, build and install leap-client::
 
-  python setup.py install # as root if installing globally.
+  python setup.py install
 
 
-Running the App
------------------
+Running
+-------
 
-After a successful installation, there should be a launcher called leap-client somewhere in your path::
+After a successful installation, there should be a launcher called ``leap-client`` somewhere in your path::
 
   % leap-client
 
-In order to run the client in debug mode::
-
-  % leap-client --debug --logfile /tmp/leap.log
-
-To see all the available command line options::
-
-  % leap-client --help
 
+Hacking
+=======
 
-Development
-==============
-
-Troubleshooting PyQt install inside a virtualenv
-------------------------------------------------
-If you attempt to install PyQt inside a virtualenv using pip, it will fail because PyQt4 does not use the standard setup.py mechanism.
-
-As a workaround, you can:
-
-  * run pkg/postmkvenv.sh after creating your virtualenv. It will symlink to your global PyQt installation _(recommended)_.
-  * install PyQt globally and make a virtualenv with --site-packages
-
-Or, if you prefer, you can download the official PyQt tarball and execute `configure.py` in the root folder of their distribution, which generates a Makefile::
-
-  python configure.py
-  make && make install
+.. note::
+   link to Hackers Guide in documentation.
 
+The LEAP client git repository is available at::
 
-Hack
---------------
-
-The LEAP client git repository is available at:
-git://leap.se/leap_client 
+  git://leap.se/leap_client 
 
 Some steps need to be run when setting a development environment for the first time.
 
-# recommended: enable a **virtualenv** to isolate your libraries::
-
-  % virtualenv .  # ensure your .gitignore knows about it
-  % source bin/activate
-
-# make sure you are in the development branch::
-
-  (leap_client)% git checkout develop
-  (leap_client)% pkg/postmkvenv.sh
-  (leap_client)% python setup.py develop  
-
-to avoid messing with the entry point and global versions installed,
-it's recommended to run the app like this during development cycle::
-
-  (leap_client)% cd src/leap 
-  (leap_client)% python app.py --debug
+Enable a **virtualenv** to isolate your libraries::
 
-Install testing dependencies
-----------------------------
+  $ virtualenv .  # ensure your .gitignore knows about it
+  $ source bin/activate
 
-have a look at ``pkg/test-requirements.pip``
-The ./run_tests.sh command should install all of them in your virtualenv for you.
+Make sure you are in the development branch::
 
-Running tests
--------------
+  (leap_client)$ git checkout develop
 
-There is a convenience script at ``./run_tests.sh``
+Symlink your global pyqt libraries::
 
-If you want to run specific tests, pass the (sub)module to nose::
-  nosetests leap.util
+  (leap_client)$ pkg/postmkvenv.sh
 
-or::
-  nosetests leap.util.tests.test_leap_argparse
+And make your working tree available to your pythonpath::
 
-Hint: colorized output
-----------------------
-Install ``rednose`` locally and activate it, and give your eyes a rest :)::
+  (leap_client)$ python setup.py develop  
 
-  (leap_client)% pip install rednose
-  (leap_client)% export NOSE_REDNOSE=1
 
+Testing 
+=======
 
-Tox
----
-For running testsuite against all the supported python versions (currently 2.6 and 2.7), run::
+Have a look at ``pkg/test-requirements.pip`` for the tests dependencies.
 
-  % tox -v
+To run the test suite::
 
+    $ ./run_tests.sh
+    
+which the first time should also install all of them in your virtualenv for you.
 
-Compiling resource/ui files
------------------------------
+License
+=======
 
-You should refresh resource/ui files every time you change an image or a resource/ui (.ui / .qc). From the root folder::
+.. image:: docs/user/intro/gpl.*
 
-  % make ui
-  % make resources
+The LEAP Client is released under the terms of the `GNU GPL version 3`_ or later.
 
-As there are some tests to guard against unwanted resource updates, you will have to update the resource hash in those failing tests.
+.. _`GNU GPL version 3`: http://www.gnu.org/licenses/gpl.txt