Merge pull request #4622 from kmaehashi/update-install-guide

rewrite installation guide to align with CuPy's installation guide
chainer · Apr 16, 2018 · b1b6566 · b1b6566
2 parents 04b6068 + dc51526
commit b1b6566
Showing 1 changed file with 63 additions and 95 deletions.
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -6,61 +6,64 @@ Installation
 Recommended Environments
 ------------------------
 
-We recommend these Linux distributions.
+We recommend the following Linux distributions.
 
-* `Ubuntu <https://www.ubuntu.com/>`__ 14.04/16.04 LTS 64bit
-* `CentOS <https://www.centos.org/>`__ 7 64bit
-
-The following versions of Python can be used: 2.7.6+, 3.4.3+, 3.5.1+, and 3.6.0+.
+* `Ubuntu <https://www.ubuntu.com/>`_ 14.04 / 16.04 LTS (64-bit)
+* `CentOS <https://www.centos.org/>`_ 7 (64-bit)
 
 .. note::
 
-   We are testing Chainer automatically with Jenkins, where all the above *recommended* environments are tested.
-   We cannot guarantee that Chainer works on other environments including Windows and macOS (especially with CUDA support), even if Chainer looks running correctly.
-
+   We are automatically testing Chainer on all the recommended environments above.
+   We cannot guarantee that Chainer works on other environments including Windows and macOS (especially with CUDA support), even if Chainer may seem to be running correctly.
 
 
-Dependencies
+Requirements
 ------------
 
-Before installing Chainer, we recommend to upgrade ``setuptools`` if you are using an old one::
+You need to have the following components to use Chainer.
 
-  $ pip install -U setuptools
+* `Python <https://python.org/>`_
+    * Supported Versions: 2.7.6+, 3.4.3+, 3.5.1+ and 3.6.0+.
+* `NumPy <http://www.numpy.org/>`_
+    * Supported Versions: 1.9, 1.10, 1.11, 1.12 and 1.13.
+    * NumPy will be installed automatically during the installation of Chainer.
 
-The following Python packages are required to install Chainer.
-The latest version of each package will automatically be installed if missing.
+Before installing Chainer, we recommend you to upgrade ``setuptools`` and ``pip``::
 
-* `NumPy <http://www.numpy.org/>`__ 1.9, 1.10, 1.11, 1.12, 1.13
-* `Six <https://pythonhosted.org/six/>`__ 1.9+
+  $ pip install -U setuptools pip
 
-The following packages are optional dependencies.
-Chainer can be installed without them, in which case the corresponding features are not available.
+Hardware Acceleration Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* CUDA/cuDNN support
+You can accelerate performance of Chainer by installing the following optional components.
 
-  * `cupy <https://cupy.chainer.org/>`__ 4.0+
+* NVIDIA CUDA / cuDNN
+    * `CuPy <https://cupy.chainer.org/>`_ 4.0+
+    * See `Installation Guide <https://cupy.chainer.org/en/latest/install.html>`__ for instructions.
 
-* Caffe model support
+* Intel CPU (experimental)
+    * `iDeep <https://github.com/intel/ideep>`_ 1.0.3+
+    * See :doc:`tips` for instructions.
 
-  * `protobuf <https://developers.google.com/protocol-buffers/>`__ 3.0+
+Optional Features
+~~~~~~~~~~~~~~~~~
 
-* Image dataset support
-
-  * `pillow <https://pillow.readthedocs.io/>`__ 2.3+
+The following packages are optional dependencies.
+Chainer can be installed without them, in which case the corresponding features are not available.
 
+* Image dataset support
+    * `pillow <https://pillow.readthedocs.io/>`__ 2.3+
+    * Run ``pip install pillow`` to install.
 * HDF5 serialization support
+    * `h5py <http://www.h5py.org/>`__ 2.5+
+    * Run ``pip install h5py`` to install.
 
-  * `h5py <http://www.h5py.org/>`__ 2.5+
-
-* iDeep (performance acceleration for Intel CPU) support (experimental)
-
-  * `ideep <https://github.com/intel/ideep>`__ 1.0.3+
 
 Install Chainer
 ---------------
 
