another pass towards a clearer README

1 files changed, 80 insertions, 74 deletions

diff --git a/README.rst b/README.rst
index 183229fe..dd8ee425 100644
--- a/README.rst
+++ b/README.rst
@@ -1,88 +1,105 @@
-LEAP                   
-The LEAP Encryption Access Project
-your internet encryption toolkit
+=========================================
+The LEAP Encryption Access Project Client
+=========================================
+
+*your internet encryption toolkit*
 
 Installation
 =============
 
-Dependencies
---------------
-Listed in pkg/requirements.pip and pkg/test-requirements.pip
+Base Dependencies
+------------------
+Leap client depends on these libraries:
 
 * python 2.6 or 2.7
-* python setuptools
-* qt4 libraries
+* qt4 libraries (see installing Qt section below)
+* libgnutls
+
+Python packages are listed in ``pkg/requirements.pip`` and ``pkg/test-requirements.pip``
+
+Debian systems
+--------------
+
 * python-qt4
 * python-gnutls == 1.1.9
 * python-keyring
+* python-crypto
+* python setuptools
 * python-nose, python-mock, python-coverage (if you want to run tests)
 
-If you are on a debian-based system, you can run:
+Under a debian-based system, you can run::
 
-  apt-get install python-qt4 python-qt4-doc pyqt4-dev-tools python-gnutls libgnutls-dev python-setuptools python-nose
+  apt-get install python-qt4 python-gnutls python-keyring python-crypto
+  
+For testing:
 
-# **note**: I think setuptools is needed for build process only.
-# we should separate what's needed as a lib dependency, and what's a dependency that has been debianized but
-# still can be retrieved using pip.
+  python-nose python-mock
 
-If you are installing in a virtualenv:
+For building the package you will need also::
 
-  pip install -r pkg/requirements.pip
+  pyqt4-dev-tools libgnutls-dev python-setuptools python-all-dev
 
-# **note**: I _think_ setuptools is needed for build process only.                     
-# we should separate what's needed as a global lib dependency, and what's a dependency that
-# still can be retrieved using pip.                                                  
-                                                        
-If you are installing in a virtualenv:                                               
+# **note**: Some libs like setuptools are needed as build-deps only.                  
+# TODO we probably should separate what's needed as a global lib dependency, and what's a dependency that still can be retrieved using pip.
+
+Install python dependencies with pip
+-------------------------------------
+Use pip (preferrable inside a virtualenv) to install all the required python packages::
+
+  apt-get install python-pip
   pip install -r pkg/requirements.pip
 
 
 Install PyQt
 ------------
-pip install PyQt will fail because PyQt4 does not use the standard setup.py mechanism.
-Instead, they use configure.py which generates a Makefile.
+If you are using pip as your python packaging tool, pip install PyQt will fail because PyQt4 does not use the standard setup.py mechanism.
+
+Instead, they use configure.py which generates a Makefile::
 
-python configure.py
-make && make install
+  python configure.py
+  make && make install
 
 You can:
 
-* (recommended) run pkg/postmkvenv.sh after creating your virtualenv. It will symlink to your global PyQt installation.
+* recommended run pkg/postmkvenv.sh after creating your virtualenv. It will symlink to your global PyQt installation.
 * install PyQt globally and make a virtualenv with --site-packages
 * run pkg/install_pyqt.sh inside your virtualenv (with --no-site-packages)
 
 
-Install
----------------
+Install leap-client
+-------------------
+
+After getting the sources and installing all the dependencies, proceed to install leap-client package:
 
 # need to run this if you are installing from the git source tree
-# not needed if installing from a tarball.
+# not needed if installing from a tarball::
 
-python setup.py branding
+  python setup.py branding
 
-# run this if you have installed previous versions before
+# run this if you have installed previous versions before::
 
-python setup.py clean
+  python setup.py clean
 
-python setup.py install # as root if installing globally.
+And finally, build and install leap-client::
 
+  python setup.py install # as root if installing globally.
 
 
 Running the App
 -----------------
 
 If you're running a branded build, the script name will have a infix that
-depends on your build flavor. Look for it in /usr/local/bin
+depends on your build flavor. Look for it in ``/usr/local/bin``::
 
-% leap-springbok-client
+  % leap-springbok-client
 
-In order to run in debub mode:
+In order to run the client in debug mode::
 
-% leap-springbok-client --debug --logfile /tmp/leap.log
+  % leap-springbok-client --debug --logfile /tmp/leap.log
 
-To see all options:
+To see all the available command line options::
 
-% leap-springbok-client --help
+  % leap-springbok-client --help
 
 
 Development
@@ -93,60 +110,52 @@ Hack
 
 Some steps 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
+# recommended: enable a **virtualenv** to isolate your libraries::
 
-# make sure you're in the development branch
+  % virtualenv .  # ensure your .gitignore knows about it
+  % source bin/activate
 
-(leap_client)% git checkout develop
+# make sure you are in the development branch::
 
-(leap_client)% pkg/postmkvenv.sh
-
-(leap_client)% python setup.py branding
-(leap_client)% python setup.py develop  
+  (leap_client)% git checkout develop
+  (leap_client)% pkg/postmkvenv.sh
+  (leap_client)% python setup.py branding
+  (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:
+it's recommended to run the app like this during development cycle::
 
-(leap_client)% cd src/leap 
-(leap_client)% python app.py --debug
+  (leap_client)% cd src/leap 
+  (leap_client)% python app.py --debug
 
 Install testing dependencies
 ----------------------------
 
-have a look at setup/test-requires
+have a look at ``setup/test-requires``
 The ./run_tests.sh command should install all of them in your virtualenv for you.
 
 Running tests
 -------------
 
-./run_tests.sh
-
-force no virtualenv and create coverage reports:
-./run_tests.sh -N -c
-
-if you want to run specific tests, pass the (sub)module to nose:
-
-nosetests leap.util
+There is a convenience script at ``./run_tests.sh``
 
-or
+If you want to run specific tests, pass the (sub)module to nose::
+  nosetests leap.util
 
-nosetests leap.util.test_leap_argparse
+or::
+  nosetests leap.util.test_leap_argparse
 
-Colorized output
-----------------
-Install rednose locally and activate it.
+Hint: colorized output
+----------------------
+Install ``rednose`` locally and activate it, and give your eyes a rest :)::
 
   (leap_client)% pip install rednose
   (leap_client)% export NOSE_REDNOSE=1
 
-enjoy :)
 
 Tox
 ---
-For running testsuite against all the supported python versions (currently 2.6 and 2.7), run:
+For running testsuite against all the supported python versions (currently 2.6 and 2.7), run::
 
   tox -v
 
@@ -154,12 +163,9 @@ For running testsuite against all the supported python versions (currently 2.6 a
 Compiling resource/ui files
 -----------------------------
 
-You should refresh resource/ui files every time you
-change an image or a resource/ui (.ui / .qc). From
-the root folder:
+You should refresh resource/ui files every time you change an image or a resource/ui (.ui / .qc). From the root folder::
 
-make ui
-make resources
+  make ui
+  make resources
 
-As there are some tests to guard against unwanted resource updates,
-you will have to update the resource hash in those failing tests.
+As there are some tests to guard against unwanted resource updates, you will have to update the resource hash in those failing tests.