[PATCH] docs: recommend --upgrade for all pip installations in a virtualenv

[Thomas De Schampheleire]

# HG changeset patch
# User Thomas De Schampheleire <thomas.de.schampheleire at gmail.com>
# Date 1499363262 -7200
#      Thu Jul 06 19:47:42 2017 +0200
# Node ID f6b65ef9256699f055795e8309cd7aa4cf719a62
# Parent  8b265e5f9e07aa47c9a1201c4705bc576938e3ae
docs: recommend --upgrade for all pip installations in a virtualenv

As suggested by Mads Kiilerich.

Don't recommend this practice when no virtualenv is used, i.e. root
installation or --user installation: in this case upgrading existing
packages may be too disruptive. The user can still add it manually if he so
chooses.

diff --git a/docs/contributing.rst b/docs/contributing.rst
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -35,8 +35,8 @@ To get started with Kallithea developmen
         virtualenv ../kallithea-venv
         source ../kallithea-venv/bin/activate
         pip install --upgrade pip setuptools
-        pip install -e .
-        pip install -r dev_requirements.txt
+        pip install --upgrade -e .
+        pip install --upgrade -r dev_requirements.txt
         gearbox make-config my.ini
         gearbox setup-db -c my.ini --user=user --email=user at example.com --password=password --repos=/tmp
         gearbox serve -c my.ini --reload &
diff --git a/docs/installation.rst b/docs/installation.rst
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -56,7 +56,7 @@ repository, follow the instructions belo
         virtualenv ../kallithea-venv
         . ../kallithea-venv/bin/activate
         pip install --upgrade pip setuptools
-        pip install -e .
+        pip install --upgrade -e .
         python2 setup.py compile_catalog   # for translation of the UI
 
 You can now proceed to :ref:`setup`.
@@ -91,8 +91,8 @@ An additional benefit of virtualenv_ is 
 .. note:: Some dependencies are optional. If you need them, install them in
    the virtualenv too::
 
-     pip install psycopg2
-     pip install python-ldap
+     pip install --upgrade psycopg2
+     pip install --upgrade python-ldap
 
    This might require installation of development packages using your
    distribution's package manager.
@@ -104,12 +104,12 @@ An additional benefit of virtualenv_ is 
 
 - Go into the created directory and run this command to install Kallithea::
 
-    pip install kallithea
+    pip install --upgrade kallithea
 
   Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea,
   extract it and run::
 
-    pip install .
+    pip install --upgrade .
 
 - This will install Kallithea together with all other required
   Python libraries into the activated virtualenv.
diff --git a/docs/upgrade.rst b/docs/upgrade.rst
--- a/docs/upgrade.rst
+++ b/docs/upgrade.rst
@@ -85,7 +85,7 @@ If you originally installed from version
 
     cd my-kallithea-clone
     hg pull -u
-    pip install -e .
+    pip install --upgrade -e .
 
 
 5. Upgrade your configuration