New upstream version 0.9.0+dfsg

1 files changed, 119 insertions, 148 deletions

diff --git a/doc/source/install.rst b/doc/source/install.rst
index 93b9df0..7941a7b 100644
--- a/doc/source/install.rst
+++ b/doc/source/install.rst
@@ -2,38 +2,71 @@
 Installation steps
 ==================
 
-*silx* supports most operating systems, different version of the Python
+*silx* supports most operating systems and different versions of the Python
 programming language.
-While `numpy <http://www.numpy.org/>`_ is the only mandatory dependency,
-graphical widgets require Qt, management of data files requires
-`h5py <http://docs.h5py.org/en/latest/build.html>`_ and
-`fabio <https://github.com/silx-kit/fabio>`_, and high performance data-analysis
-code on GPU requires `pyopencl <https://mathema.tician.de/software/pyopencl/>`_.
 
-This table summarized the the support matrix of silx v0.7:
+This table summarizes the support matrix of silx:
 
 +------------+--------------+---------------------+
 | System     | Python vers. | Qt and its bindings |
 +------------+--------------+---------------------+
-| `Windows`_ | 3.5, 3.6     | PyQt5.6+            |
+| `Windows`_ | 3.5, 3.6-3.7 | PyQt5.6+, PySide2   |
 +------------+--------------+---------------------+
-| `MacOS`_   | 2.7, 3.5-3.6 | PyQt5.6+            |
+| `MacOS`_   | 2.7, 3.5-3.7 | PyQt5.6+, PySide2   |
 +------------+--------------+---------------------+
-| `Linux`_   | 2.7, 3.4-3.6 | PyQt4.8+, PyQt5.3+  |
+| `Linux`_   | 2.7, 3.4-3.7 | PyQt5.3+, PySide2   |
 +------------+--------------+---------------------+
 
-For all platform, you can install *silx* from the source, see `Installing from source`_.
+For the description of *silx* dependencies, see the Dependencies_ section.
+
+For all platforms, you can install *silx* with pip, see `Installing with pip`_.
 
 To install *silx* in a `Virtual Environment`_, there is short version here-after
-and  a `longer description :ref:`silx-venv`.
+and  a longer description: :ref:`silx-venv`.
+
+You can also install *silx* from the source, see `Installing from source`_.
+
+
+Installing with pip
+-------------------
+
+To install silx (and all its dependencies_), run:
+
+.. code-block:: bash
+
+    pip install silx[full]
+
+To install silx with a minimal set of dependencies, run:
+
+.. code-block:: bash
+
+    pip install silx
+
+.. note::
+
+    Use pip's ``--user`` option to install locally for the current user.
+
+.. note::
+
+    - If numpy is not yet installed, you might need to install it first.
+    - Replace the ``pip`` command with ``pip3`` to install *silx* or any other library for Python 3.
+
 
 Dependencies
 ------------
 
+.. _dependencies:
+
+The mandatory dependencies are:
+
+- `numpy <http://www.numpy.org/>`_
+- `h5py <http://docs.h5py.org/en/latest/build.html>`_
+- `fabio <https://github.com/silx-kit/fabio>`_
+
 The GUI widgets depend on the following extra packages:
 
-* A Qt binding: either `PyQt5, PyQt4 <https://riverbankcomputing.com/software/pyqt/intro>`_,
-  `PySide <https://pypi.python.org/pypi/PySide/>`_, or `PySide2 <https://wiki.qt.io/PySide2>`_
+* A Qt binding: either `PyQt5 <https://riverbankcomputing.com/software/pyqt/intro>`_,
+  or `PySide2 <https://wiki.qt.io/Qt_for_Python>`_
 * `matplotlib <http://matplotlib.org/>`_
 * `PyOpenGL <http://pyopengl.sourceforge.net/>`_
 * `qt_console <https://pypi.python.org/pypi/qtconsole>`_
@@ -45,13 +78,13 @@ Tools for reading and writing files depend on the following packages:
 * `h5py <http://docs.h5py.org/en/latest/build.html>`_ for HDF5 files
 * `fabio <https://github.com/silx-kit/fabio>`_ for multiple image formats
 
