imported client docs, converted to .md

5 files changed, 235 insertions, 42 deletions

diff --git a/docs/client/howto-test-dev.rst b/docs/client/bleeding-edge.md
index 31471f0..c00bcb2 100644
--- a/docs/client/howto-test-dev.rst
+++ b/docs/client/bleeding-edge.md
@@ -1,80 +1,79 @@
-@title = "HOWTO for testing latest develop branch"
+@title = "HOWTO for running latest develop branch"
+@nav_title = "Running Lastest"
 
 This document covers a how-to guide to:
 
-#. Quickly fetching latest development code, and
-#. Reporting bugs.
+1. Quickly fetching latest development code, and
+2. Reporting bugs.
 
 Let's go!
 
-.. _fetchinglatest:
-
 Fetching latest development code
----------------------------------
+=========================================
 
-To allow rapid testing in different platforms, we have put together a quick script that is able to fetch latest development code. It more or less does all the steps covered in the :ref:`Setting up a Work Enviroment <environment>` section, only that in a more compact way suitable (ahem) also for non developers.
+To allow rapid testing in different platforms, we have put together a quick script that is able to fetch latest development code. It more or less does all the steps covered in the [Setting up a Work Enviroment](client/dev-guide) section, only that in a more compact way suitable (ahem) also for non developers.
 
 Install dependencies
-^^^^^^^^^^^^^^^^^^^^
-First, install all the base dependencies plus git, virtualenv and development files needed to compile several extensions::
+-------------------------------
+
+First, install all the base dependencies plus git, virtualenv and development files needed to compile several extensions:
 
-   apt-get install openvpn git-core python-dev python-qt4 python-setuptools python-virtualenv
+    apt-get install openvpn git-core python-dev python-qt4 python-setuptools python-virtualenv
 
 
 Bootstrap script
-^^^^^^^^^^^^^^^^
-.. note::
-   This will fetch the *develop* branch. If you want to test another branch, just change it in the line starting with *pip install...*. Alternatively, bug kali so she add an option branch to a decent script.
+---------------------------------
+
+> note: This will fetch the *develop* branch. If you want to test another branch, just change it in the line starting with *pip install...*. Alternatively, bug kali so she add an option branch to a decent script.
 
-.. note::
-   This script could make use of the after_install hook. Read http://pypi.python.org/pypi/virtualenv/
+> note: This script could make use of the after_install hook. Read http://pypi.python.org/pypi/virtualenv/
 
 Download and source the following script in the parent folder where you want your testing build to be downloaded. For instance, to `/tmp/`:
 
-.. code-block:: bash
 
-   cd /tmp
-   wget https://raw.github.com/leapcode/leap_client/develop/pkg/scripts/leap_client_bootstrap.sh
-   source leap_client_bootstrap.sh
+    cd /tmp
+    wget https://raw.github.com/leapcode/leap_client/develop/pkg/scripts/leap_client_bootstrap.sh
+    source leap_client_bootstrap.sh
 
-Tada! If everything went well, you should be able to run the client by typing::
+Tada! If everything went well, you should be able to run the client by typing:
 
     bin/leap-client
 
 Noticed that your prompt changed? That was *virtualenv*. Keep reading...
 
 Activating the virtualenv
-^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------
+
 The above bootstrap script has fetched latest code inside a virtualenv, which is an isolated, *virtual* python local environment that avoids messing with your global paths. You will notice you are *inside* a virtualenv because you will see a modified prompt reminding it to you (*leap-client-testbuild* in this case).
 
-Thus, if you forget to *activate your virtualenv*, the client will not run from the local path, and it will be looking for something else in your global path. So, **you have to remember to activate your virtualenv** each time that you open a new shell and want to execute the code you are testing. You can do this by typing::
+Thus, if you forget to *activate your virtualenv*, the client will not run from the local path, and it will be looking for something else in your global path. So, **you have to remember to activate your virtualenv** each time that you open a new shell and want to execute the code you are testing. You can do this by typing:
 
     $ source bin/activate
 
 from the directory where you *sourced* the bootstrap script.
 
