Merge pull request #7877 from minrk/install-doc

update install doc

docs/source/install/install.rst

@@ -2,29 +2,27 b' IPython requires Python 2.7 or \xe2\x89\xa5 3.3.'
 
 .. note::
 
-    If you need to use Python 2.6 or 3.2, you can find IPython 1.0
-    `here <http://archive.ipython.org/release/>`__.
+    If you need to use Python 2.6 or 3.2, you can find IPython 1.x
+    `here <http://archive.ipython.org/release/>`__,
+    or get it with pip::
+    
+        pip install 'ipython<2'
+
 
 Quickstart
 ==========
 
-If you have :mod:`setuptools`,
+If you have :mod:`pip`,
 the quickest way to get up and running with IPython is:
 
 .. code-block:: bash
 
     $ pip install "ipython[all]"
 
-This will download and install IPython and its main optional dependencies:
-
-- jinja2, needed for the notebook
-- sphinx, needed for nbconvert
-- pyzmq, needed for IPython's parallel computing features, qt console and
-  notebook
-- pygments, used by nbconvert and the Qt console for syntax highlighting
-- tornado, needed by the web-based notebook
-- nose, used by the test suite
-- readline (on OS X) or pyreadline (on Windows), needed for the terminal
+This will download and install IPython and its main optional dependencies for the notebook,
+qtconsole, tests, and other functionality.
+Some dependencies (Qt, PyQt for the QtConsole, pandoc for nbconvert) are not pip-installable,
+and will not be pulled in by pip.
 
 To run IPython's test suite, use the :command:`iptest` command:
 
@@ -53,11 +51,6 b' In many scenarios, this is the simplest method of installing Python packages.'
 More information about :mod:`pip` can be found on
 `its PyPI page <http://pypi.python.org/pypi/pip>`__.
 
-.. note::
-
-   On Windows, IPython *requires* :mod:`setuptools`.  We hope to
-   change this in the future, but for now on Windows, you *must* install
-   :mod:`setuptools` to use IPython.
 
 More general information about installing Python packages can be found in
 `Python's documentation <http://docs.python.org>`_.
@@ -71,16 +64,14 b' with no external dependencies. However, some Python distributions'
 (particularly on Windows and OS X), don't come with a working :mod:`readline`
 module.  The IPython shell will work without :mod:`readline`, but will lack
 many features that users depend on, such as tab completion and command line
-editing.  If you install IPython with :mod:`setuptools`, (e.g. with
-`pip`), then the appropriate :mod:`readline` for your platform will be
-installed.  See below for details of how to make sure you have a working
-:mod:`readline`.
+editing.  If you install IPython with :mod:`pip`,
+then the appropriate :mod:`readline` for your platform will be installed.
+See below for details of how to make sure you have a working :mod:`readline`.
 
 Installation using pip
 ----------------------
 
-If you have :mod:`setuptools` or :mod:`pip`, the easiest way of getting IPython is
-to simply use :command:`pip`:
+If you have :mod:`pip`, the easiest way of getting IPython is:
 
 .. code-block:: bash
 
@@ -93,7 +84,7 b' Installation from source'
 ------------------------
 
 If you don't want to use :command:`pip`, or don't have it installed,
-just grab the latest stable build of IPython from `here
+grab the latest stable build of IPython from `here
 <http://ipython.org/download.html>`_.  Then do the following:
 
 .. code-block:: bash
@@ -105,42 +96,14 b' just grab the latest stable build of IPython from `here'
 If you are installing to a location (like ``/usr/local``) that requires higher
 permissions, you may need to run the last command with :command:`sudo`.
 
