[PATCH] docs/installation: clarify and reorder alternative installation methods

[Thomas De Schampheleire]

# HG changeset patch
# User Thomas De Schampheleire <thomas.de.schampheleire at gmail.com>
# Date 1426453734 -3600
#      Sun Mar 15 22:08:54 2015 +0100
# Node ID 0e43ad4a28cdaa4218ccacea0963c7bf0a1a3b9f
# Parent  5e66d3ec9880073b78653861518fe810c3bb1754
docs/installation: clarify and reorder alternative installation methods

- Add an introduction describing the different installation methods and their
pros/cons.

- Clarify that Python 3.x is not currently supported.

- Move standard pip install method as last method, and rename as also in
  virtualenv we are installing from Python Package Index.

diff --git a/docs/installation.rst b/docs/installation.rst
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -4,17 +4,38 @@
 Installation on Unix/Linux
 ==========================
 
-**Kallithea** is written entirely in Python.  Kallithea requires Python version
-2.6 or higher.
+**Kallithea** is written entirely in Python and requires Python version
+2.6 or higher. Python 3.x is not currently supported.
 
-.. Note:: Alternative very detailed installation instructions for Ubuntu Server
-   with celery, indexer and daemon scripts: https://gist.github.com/4546398
+There are several ways to install Kallithea:
 
-Installing Kallithea from repository source
--------------------------------------------
+- :ref:`installation-source`: the Kallithea development repository is stable
+  and can be used in production. In fact, the Kallithea maintainers actually do
+  use it in production. The advantage of installation from source and regularly
+  updating it is that you take advantage of the most recent improvements, which
+  is particularly useful because Kallithea is evolving rapidly.
 
-The Kallithea development repository is stable and can be used in production.
-Follow these instructions::
+- :ref:`installation-virtualenv`: if you prefer to use only released versions
+  of Kallithea, the recommended method is to install Kallithea in a virtual
+  Python environment using `virtualenv`. The advantages of this method over
+  installation via `pip` is that Kallithea and its dependencies is completely
+  contained inside the virtualenv (which also means you can remove it entirely
+  by just removing the virtualenv directory) and does not require root
+  privileges.
+
+- :ref:`installation-without-virtualenv`: the alternative method of installing
+  a Kallithea release is using standard pip. The package will be installed in
+  the same location as all other Python packages you have ever installed. As a
+  result, removing it is not as straightforward as with a virtualenv, as you'd
+  have to remove its dependencies manually and make sure that these dependencies
+  are not needed for other packages.
+
+.. _installation-source:
+
+Installation from repository source
+-----------------------------------
+
+To install Kallithea from source, follow the below instructions::
 
         hg clone https://kallithea-scm.org/repos/kallithea
         cd kallithea
@@ -22,21 +43,17 @@
         source ../kallithea-venv/bin/activate
         python setup.py develop
 
+As you can see, we're using a virtualenv here too.
+
 You can now proceed to :ref:`setup`.
 
 To upgrade, simply update the repository with ``hg pull -u`` and restart the
 server.
 
-Installing Kallithea from Python Package Index (PyPI)
------------------------------------------------------
+.. _installation-virtualenv:
 
-**Kallithea** can be installed from PyPI with::
-
-    pip install kallithea
-
-
-Installation in virtualenv
---------------------------
+Installation of a release in a virtualenv
+-----------------------------------------
 
 It is highly recommended to use a separate virtualenv_ for installing Kallithea.
 This way, all libraries required by Kallithea will be installed separately from your
@@ -78,6 +95,24 @@
 - This will install Kallithea together with pylons and all other required
   python libraries into the activated virtualenv.
 
+You can now proceed to :ref:`setup`.
+
+.. _installation-without-virtualenv:
+
+Installing of a release without virtualenv
+------------------------------------------
+
+If for some reason you do not want to follow the recommendation of installing
+Kallithea in a virtualenv, then you can install it directly using::
+
+    pip install kallithea
+
+Note that this method requires root privileges. To install as a regular user,
+you can use::
+
+    pip install --user kallithea
+
+You can now proceed to :ref:`setup`.
 
 Requirements for Celery (optional)
 ----------------------------------