-Refer to :ref:`Working with virtualenv <virtualenv>` to learn more about virtualenv.
+Refer to [Working with virtualenv](client/dev-guide) to learn more about virtualenv.
 
 Copying config files
-^^^^^^^^^^^^^^^^^^^^
+----------------------------
 
-If you have never installed the ``leap-client`` globally, **you need to copy some files to its proper path before running it for the first time** (you only need to do this once). This, unless the virtualenv-based operations, will need root permissions. See :ref:`copy script files <copyscriptfiles>` and :ref:`running openvpn without root privileges <policykit>` sections for more info on this. In short::
+If you have never installed the `leap-client` globally, **you need to copy some files to its proper path before running it for the first time** (you only need to do this once). This, unless the virtualenv-based operations, will need root permissions. See [copy script files](client/dev-guide) and [running openvpn without root privileges](client/dev-guide) sections for more info on this. In short:
 
     $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/
     $ sudo mkdir -p /etc/leap
     $ sudo cp pkg/linux/resolv-update /etc/leap
 
 Local config files
-^^^^^^^^^^^^^^^^^^^
+--------------------------
 
-If you want to start fresh without config files, just move them. In linux::
+If you want to start fresh without config files, just move them. In linux:
 
     mv ~/.config/leap ~/.config/leap.old
 
 Pulling latest changes
-^^^^^^^^^^^^^^^^^^^^^^
+------------------------------
 
-You should be able to cd into the downloaded repo and pull latest changes::
+You should be able to cd into the downloaded repo and pull latest changes:
 
     (leap-client-testbuild)$ cd src/leap-client
     (leap-client-testbuild)$ git pull origin develop
@@ -82,27 +81,24 @@ You should be able to cd into the downloaded repo and pull latest changes::
 However, as a tester you are encouraged to run the whole bootstrap process from time to time to help us catching install and versioniing bugs too.
 
 Testing the packages
-^^^^^^^^^^^^^^^^^^^^
+-------------------------------
+
 When we have a release candidate for the supported platforms (Debian stable, Ubuntu 12.04 by now), we will announce also the URI where you can download the rc for testing in your system. Stay tuned!
 
 Testing the status of translations
-----------------------------------
+==================================================
 
