From 71834f3e17c809e48bd212dc1f7949fca8279be7 2014-05-16 17:30:17 From: MinRK Date: 2014-05-16 17:30:17 Subject: [PATCH] Backport PR #5837: pass on install docs there were many False statements, and no-longer appropriate recommendations to use easy_install. --- diff --git a/docs/source/install/install.rst b/docs/source/install/install.rst index 4ec5ff3..923c5b3 100644 --- a/docs/source/install/install.rst +++ b/docs/source/install/install.rst @@ -13,7 +13,7 @@ the quickest way to get up and running with IPython is: .. code-block:: bash - $ easy_install ipython[all] + $ pip install ipython[all] This will download and install IPython and its main optional dependencies: @@ -32,16 +32,6 @@ To run IPython's test suite, use the :command:`iptest` command: $ iptest -.. note:: - - .. code-block:: bash - - $ pip install ipython[all] - - will also work in many cases, but it will ignore the binary eggs - of packages such as pyzmq and readline, - which may be required for some users on Windows or OS X. - Overview ======== @@ -58,11 +48,10 @@ install all of its dependencies. Please let us know if you have problems installing IPython or any of its dependencies. -IPython and most dependencies can be installed via :command:`easy_install`, -provided by the :mod:`setuptools` package, or :command:`pip`. -In many scenarios, this is the most simplest method of installing Python packages. -More information about :mod:`setuptools` can be found on -`its PyPI page `__. +IPython and most dependencies can be installed via :command:`pip`. +In many scenarios, this is the simplest method of installing Python packages. +More information about :mod:`pip` can be found on +`its PyPI page `__. .. note:: @@ -83,15 +72,15 @@ with no external dependencies. However, some Python distributions 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 -`easy_install`), then the appropriate :mod:`readline` for your platform will be +`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 easy_install or pip --------------------------------------- +Installation using pip +---------------------- If you have :mod:`setuptools` or :mod:`pip`, the easiest way of getting IPython is -to simply use :command:`easy_install` or :command:`pip`: +to simply use :command:`pip`: .. code-block:: bash @@ -99,17 +88,11 @@ to simply use :command:`easy_install` or :command:`pip`: That's it. -.. note:: - - Many prefer :command:`pip` to :command:`easy_install`, but it ignores eggs (binary Python packages). - This mainly affects pyzmq and readline, which are compiled packages and provide - binary eggs. If you use :command:`pip` to install these packages, - it will always compile from source, which may not succeed. Installation from source ------------------------ -If you don't want to use :command:`easy_install`, or don't have it installed, +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 `_. Then do the following: @@ -133,7 +116,7 @@ Windows, the installation procedure is: 1. Install `setuptools `_. 2. Install `pyreadline `_. You can use - the command ``easy_install pyreadline`` from a terminal, or the binary + 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 @@ -227,33 +210,34 @@ PyReadline is you use the binary installer available `here `__. On OSX, if you are using the built-in Python shipped by Apple, you will be -missing a full readline implementation as Apple ships instead a library called +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 developers who use OS X as their main environment consider libedit unacceptable for productive, regular use with IPython. -Therefore, we *strongly* recommend that on OS X you get the full -:mod:`readline` module. We will *not* consider completion/history problems to -be bugs for IPython if you are using libedit. +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, just do (with :mod:`setuptools` +To get a working :mod:`readline` module on OS X, just do (with :mod:`pip` installed): .. code-block:: bash - $ easy_install readline + $ pip install gnureadline .. note:: - Other Python distributions on OS X (such as fink, MacPorts and the official - python.org binaries) already have readline installed so you likely don't - have to do this step. + 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 -``easy_install`` command), readline is added as a dependency on OS X, and -PyReadline on Windows, and will be installed on your system. However, if you -do not use setuptools, you may have to install one of these packages yourself. +``pip`` command), the correct readline should be installed if you specify the `terminal` +optional dependencies: + +.. code-block:: bash + + $ pip install ipython[terminal] nose @@ -261,7 +245,7 @@ nose To run the IPython test suite you will need the :mod:`nose` package. Nose provides a great way of sniffing out and running all of the IPython tests. The -simplest way of getting nose is to use :command:`easy_install` or :command:`pip`: +simplest way of getting nose is to use :command:`pip`: .. code-block:: bash @@ -295,7 +279,7 @@ On a Unix style platform (including OS X), if you want to use .. code-block:: bash - $ easy_install ipython[zmq] # will include pyzmq + $ pip install ipython[zmq] # will include pyzmq 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 @@ -309,11 +293,11 @@ 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 easy_install-able once you have -ZeroMQ installed. If you are on Python 2.6 or 2.7 on OSX, or 2.7 on Windows, -pyzmq has eggs that include ZeroMQ itself. +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. -IPython.kernel.zmq depends on pyzmq >= 2.1.4. +IPython.kernel.zmq depends on pyzmq >= 2.2. Dependencies for the IPython QT console ======================================= @@ -337,7 +321,7 @@ pygments -------- The syntax-highlighting in ``ipython qtconsole`` is done with the pygments_ -project, which is easy_install-able. +project, which is pip install-able. .. _installnotebook: @@ -397,7 +381,7 @@ of :mod:`IPython.external.mathjax` Browser Compatibility --------------------- -The IPython notebook is officially supported on the following browers: +The IPython notebook is officially supported on the following browsers: * Chrome ≥ 13 * Safari ≥ 5