Merge branch 'develop' of ssh://code.leap.se/leap_client into develop

8 files changed, 315 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..55f00d5e
--- /dev/null
+++ b/docs/dev/environment.rst
@@ -0,0 +1,111 @@
+.. _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 will be in *master* branch (nothing there yet, move on!).
+   Development code lives in *develop* branch.
+
+::
+
+    git clone git://leap.se/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<http://openvpn.net/index.php/open-source/345-openvpn-project.html>`_
+
+Debian
+^^^^^^
+In debian-based systems::
+
+  $ apt-get install openvpn python-qt4 python-crypto python-gnutls
+
+To install the software from sources::
+
+  $ apt-get install python-pip python-dev libgnutls-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/>`_. 
+
+
+Create and activate your dev environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+    $ virtualenv </path/to/new/environment>
+    $ source </path/to/new/environment>/bin/activate
+
+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
+
+.. _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<http://www.riverbankcomputing.com/software/pyqt/download>`_ and execute ``configure.py`` in the root folder of their distribution, which generates a ``Makefile``::
+
+    $ python configure.py
+    $ make && make install
+
+.. 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, ...).
+
+
+
+.. _policykit:
+
+Running openvpn without root privileges
+---------------------------------------
+
+In linux, we are using ``policykit`` to be able to run openvpn without run 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 &
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..e6b89dea
--- /dev/null
+++ b/docs/dev/internationalization.rst
@@ -0,0 +1,108 @@
+.. _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.
+
+Translating the LEAP Client PyQt Application
+--------------------------------------------
+
+.. raw:: html
+
+   <div><a target="_blank" style="text-decoration:none; color:black; font-size:66%" href="https://www.transifex.com/projects/p/leap-client/resource/leap-client/" title="See more information on Transifex.com">Top translations: leap-client » leap-client</a><br/><img border="0" src="https://www.transifex.com/projects/p/leap-client/resource/leap-client/chart/image_png"/><br/><a target="_blank" href="https://www.transifex.com/"><img border="0" src="https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.646b0065fce6.png"/></a></div>
+
+
+For translators
+^^^^^^^^^^^^^^^
+.. note::
+   We should probably move the translators info to a top level section of the docs, and leave this
+   as internal notes.
+
+
+We are using `transifex <http://transifex.com/projects/p/leap-client>`_ to coordinate translation efforts. If you want to contribute, just sign up there and ...
+
+.. note::
+   ... and what??
+
+For devs: i18n conventions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+   should say something about our special cases (provider labels and exceptions) when we get decision about it.
+
+Refer to `pyqt documentation <http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/html/i18n.html>`_.
+
+tl;dr;::
+
+     self.tr('your string')
+
+for any string that you want to be translated.
+
+.. Note about this: there seems to be some problems with the .tr method
+   on QObjects. Investigate this.
+   I still believe we can use a generic _ method which is smart enough to
+   fallback to QObject.tr methods or lookup our own tr implementation (for our
+   multilungual objects, like in exceptions or provider labels that came from json objects).
+   --kali
+
+For i18n maintainers
+^^^^^^^^^^^^^^^^^^^^
+
+You need ``pylupdate4`` for these steps. To get it, in debian::
+
+   $ apt-get install python-qt4-utils
+
+If you do not already have it, install the ``transifex-client`` from the cheese shop::
+
+   pip install  transifex-client
+
+You can learn more about the transifex-client `here <http://help.transifex.com/features/client/index.html>`_.
+
+**1.** Add any new source files to the project file, ``data/leap_client.pro``. *We should automate this with some templating, it's tedious.*
+
+**2.** Update the source .ts file ``data/ts/en_US.ts``.::
+
+   $ make translations
+
+**3.** Push source .ts file to transifex::
+
+   $ tx push -s
+
+**4.** Let the translation fairies do their work...
+
+**5.** *Et voila!* Get updated .ts files for each language from ``Transifex``. For instance, to pull updated spanish translations:: 
+
+   $ tx pull -l es
+   Pulling new translations for resource leap-client.leap-client (source: data/ts/en_US.ts)
+   -> es: data/translations/es.ts
+   Done.
+
+
+Note that there is a configuration option in ``.tx/config`` for setting the minimum completion percentage needed to be able to actually pull a resource.
+
+**6.** Generate .qm files from the updated .ts files::
+
+   $ make translations 
+
+and yes, it's the same command than in step 2. One less thing to remember :)
+
+**7.** Check that the .qm for the language you're working with is listed in ``data/resources/locale.qrc`` file. That should take the translated files from ``data/translations``
+
+**8.** Re-generate ``src/leap/gui/locale_qrc``. This is the embedded resource file that we load in the main app entry point; and from where we load the data for the qt translator object::
+
+    $ make resources
+
+If you want to try it, just set your LANG environment variable::
+
+    $ LANG=es_ES leap-client
+
+
+Translating 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