-*silx.opencl* further depends on OpenCL and the following packages to :
+*silx.opencl* further depends on OpenCL and the following packages too :
 
 * `pyopencl <https://mathema.tician.de/software/pyopencl/>`_
 * `Mako <http://www.makotemplates.org/>`_
 
 The complete list of dependencies with the minimal version is described in the
-`requirement.txt <https://github.com/silx-kit/silx/blob/0.7/requirements.txt>`_
+`requirement.txt <https://github.com/silx-kit/silx/blob/0.8/requirements.txt>`_
 at the top level of the source package.
 
 Build dependencies
@@ -64,63 +97,36 @@ On Windows it is recommended to use Python 3.5, because with previous versions
 of Python, it might be difficult to compile extensions (i.e. binary modules).
 
 This project uses Cython (version > 0.21) to generate C files.
-Cython is now mandatory to build *silx* from the development branch and is only
-needed when compiling binary modules.
+Cython is mandatory to build *silx* from the development branch.
 
 The complete list of dependencies for building the package, including its
 documentation, is described in the
-`requirement-dev.txt <https://github.com/silx-kit/silx/blob/0.7/requirements-dev.txt>`_
+`requirement-dev.txt <https://github.com/silx-kit/silx/blob/0.8/requirements-dev.txt>`_
 at the top level of the source package.
 
 
-
 Linux
 -----
 
-If NumPy is not installed on your system, you need to install it first,
-preferably with the package manager of your system.
-If you cannot use the package manager of your system (which requires the root
-access), please refer to the `Virtual Environment`_ procedure.
-
-On Linux, you can install *silx* in your home directory
-
-.. code-block:: bash 
-
-    pip install silx --user
-
-.. note::
-    
-    Replace the ``pip`` command with ``pip3`` to install *silx* or any other library for Python 3.
-
-.. note::
-    
-    This installs *silx* without the optional dependencies. 
-    
-To install *silx* on Debian or Ubuntu systems, see `Installing a Debian package`_.
-This method requires **sudo** privileges, but has the benefit of installing
-dependencies in a simple way.
-
-`CentOS 7 RPM packages <http://pubrepo.maxiv.lu.se/rpm/el7/x86_64/>`_ and
-`Fedora 23 rpm packages <http://pubrepo.maxiv.lu.se/rpm/fc23/x86_64/>`_
-are provided by the Max IV institute at Lund, Sweden.
-
-An `Arch Linux (AUR) package <https://aur.archlinux.org/packages/python-silx>`_
-is provided by Leonid Bloch.
+Packages are available for a few distributions:
 
-You can also choose to compile and install *silx* from it's sources:
-see `Installing from source`_.
+- Debian 8: see `Installing a Debian package`_.
+- `CentOS 7 RPM packages <http://pubrepo.maxiv.lu.se/rpm/el7/x86_64/>`_ provided by the Max IV institute at Lund, Sweden.
+- `Fedora 23 rpm packages <http://pubrepo.maxiv.lu.se/rpm/fc23/x86_64/>`_ provided by the Max IV institute at Lund, Sweden.
+- `Arch Linux (AUR) package <https://aur.archlinux.org/packages/python-silx>`_ provided by Leonid Bloch.
 
-.. note::
+You can also follow one of those installation procedures:
 
-    The Debian packages `python-silx` and `python3-silx` will not install executables 
-    (`silx view`, `silx convert` ...). Please install the silx package.  
+- `Installing with pip`_
+- Installing in a `Virtual Environment`_
+- `Installing from source`_
 
 
 Installing a Debian package
 +++++++++++++++++++++++++++
 
 Debian 8 (Jessie) packages are available on http://www.silx.org/pub/debian/ for amd64 computers.
-To install it, you need to download this file
+To install it, you need to download this file :
 
 .. code-block:: bash 
 
@@ -136,6 +142,9 @@ Then run ``apt-get update`` and ``apt-get install python-silx``
    sudo apt-get update
    sudo apt-get install python-silx python3-silx silx
 