-We need translators! You can go to `transifex <https://www.transifex.com/projects/p/leap-client/>`_, get an account and start contributing.
+We need translators! You can go to [transifex](https://www.transifex.com/projects/p/leap-client/), get an account and start contributing.
 
-If you want to check the current status of the client localization in a language other than the one set in your machine, you can do it with a simple trick (under linux). For instance, do::
+If you want to check the current status of the client localization in a language other than the one set in your machine, you can do it with a simple trick (under linux). For instance, do:
 
     $ lang=es_ES leap-client
 
 for running  LEAP Client with the spanish locales.
 
 Reporting bugs
---------------
-
-.. admonition:: Reporting better bugs
-
-   There is a great text on the art of bug reporting, that can be found `online <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_.
+=======================
 
-.. TODO add a line with ref. to running the client in debug mode...
+We use the [LEAP Client Bug Tracker](https://leap.se/code/projects/eip-client), although you can also use [Github issues](https://github.com/leapcode/leap_client/issues).
 
-We use the `LEAP Client Bug Tracker <https://leap.se/code/projects/eip-client>`_, although you can also use `Github issues <https://github.com/leapcode/leap_client/issues>`_.
\ No newline at end of file
+> There is a great text on the art of bug reporting, that can be found at http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
diff --git a/docs/client/dev-guide.md b/docs/client/dev-guide.md
new file mode 100644
index 0000000..30d62da
--- /dev/null
+++ b/docs/client/dev-guide.md
@@ -0,0 +1,107 @@
+@nav_title = 'Development Guide'
+@title = 'Setting up a development environment'
+
+This document covers how to get an enviroment ready to contribute code to the LEAP Client.
+
+Cloning the repo
+==========================
+
+> 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 below for how to install under virtualenv)
+* `openssl`
+* [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-openssl
+
+To install the software from sources:
+
+    $ apt-get install python-pip python-dev
+
+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
+
+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
+
+> this section could be completed with useful options that can be passed to the virtualenv command (e.g., to make portable paths, site-packages, ...).
+
+
+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:
+
+    $ sudo mkdir -p /etc/leap
+    $ sudo cp pkg/linux/resolv-update /etc/leap
+
+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 &
\ No newline at end of file
diff --git a/docs/client/en.md b/docs/client/en.md
index 1528437..bcb495f 100644
--- a/docs/client/en.md
+++ b/docs/client/en.md
@@ -1,3 +1,12 @@
-Not much here yet.
+@title = 'LEAP Client'
 
-* [HOWTO for testing latest develop branch](howto-test-dev)
\ No newline at end of file
+The **LEAP Client** is a GPL3 Licensed multiplatform client, written in python using PyQt4, that supports the features offered by [the LEAP Platform](platform). Currently is being tested on Linux, support for OSX and Windows will come soon.
+
+* [User guide](client/user-guide)
+* [Running latest code](client/bleeding-edge)
+* [Getting started with development](client/dev-guide)
+* [Packaging notes](client/packaging)
+
+<!--
+  * [Configuration](client/configuration)
+  * [Client API](client/client-api) -->
\ No newline at end of file
diff --git a/docs/client/packaging.md b/docs/client/packaging.md
new file mode 100644
index 0000000..f767c9f
--- /dev/null
+++ b/docs/client/packaging.md
@@ -0,0 +1,25 @@
+@title = 'Packaging'
+
+Debian
+======
+
+This section documents all related to the debian package.
+
+Dependencies
+------------
+
+* `openvpn`
+* `python-qt4`
+* `python-crypto`
+* `python setuptools`
+* `python-requests`
+* `python-openssl`
+
+These need a version that is not found in the current debian stable or in ubuntu 12.04. They will be packaged... soon.
+
+* `python-keyring`
+
+For tests
+-----------------------
+
+* `python-nose`, `python-mock`, `python-coverage`
diff --git a/docs/client/user-guide.md b/docs/client/user-guide.md
new file mode 100644
index 0000000..7c1b1aa
--- /dev/null
+++ b/docs/client/user-guide.md
@@ -0,0 +1,56 @@
+@nav_title = "User Guide"
+@title = "Client User Guide"
+
+Installation
+==================
+
+Note: currently, this does not completely work. See [testing](testing)
+
+You can get the code from LEAP public git repository
+
+    git clone git://leap.se/leap_client
+
+Or from the github mirror
+
+    git clone git://github.com/leapcode/leap_client.git
+
+Once you have grabbed a copy of the sources, you can install it into your site-packages easily
+
+    $ pyton setup.py install
+
+
+Running
+==================
+
+This document dovers how to launch the LEAP Client.
+
+Launching the client
+--------------------
+
+After a successful installation, there should be a launcher called leap-client somewhere in your path:
+
+    $ leap-client
+
+Debug mode
+----------
+
+If you are happy having lots of output in your terminal, you will like to know that you can run the client in debug mode:
+
+    $ leap-client --debug
+
+If you ask for it, you can also have all that debug info in a beautiful file ready to be attached to your bug reports:
+
+    $ leap-client --debug --logfile /tmp/leap.log
+
+> the following is broken since it will clutter your stdout with all the commands sent to the management interface. See bug #1232
+
+If you want to increment the level of verbosity passed to openvpn, you can do:
+
+    $ leap-client --openvpn-verbosity 4
+
+Options
+------------
+
+To see all the available command line options:
+
+    $ leap-client --help
\ No newline at end of file