-Windows
--------
-
-As mentioned above, on Windows, IPython requires :mod:`setuptools`, and it also
-requires the PyReadline library to properly support coloring and keyboard
-management (features that the default windows console doesn't have).  So on
-Windows, the installation procedure is:
-
-1. Install `setuptools <http://pypi.python.org/pypi/setuptools>`_.
 
-2. Install `pyreadline <http://pypi.python.org/pypi/pyreadline>`_.  You can use
-   the command ``pip install pyreadline`` from a terminal, or the binary
-   installer appropriate for your platform from the PyPI page.
 
-3. Install IPython itself, which you can download from `PyPI
-   <http://pypi.python.org/pypi/ipython>`_ or from `our site
-   <http://ipython.org/download.html>`_.  Note that on Windows 7, you *must*
-   right-click and 'Run as administrator' for the Start menu shortcuts to be
-   created.
-
-IPython by default runs in a terminal window, but the normal terminal
-application supplied by Microsoft Windows is very primitive.  You may want to
-download the excellent and free Console_ application instead, which is a far
-superior tool.  You can even configure Console to give you by default an
-IPython tab, which is very convenient to create new IPython sessions directly
-from the working terminal.
-
-.. _Console:  http://sourceforge.net/projects/console
-
-   
 Installing the development version
 ----------------------------------
 
 It is also possible to install the development version of IPython from our
 `Git <http://git-scm.com/>`_ source code repository.  To do this you will
-need to have Git installed on your system.  Then just do:
+need to have Git installed on your system.  Then do:
 
 .. code-block:: bash
 
@@ -149,18 +112,16 b' need to have Git installed on your system. Then just do:'
     $ python setup.py install
 
 Some users want to be able to follow the development branch as it changes.  If
-you have :mod:`setuptools` installed, this is easy. Simply replace the last
-step by:
+you have :mod:`pip`, you can replace the last step by:
 
 .. code-block:: bash
 
-    $ python setupegg.py develop
+    $ pip install -e .
 
 This creates links in the right places and installs the command line script to
 the appropriate places. 
 
-Then, if you want to update your IPython at any time,
-just do:
+Then, if you want to update your IPython at any time, do:
 
 .. code-block:: bash
 
@@ -191,6 +152,7 b' get. These are:'
 
 * readline (for command line editing, tab completion, etc.)
 * nose (to run the IPython test suite)
+* mock (Python < 3, also for tests)
 
 If you are comfortable installing these things yourself, have at it, otherwise
 read on for more details.
@@ -209,7 +171,7 b' native Windows calls through :mod:`ctypes`. The easiest way of installing'
 PyReadline is you use the binary installer available `here
 <http://pypi.python.org/pypi/pyreadline>`__.
 
-On OSX, if you are using the built-in Python shipped by Apple, you will be
+On OS X, if you are using the built-in Python shipped by Apple, you will be
 missing a proper readline implementation as Apple ships instead a library called
 ``libedit`` that provides only some of readline's functionality.  While you may
 find libedit sufficient, we have occasional reports of bugs with it and several
@@ -219,7 +181,7 b' for productive, regular use with IPython.'
 Therefore, IPython on OS X depends on the :mod:`gnureadline` module.
 We will *not* consider completion/history problems to be bugs for IPython if you are using libedit.
 
-To get a working :mod:`readline` module on OS X, just do (with :mod:`pip`
+To get a working :mod:`readline` module on OS X, do (with :mod:`pip`
 installed):
 
 .. code-block:: bash
@@ -231,8 +193,8 b' installed):'
     Other Python distributions on OS X (such as Anaconda, fink, MacPorts)
     already have proper readline so you likely don't have to do this step.
 
-When IPython is installed with :mod:`setuptools`, (e.g. using the
-``pip`` command), the correct readline should be installed if you specify the `terminal`
+When IPython is installed with :mod:`pip`,
+the correct readline should be installed if you specify the `terminal`
 optional dependencies:
 
 .. code-block:: bash
@@ -270,84 +232,67 b' iptest command:'
 Dependencies for IPython.parallel (parallel computing)
 ======================================================
 
-IPython.parallel provides a nice architecture for parallel computing, with a
-focus on fluid interactive workflows.  These features require just one package:
-PyZMQ.  See the next section for PyZMQ details.
+IPython's inter-process communication uses the PyZMQ_ bindings for the ZeroMQ_ messaging library.
+This is the only dependency for :mod:`IPython.parallel`.
 
-On a Unix style platform (including OS X), if you want to use
-:mod:`setuptools`, you can just do:
+Shortcut:
 
 .. code-block:: bash
 
-    $ pip install "ipython[zmq]"    # will include pyzmq
+    pip install "ipython[parallel]"
 
-Security in IPython.parallel is provided by SSH tunnels.  By default, Linux
-and OSX clients will use the shell ssh command, but on Windows, we also
-support tunneling with paramiko_.
+or manual
 
-Dependencies for IPython.kernel.zmq
-===================================
+.. code-block:: bash
 
-pyzmq
------
+    pip install pyzmq
 
-IPython 0.11 introduced some new functionality, including a two-process
-execution model using ZeroMQ_ for communication. The Python bindings to ZeroMQ
-are found in the PyZMQ_ project, which is pip install-able.
-If you are on Python 2.7, 3.3, or 3.4 on OSX or Windows,
-pyzmq has eggs and wheels that include ZeroMQ itself.
+PyZMQ provides wheels for current Python on OS X and Windows, so installing pyzmq will typically not require compilation.
 
-IPython.kernel.zmq depends on pyzmq >= 2.2.
+IPython.parallel can use SSH tunnels, which require paramiko_ on Windows.
 
-Dependencies for the IPython QT console
+Dependencies for the IPython Qt console
 =======================================
 
-pyzmq
------
+pyzmq_, pygments_, PyQt_ (or PySide_)
 
-Like the :mod:`IPython.parallel` package, the QT Console requires ZeroMQ and
-PyZMQ.
+Shortcut:
 
-Qt
---
+.. code-block:: bash
 
-Also with 0.11, a new GUI was added using the work in :mod:`IPython.kernel.zmq`, which
-can be launched with ``ipython qtconsole``. The GUI is built on Qt, and works
-with either `PyQt <http://www.riverbankcomputing.co.uk/>`_, or `PySide
-<http://qt-project.org/wiki/PySide>`_.
+    pip install "ipython[qtconsole]"
 
-pygments
---------
+or manual
 
-The syntax-highlighting in ``ipython qtconsole`` is done with the pygments_
-project, which is pip install-able.
+.. code-block:: bash
+
+    pip install pyzmq pygments
+
+PyQt/PySide are not pip installable, so generally must be installed via system package managers (or conda).
 
 .. _installnotebook:
 
 Dependencies for the IPython HTML notebook
 ==========================================
 
-The IPython notebook is a notebook-style web interface to IPython and can be
-started with the command ``ipython notebook``.
+The HTML notebook is a complex web application with quite a few dependencies:
 
-pyzmq
------
+pyzmq_, jinja2_, tornado_, mistune_, jsonschema_, pygments_, terminado_
 
-Like the :mod:`IPython.parallel` and :mod:`IPython.frontend.qt.console`
-packages, the HTML notebook requires ZeroMQ and PyZMQ.
+Shortcut:
 
-Tornado
--------
+.. code-block:: bash
 
-The IPython notebook uses the Tornado_ project for its HTTP server.  Tornado 2.1
-is required, in order to support current versions of browsers, due to an update
-to the websocket protocol.
+    pip install "ipython[notebook]"
 
-Jinja
------
+or manual:
 
-The IPython notebook uses the Jinja_ templating tool to render HTML pages.
+.. code-block:: bash
 
+    pip install pyzmq jinja2 tornado mistune jsonschema pygments terminado
+
+The IPython notebook is a notebook-style web interface to IPython and can be
+started with the command ``ipython notebook``.
 
 MathJax
 -------
@@ -360,21 +305,20 b' you can install MathJax locally.'
 
 A quick and easy method is to install it from a python session::
 
-    from IPython.external.mathjax import install_mathjax
-    install_mathjax()
+    python -m IPython.external.mathjax
 
 If you need tighter configuration control, you can download your own copy
 of MathJax from http://www.mathjax.org/download/ - use the MathJax-2.0 link.
 When you have the file stored locally, install it with::
 
-	python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip
+    python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip
 
 For unusual needs, IPython can tell you what directory it wants to find MathJax in::
 
-	python -m IPython.external.mathjax -d /some/other/mathjax
+    python -m IPython.external.mathjax -d /some/other/mathjax
 
-By default Mathjax will be installed in your ipython profile directory, but you
-can make system wide install, please refer to the documentation and helper function 
+By default MathJax will be installed in your ipython directory, but you
+can install MathJax system-wide.  Please refer to the documentation
 of :mod:`IPython.external.mathjax`
 
 Browser Compatibility
@@ -395,25 +339,15 b' The following browsers are unsupported:'
 * Chrome < 13
 * Opera (any): CSS issues, but execution might work
 * Internet Explorer < 10
+* Internet Explorer ≥ 10 (same as Opera)
 
-The following specific combinations are known **NOT** to work:
-
-* Safari, IPython 0.12, tornado ≥ 2.2.0
-* Safari with HTTPS connection to notebook and an untrusted certificate (websockets will fail)
-* The `diigo Chrome extension <http://help.diigo.com/tools/chrome-extension>`_ seems to interfere with scrolling
-
-There are some early reports that the Notebook works on Internet Explorer 10, but we
-expect there will be some CSS issues related to the flexible box model.
+Using Safari with HTTPS and an untrusted certificate is known to not work (websockets will fail).
 
 
 Dependencies for nbconvert (converting notebooks to various formats)
 ====================================================================
 
-pandoc
-------
-
-The most important dependency of nbconvert is Pandoc_ 1.10 or later, a document format translation program.
-This is not a Python package, so it cannot be expressed as a regular IPython dependency with setuptools.
+For converting markdown to formats other than HTML, nbconvert uses Pandoc_ (1.12.1 or later).
 
 To install pandoc on Linux, you can generally use your package manager::
 
@@ -432,3 +366,9 b' On other platforms, you can get pandoc from `their website <http://johnmacfarlan'
 .. _pandoc: http://johnmacfarlane.net/pandoc
 .. _Tornado: http://www.tornadoweb.org
 .. _MathJax: http://www.mathjax.org
+.. _PyQt: http://www.riverbankcomputing.com/software/pyqt/intro
+.. _PySide: http://qt-project.org/wiki/PySide
+.. _jinja2: http://jinja.pocoo.org/
+.. _mistune: https://github.com/lepture/mistune
+.. _jsonschema: https://github.com/Julian/jsonschema
+.. _terminado: https://github.com/takluyver/terminado
  No newline at end of file