-Install Chainer via pip
-~~~~~~~~~~~~~~~~~~~~~~~
+Using pip
+~~~~~~~~~
 
 We recommend to install Chainer via pip::
 
@@ -71,9 +74,8 @@ We recommend to install Chainer via pip::
    Any optional dependencies (including CuPy) can be added after installing Chainer.
    Chainer automatically detects the available packages and enables/disables the optional features appropriately.
 
-
-Install Chainer from source
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Using Tarball
+~~~~~~~~~~~~~
 
 The tarball of the source tree is available via ``pip download chainer`` or from `the release notes page <https://github.com/chainer/chainer/releases>`_.
 You can install Chainer from the tarball::
@@ -86,27 +88,12 @@ You can also install the development version of Chainer from a cloned Git reposi
   $ cd chainer
   $ pip install .
 
-
-.. _install_error:
-
-When an error occurs...
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Use ``-vvvv`` option with ``pip`` command.
-That shows all logs of installation.
-It may help you::
-
-  $ pip install chainer -vvvv
-
-
-.. _install_cuda:
-
 Enable CUDA/cuDNN support
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In order to enable CUDA support, you have to install `CuPy <https://cupy.chainer.org/>`_ manually.
 If you also want to use cuDNN, you have to install CuPy with cuDNN support.
-See `CuPy's installation guide <https://docs-cupy.chainer.org/en/latest/install.html>`_ to install CuPy.
+See `CuPy's installation guide <https://docs-cupy.chainer.org/en/latest/install.html>`__ to install CuPy.
 Once CuPy is correctly set up, Chainer will automatically enable CUDA support.
 
 You can refer to the following flags to confirm if CUDA/cuDNN support is actually available.
@@ -117,37 +104,6 @@ You can refer to the following flags to confirm if CUDA/cuDNN support is actuall
    ``True`` if cuDNN support is available.
 
 
-Support image dataset
-~~~~~~~~~~~~~~~~~~~~~
-
-Install Pillow manually to activate image dataset feature::
-
-  $ pip install pillow
-
-Note that this feature is optional.
-
-.. _hdf5-support:
-
-Support HDF5 serialization
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Install h5py manually to activate HDF5 serialization::
-
-  $ pip install h5py
-
-Before installing h5py, you need to install libhdf5.
-The way to install it depends on your environment::
-
-  # Ubuntu 14.04/16.04
-  $ apt-get install libhdf5-dev
-
-  # CentOS 7
-  $ yum -y install epel-release
-  $ yum install hdf5-devel
-
-Note that this feature is optional.
-
-
 Uninstall Chainer
 -----------------
 
@@ -194,23 +150,35 @@ Or run the interpreter directly::
   $ nvidia-docker run -it chainer/chainer /usr/bin/python
 
 
-Install Issues
---------------
-
-The installer says "hdf5.h is not found"
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You don't have libhdf5.
-Please install it first.
-See :ref:`hdf5-support`.
-
+FAQ
+---
 
-Examples say "cuDNN is not enabled"
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Warning message "cuDNN is not enabled" appears
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You failed to build CuPy with cuDNN.
 If you don't need cuDNN, ignore this message.
 Otherwise, retry to install CuPy with cuDNN.
-``-vvvv`` option helps you.
+``pip install -vvvv`` option helps you.
 There is no need of re-installing Chainer itself.
-See `CuPy's installation guide <https://docs-cupy.chainer.org/en/latest/install.html>`_ for more details.
+See `CuPy's installation guide <https://docs-cupy.chainer.org/en/latest/install.html>`__ for more details.
+
+CuPy always raises ``cupy.cuda.compiler.CompileException``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See FAQ section of `CuPy's installation guide <https://docs-cupy.chainer.org/en/latest/install.html>`__ for details.
+
+h5py installation failed
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the installation failed with error saying ``hdf5.h is not found``, you need to install ``libhdf5`` first.
+The way to install it depends on your environment::
+
+  # Ubuntu 14.04/16.04
+  $ apt-get install libhdf5-dev
+
+  # CentOS 7
+  $ yum -y install epel-release
+  $ yum install hdf5-devel
+
+Note that ``h5py`` is not required unless you need HDF5 serialization support.