documentation update!

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

8 files changed, 182 insertions, 0 deletions

diff --git a/docs/dev/authors.rst b/docs/dev/authors.rst
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/docs/dev/authors.rst
diff --git a/docs/dev/environment.rst b/docs/dev/environment.rst
new file mode 100644
index 00000000..7eafcdea
--- /dev/null
+++ b/docs/dev/environment.rst
@@ -0,0 +1,59 @@
+.. _environment:
+
+Setting up a Work Environment
+==============================
+
+This document covers how to get an enviroment ready to contribute code to the LEAP Client.
+
+Base Dependencies
+------------------
+Leap client depends on these libraries:
+
+* `python 2.6 or 2.7`
+* `qt4` libraries (see also :ref:`Troubleshooting PyQt install <pyqtvirtualenv>` about how to install inside your virtualenv)
+* `libgnutls`
+* `openvpn`
+
+.. _virtualenv:
+
+Working with virtualenv
+-----------------------
+
+Intro to virtualenv
+^^^^^^^^^^^^^^^^^^^
+Virtualenv blah blah
+
+Install python dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can install python dependencies with pip::
+
+    $ apt-get install python-pip python-dev libgnutls-dev
+    $ pip install -r pkg/requirements.pip
+
+.. _pyqtvirtualenv:
+
+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 the following script after creating your virtualenv. It will symlink to your global PyQt installation (`this is the recommended way if you are running a debian-based system`)::
+
+    $ pkg/postmkvenv.sh
+
+A second option if that does not work for you would be to install PyQt globally and pass the `--site-packages` option when you are creating your virtualenv::
+
+    $ apt-get install python-qt4
+    $ virtualenv --site-packages .
+
+Or, if you prefer, you can also 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
+
+
+Cloning the repo
+----------------
+
+`XXX`
diff --git a/docs/dev/internals.rst b/docs/dev/internals.rst
new file mode 100644
index 00000000..8bb19211
--- /dev/null
+++ b/docs/dev/internals.rst
@@ -0,0 +1,12 @@
+.. _internals:
+
+Internals
+=========
+
+This section covers briefly the internal organization of the LEAP Client source tree.
+
+.. note::
+
+   very unfinished.
+
+`TBD`
diff --git a/docs/dev/internationalization.rst b/docs/dev/internationalization.rst
new file mode 100644
index 00000000..4e75739b
--- /dev/null
+++ b/docs/dev/internationalization.rst
@@ -0,0 +1,27 @@
+.. _i18n:
+
+Internationalization
+====================
+
+This part of the documentation covers the localization and translation of LEAP Client.
+Because we want to *bring fire to the people*, in as many countries and languages as possible.
+
+.. note::
+   We should probably move the translators info to a top level section of the docs, and leave this
+   as internal/tech-savvy notes.
+
+Translate the Qt App
+--------------------
+
+.. note::
+   ... unfinished
+
+`transifex <transifex.com/>`_
+
+Translate the Documentation
+---------------------------
+
+.. note::
+   ...unfinished
+
+`translating sphinx docs <http://sphinx-doc.org/intl.html>`_
diff --git a/docs/dev/resources.rst b/docs/dev/resources.rst
new file mode 100644
index 00000000..7cfa2b70
--- /dev/null
+++ b/docs/dev/resources.rst
@@ -0,0 +1,14 @@
+.. _resources:
+
+PyQt Resource files
+===================
+
+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::
+
+  % 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.
diff --git a/docs/dev/tests.rst b/docs/dev/tests.rst
new file mode 100644
index 00000000..7f5fbaaf
--- /dev/null
+++ b/docs/dev/tests.rst
@@ -0,0 +1,62 @@
+.. _tests:
+
+Running and writing tests
+=========================
+
+.. note::
+   should include seeAlso to virtualenv
+
+This section covers the documentation about the tests for the LEAP Client code.
+All patches should have tests for them ...
+
+
+Testing dependencies
+--------------------
+
+have a look at ``pkg/test-requirements.pip``
+The ``./run_tests.sh`` command should install all of them in your virtualenv for you.
+
+If you prefer to install them system wide, this should do in a debian system::
+
+    $ apt-get install python-nose python-mock python-coverage
+
+
+Running tests
+-------------
+
+There is a convenience script at ``./run_tests.sh``
+
+If you want to run specific tests, pass the (sub)module to nose::
+
+  $ nosetests leap.util
+
+or::
+
+  $ nosetests leap.util.tests.test_leap_argparse
+
+Hint: colorized output
+^^^^^^^^^^^^^^^^^^^^^^
+
+Install ``rednose`` locally, export the ``NOSE_REDNOSE`` variable, and give your eyes a rest :)::
+
+  (leap_client)% pip install rednose
+  (leap_client)% export NOSE_REDNOSE=1
+
+Testing all the supported python versions
+-----------------------------------------
+
+For running testsuite against all the supported python versions (currently 2.6 and 2.7), run::
+
+  % tox -v
+
+Coverage reports
+----------------
+
+Pass the ``-c`` flat to the ``run_tests.sh`` script::
+
+    $ run_tests.sh -c
+
+Using ``coverage`` it will generate beautiful html reports that you can access pointing your browser to ``docs/covhtml/index.html``
+
+.. note::
+   The coverage reports will not be generated if all tests are not passing.
diff --git a/docs/dev/todo.rst b/docs/dev/todo.rst
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/docs/dev/todo.rst
diff --git a/docs/dev/workflow.rst b/docs/dev/workflow.rst
new file mode 100644
index 00000000..3f773712
--- /dev/null
+++ b/docs/dev/workflow.rst
@@ -0,0 +1,8 @@
+.. _workflow:
+
+Development Workflow
+====================
+
+This section documents the workflow that the LEAP project team follows and expects for the code contributions.
+
+XXX