+The `python-silx` and `python3-silx` packages provide the library,
+while the `silx` package provides the executable (`silx view`, `silx convert` ...).
+
 .. note::
     
     The packages are built automatically, hence not signed. 
@@ -147,88 +156,42 @@ If the Pin-number of silx.org is too low compared to other sources:
 download http://www.silx.org/pub/debian/silx.pref into /etc/apt/preferences.d
 and start the update/install procedure again.
 
-Virtual Environment
--------------------
-
-Virtual environments are self-contained directory tree that contains a Python
-installation for a particular version of Python, plus a number of additional
-packages.
-They do require administrator privileges, nor *root* access.
-
-To create a virtual environment, decide upon a directory where you want to place
-it (for example *myenv*), and run the *venv* module as a script with the directory path:
-
-.. code-block:: bash 
-
-    python3 -m venv  myenv
-
-This will create the *myenv* directory if it doesn’t exist, and also create
-directories inside it containing a copy of the Python interpreter, the standard
-library, and various supporting files.
-
-Once you’ve created a virtual environment, you may activate it.
-
-On Windows, run:
-
-.. code-block:: bash 
-
-  myenv\\Scripts\\activate.bat
-
-On Unix or MacOS, run:
-
-.. code-block:: bash 
-
-   source myenv/bin/activate
-
-You can install, upgrade, and remove packages using a program called *pip* within
-your virtual environment.
-
-.. code-block:: bash 
-
-    pip install numpy
-    pip install -r https://github.com/silx-kit/silx/raw/0.7/requirements.txt
-    pip install silx
     
 Windows
 -------
 
-The simple way of installing the *silx* library on Windows is to type the following
-commands in a command prompt:
+The simplest way of installing *silx* on Windows is to install it with ``pip``, see `Installing with pip`_::
 
-.. code-block:: bash
+    pip install silx[full]
 
-    pip install silx
-  
-.. note::
-    
-    This installs *silx* without the optional dependencies.
-    Instructions on how to install dependencies are given in the
-    `Installing dependencies`_ section.
-    
-This assumes you have Python and pip installed and configured. If you don't,
-read the following sections.
+This assumes you have Python and pip installed and configured.
+If you don't, read the following sections.
+
+Alternatively, you can check:
 
+- Installing in a `Virtual Environment`_
+- `Installing from source`_
 
 Installing Python
 +++++++++++++++++
 
 Download and install Python from `python.org <https://www.python.org/downloads/>`_.
 
-We recommend that you install the 64bits version of Python, which is not the
+We recommend that you install the 64bit version of Python, which is not the
 default version suggested on the Python website.
-The 32bits version is limited to 2 GB of memory, and also we don't provide a
+The 32bit version has limited memory, and also we don't provide a
 binary wheel for it.
 This means that you would have to install *silx* from its sources, which requires
 you to install a C compiler first.
 
-We also encourage you to use Python 3.5 or newer, former versions are no more
+We also encourage you to use Python 3.5 or newer as former versions are no longer
 officially supported.
 
 Configure Python as explained on
 `docs.python.org <https://docs.python.org/3/using/windows.html#configuring-python>`_
 to add the python installation directory to your PATH environment variable.
 
-Alternative Scientific Python stacks exists, such as
+Alternative Scientific Python stacks exists such as
 `WinPython <http://winpython.github.io/>`_ or `Anaconda <https://www.anaconda.com/download/#windows>`_.
 They all offer most of the scientific packages already installed which makes the
 installation of dependencies much easier.
@@ -241,49 +204,63 @@ directory, the same way as described for Python.
 
 The pip installation directory will likely be ``C:\Python35\Scripts\``.
 
-Then you will be able to use all pip commands listed in following in a command
+Then you will be able to use all the pip commands listed below in a command
 prompt.
 
 
-Installing dependencies
-+++++++++++++++++++++++
+MacOS
+-----
 
