updated documentation

* documentation reviewed after rewrite, ready for 0.2.1
* updated docstrings format to fit sphinx autodoc

1 files changed, 126 insertions, 0 deletions

diff --git a/docs/dev/environment.rst b/docs/dev/environment.rst
new file mode 100644
index 00000000..010ccc83
--- /dev/null
+++ b/docs/dev/environment.rst
@@ -0,0 +1,126 @@
+.. _environment:
+
+Setting up a development environment
+====================================
+
+This document covers how to get an enviroment ready to contribute code to the LEAP Client.
+
+Cloning the repo
+----------------
+.. note::
+   Stable releases are in *master* branch.
+   Development code lives in *develop* branch.
+
+::
+
+    git clone git://leap.se/leap_client 
+    git checkout develop
+
+Base Dependencies
+------------------
+Leap client depends on these libraries:
+
+* `python 2.6 or 2.7`
+* `qt4` libraries (see also :ref:`Troubleshooting PySide install <pysidevirtualenv>` about how to install inside your virtualenv)
+* `openssl`
+* `openvpn <http://openvpn.net/index.php/open-source/345-openvpn-project.html>`_
+
+Debian
+^^^^^^
+In debian-based systems::
+
+  $ apt-get install openvpn python-pyside python-openssl
+
+To install the software from sources::
+
+  $ apt-get install python-pip python-dev
+
+.. _virtualenv:
+
+Working with virtualenv
+-----------------------
+
+Intro
+^^^^^^^^^^^^^^^^^^^
+
+*Virtualenv* is the *Virtual Python Environment builder*.
+
+It is a tool to create isolated Python environments.
+
+The basic problem being addressed is one of dependencies and versions, and indirectly permissions. Imagine you have an application that needs version 1 of LibFoo, but another application requires version 2. How can you use both these applications? If you install everything into /usr/lib/python2.7/site-packages (or whatever your platform's standard location is), it's easy to end up in a situation where you unintentionally upgrade an application that shouldn't be upgraded.
+
+Read more about it in the `project documentation page <http://pypi.python.org/pypi/virtualenv/>`_. 
+
+.. note::
+   this section could be completed with useful options that can be passed to the virtualenv command (e.g., to make portable paths, site-packages, ...). We also should document how to use virtualenvwrapper.
+
+
+
+Create and activate your dev environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+    $ virtualenv </path/to/new/environment>
+    $ source </path/to/new/environment>/bin/activate
+
+.. _pysidevirtualenv:
+
+Avoid compiling PySide inside a virtualenv
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you attempt to install PySide inside a virtualenv as part of the rest of the dependencies using pip, basically it will take ages to compile.
+
+As a workaround, you can run the following script after creating your virtualenv. It will symlink to your global PySide 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 PySide globally and pass the ``--site-packages`` option when you are creating your virtualenv::
+
+    $ apt-get install python-pyside
+    $ virtualenv --site-packages .
+
+After that, you must export ``LEAP_VENV_SKIP_PYSIDE`` to skip the isntallation::
+
+    $ export LEAP_VENV_SKIP_PYSIDE=1
+
+And now you are ready to proceed with the next section.
+
+.. _pydepinstall:
+
+Install python dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can install python dependencies with ``pip``. If you do it inside your working environment, they will be installed avoiding the need for administrative permissions::
+
+    $ pip install -r pkg/requirements.pip
+
+
+.. _copyscriptfiles:
+
+Copy script files
+-----------------
+
+The openvpn invocation expects some files to be in place. If you have not installed `leap-client` from a debian package, you must copy these files manually by now::
+
+    $ sudo mkdir -p /etc/leap
+    $ sudo cp pkg/linux/resolv-update /etc/leap 
+
+.. _policykit:
+
+Running openvpn without root privileges
+---------------------------------------
+
+In linux, we are using ``policykit`` to be able to run openvpn without root privileges, and a policy file is needed to be installed for that to be possible.
+The setup script tries to install the policy file when installing the client system-wide, so if you have installed the client in your global site-packages at least once it should have copied this file for you. 
+
+If you *only* are running the client from inside a virtualenv, you will need to copy this file by hand::
+
+    $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/
+
+
+Missing Authentication agent
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are running a desktop other than gnome or unity, you might get an error saying that you are not running the authentication agent. You can launch it like this::
+
+    /usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1 &