Import Upstream version 0.5.0+dfsg

1 files changed, 203 insertions, 0 deletions

diff --git a/doc/source/virtualenv.rst b/doc/source/virtualenv.rst
new file mode 100644
index 0000000..db8058d
--- /dev/null
+++ b/doc/source/virtualenv.rst
@@ -0,0 +1,203 @@
+
+.. _silx-venv:
+
+Installing silx in a virtualenv
+===============================
+
+This step-by-step guide explains how to install *silx* in a virtualenv.
+
+
+Prerequisites
+-------------
+
+This guide assumes that your system meets the following requirements:
+
+   - a version of python compatible with *silx* is installed (python 2.7 or python >= 3.5)
+   - the *pip* installer for python packages is installed
+   - the Qt and PyQt libraries are installed (optional, required for using ``silx.gui``)
+
+Installation procedure
+----------------------
+
+
+Install vitrualenv
+******************
+
+.. code-block:: bash
+
+    pip install virtualenv --user
+
+.. note::
+
+    This step is not required for recent version of Python 3.
+    Virtual environments are created using a builtin standard library,
+    ``venv``.
+    On Debian platforms, you might need to install the ``python3-venv``
+    package.
+
+
+Create a virtualenv
+*******************
+
+The files required by a virtual environment are created in a new folder
+with the same name as the virtualenv. So make sure you are in a directory
+in which you have write permissions.
+
+In this tutorial we use a folder ``venvs`` in our home directory, and we create
+a virtual environment named ``silx_venv``
+
+.. code-block:: bash
+
+    cd
+    mkdir -p venvs
+    cd venvs
+    virtualenv silx_venv
+
+
+A virtualenv contains a copy of your default python interpreter with a few tools
+to install packages (pip, setuptools).
+
+To use a different python interpreter, you can specify it on the command line.
+For example, to use python 3.4:
+
+.. code-block:: bash
+
+    virtualenv -p /usr/bin/python3.4 silx_venv
+
+But for python 3  you should use the builtin ``venv`` module:
+
+.. code-block:: bash
+
+    python3 -m venv /path/to/new/virtual/environment
+
+.. note::
+
+    If you don't need to start with a clean environment and you don't want
+    to install each required library one by one, you can use a command line
+    option to create a virtualenv with access to all system packages:
+    ``--system-site-packages``
+
+
+Activate a virtualenv
+*********************
+
+A script is provided in your virtualenv to activate it.
+
+.. code-block:: bash
+
+    source silx_venv/bin/activate
+
+After activating your new virtualenv, this python interpreter and its
+package tools are used, instead of the ones from the system.
+
+Any libraries you will install or upgrade will be inside the virtual
+environment, and will not affect the rest of system.
+
+To deactivate the virtual environment, just type ``deactivate``.
+
+Upgrade pip
+***********
+
+After activating *silx_venv*, you should upgrade *pip*:
+
+.. code-block:: bash
+
+    python -m pip install --upgrade pip
+
+
+Upgrade setuptools and wheel
+****************************
+
+Upgrading the python packaging related libraries can make installing the
+rest of the libraries much easier.
+
+.. code-block:: bash
+
+    pip install setuptools --upgrade
+    pip install wheel --upgrade
+
+Install build dependencies
+**************************
+
+The following command installs libraries that are required to build and
+install *silx*:
+
+.. code-block:: bash
+
+    pip install numpy cython
+
+.. since 0.5, numpy is now automatically installed when doing `pip install silx`
+
+Install optional dependencies
+*****************************
+
+The following command installs libraries that are needed by various modules
+of *silx*:
+
+.. code-block:: bash
+
+    pip install matplotlib fabio h5py
+
+The next command installs libraries that are used by the python modules
+handling parallel computing:
+
+.. code-block:: bash
+
+    pip install pyopencl mako
+
+
+Install pyqt
+************
+
+If your python version is 3.5 or newer, installing PyQt5 and all required packages
+is as simple as typing:
+
+.. code-block:: bash
+
+    pip install PyQt5
+
+For previous versions of python, there are no PyQt wheels available, so the installation
+is not as simple.
+
+The simplest way, assuming that PyQt is installed on your system, is to use that
+system package directly. For this, you need to add a symbolic link to your virtualenv.
+
+If you want to use PyQt4 installed in ``/usr/lib/python2.7/dist-packages/``, type:
+
+.. code-block:: bash
+
+    ln -s /usr/lib/python2.7/dist-packages/PyQt4 silx_venv/lib/python2.7/site-packages/
+    ln -s /usr/lib/python2.7/dist-packages/sip.so silx_venv/lib/python2.7/site-packages/
+
+
+Install silx
+************
+
+.. code-block:: bash
+
+    pip install silx
+
+
+To test *silx*, open an interactive python console. If you managed to install PyQt or PySide
+in your virtualenv, type:
+
+.. code-block:: bash
+
+    python
+
+If you don't have PyQt, use:
+
+.. code-block:: bash
+
+    WITH_QT_TEST=False python
+
+Run the test suite using:
+
+    >>> import silx.test
+    >>> silx.test.run_tests()
+
+
+
+
+
+