-All dependencies may be simply installed with pip::
+While Apple ships Python 2.7 by default on their operating systems, we recommend
+using Python 3.5 or newer to ease the installation of the Qt library.
 
-.. code-block:: bash 
+Then, install *silx* with ``pip``, see `Installing with pip`_::
 
-    pip install -r https://github.com/silx-kit/silx/raw/0.7/requirements.txt
+    pip install silx[full]
 
+This should work without issues, as binary wheels of *silx* are provided on
+PyPi.
 
-Installing *silx*
-+++++++++++++++++
 
-Provided numpy is installed, you can install *silx* with::
+Virtual Environment
+-------------------
 
-.. code-block:: bash 
+Virtual environments are self-contained directory trees that contain a Python
+installation for a particular version of Python, plus a number of additional
+packages.
+They do not require administrator privileges, nor *root* access.
 
-    pip install silx
+To create a virtual environment, decide upon a directory where you want to place
+it (for example *myenv*), and run the *venv* module as a script with the directory path:
 
+.. code-block:: bash
 
-MacOS
------
+    python3 -m venv  myenv
 
-While Apple ships Python 2.7 by default on their operating systems, we recommand
-using Python 3.5 or newer to ease the installation of the Qt library.
-This can simply be performed by:
+This will create the *myenv* directory if it doesn’t exist, and also create
+directories inside it containing a copy of the Python interpreter, the standard
+library, and various supporting files.
 
-.. code-block:: bash 
+Once you’ve created a virtual environment, you may activate it.
 
-    pip install -r https://github.com/silx-kit/silx/raw/0.7/requirements.txt
+On Windows, run:
 
-Then install *silx* with:
+.. code-block:: bash
 
-.. code-block:: bash 
+  myenv\\Scripts\\activate.bat
 
-    pip install silx
+On Unix or MacOS, run:
 
-This should work without issues, as binary wheels of *silx* are provided on
-PyPi.
+.. code-block:: bash
+
+   source myenv/bin/activate
+
+You can install, upgrade, and remove packages using a program called *pip* within
+your virtual environment (see `Installing with pip`_).
+
+.. code-block:: bash
+
+    pip install silx[full]
 
 
 Installing from source
@@ -294,7 +271,7 @@ installed using:
 
 .. code-block:: bash 
 
-    pip install -r https://github.com/silx-kit/silx/raw/0.7/requirements-dev.txt
+    pip install -r https://github.com/silx-kit/silx/raw/0.8/requirements-dev.txt
 
 
 Building from source
@@ -326,8 +303,8 @@ There are specific issues related to MacOSX. If you get this error::
 
   UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 1335: ordinal not in range(128)
 
-This is related to the two environment variable LC_ALL and LANG not defined (or wrongly defined to UTF-8).
-To set the environment variable, type on the command line:
+This is related to the two environment variables LC_ALL and LANG not being defined (or wrongly defined to UTF-8).
+To set the environment variables, type on the command line:
 
 .. code-block:: bash 
 
@@ -345,18 +322,12 @@ In case you want more control over the build procedure, the build command is:
 
 There are few advanced options to ``setup.py build``:
 
-* ``--no-cython``: Prevent Cython (even if installed) to re-generate the C source code.
+* ``--no-cython``: Prevent Cython (even if installed) from re-generating the C source code.
   Use the one provided by the development team.
 * ``--no-openmp``: Recompiles the Cython code without OpenMP support (default for MacOSX).
 * ``--openmp``: Recompiles the Cython code with OpenMP support (default for Windows and Linux).
 
-Run the test suite of silx (may take a couple of minutes):
-
-.. code-block:: bash 
-
-    python run_tests.py
-
-Package the built into a wheel and install it:
+Package the build into a wheel and install it:
 
 .. code-block:: bash 
 
@@ -373,7 +344,7 @@ To build the documentation, using  `Sphinx <http://www.sphinx-doc.org/>`_:
 Testing
 +++++++
 
-To run the tests of an installed version of *silx*, from the python interpreter, run:
+To run the tests of an installed version of *silx*, run the following on the python interpreter:
 
 .. code-block:: python