updated documentation

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

8 files changed, 388 insertions, 0 deletions

diff --git a/docs/dev/authors.rst b/docs/dev/authors.rst
new file mode 100644
index 00000000..db32bd94
--- /dev/null
+++ b/docs/dev/authors.rst
@@ -0,0 +1,8 @@
+.. _authors:
+
+Authors
+=======
+
+We are many.
+We are legion.
+
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 &
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..1a9af0be
--- /dev/null
+++ b/docs/dev/internationalization.rst
@@ -0,0 +1,117 @@
+.. _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, as long as the instance derives from ``QObject``.
+
+If you have to translate something that it is not a ``QObject``, use the magic leap ``translate`` method:
+
+
+.. code-block:: python
+
+   from leap.util.translations import translate
+
+   class Foo(object):
+        bar = translate(<Context>, <string>, <comment>)
+
+
+.. Note about this: there seems to be some problems with the .tr method
+   so the translate method could actually be the preferred thing in all the cases.
+   Still missing what to do for language labels (json-based).
+   --kali
+
+For i18n maintainers
+^^^^^^^^^^^^^^^^^^^^
+
+You need ``pylupdate4`` and ``lrelease`` for these steps. To get it, in debian::
+
+   $ apt-get install pyqt4-dev-tools qt4-linguist-tools
+
+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..c50eac09
--- /dev/null
+++ b/docs/dev/todo.rst
@@ -0,0 +1,6 @@
+.. _todo:
+
+To-Do
+=====
+
+alot
diff --git a/docs/dev/workflow.rst b/docs/dev/workflow.rst
new file mode 100644
index 00000000..e36431ff
--- /dev/null
+++ b/docs/dev/workflow.rst
@@ -0,0 +1,43 @@
+.. _workflow:
+
+Development Workflow
+====================
+
+This section documents the workflow that the LEAP project team follows and expects for the code contributions.
+
+Code formatting
+---------------
+In one word: `PEP8`_.
+
+`autopep8` might be your friend. or eat your code.
+
+.. _`PEP8`: http://www.python.org/dev/peps/pep-0008/
+.. _`autopep8`: http://pypi.python.org/pypi/autopep8
+
+Dependencies
+------------
+If you introduce a new dependency, please add it under ``pkg/requirements`` or ``pkg/test-requirements`` as appropiate, under the proper module section.
+
+Git flow
+--------
+We are basing our workflow on what is described in `A successful git branching model <http://nvie.com/posts/a-successful-git-branching-model/>`_.
+
+.. image:: https://leap.se/code/attachments/13/git-branching-model.png
+
+The author of the aforementioned post has also a handy pdf version of it: `branching_model.pdf`_ 
+
+However, we use a setup in which each developer maintains her own feature branch in her private repo. After a code review, this feature branch is rebased onto the authoritative integration branch. Thus, the leapcode repo in leap.se (mirrored in github) only maintains the master and develop branches.
+
+A couple of tools that help to follow this process are  `git-flow`_ and `git-sweep`_.
+
+.. _`branching_model.pdf`: https://leap.se/code/attachments/14/Git-branching-model.pdf
+.. _`git-flow`: https://github.com/nvie/gitflow
+.. _`git-sweep`: http://pypi.python.org/pypi/git-sweep
+
+Code review and merges into integration branch
+-----------------------------------------------
+All code ready to be merged into the integration branch is expected to:
+
+* Have tests
+* Be documented
+* Pass existing tests: do **run_tests.sh** and **tox -v**. All feature branches are automagically built by our `buildbot farm <http://lemur.leap.se:8010/grid>`_. So please check your branch is green before merging it it to `develop`. Rebasing against the current tip of the integration when possible is preferred in order to keep a clean history.