Merge pull request #9103 from takluyver/kernel-install-doc

Improve kernel installation docs

docs/source/install/kernel_install.rst

@@ -3,49 +3,26 b''
 Installing the IPython kernel
 =============================
 
-IPython can be installed (different python versions, virtualenv or conda
-environments) as a kernel for Jupyter by following these steps:
+The Jupyter Notebook and other frontends automatically ensure that the IPython kernel is available.
+However, if you want to use a kernel with a different version of Python, or in a virtualenv or conda environment,
+you'll need to install that manually.
 
-* make sure that the desired python installation is active
-  (e.g. activate the environment, or use absolute paths)
-  and ipykernel is installed
-* run once ``ipython kernel install --user``,
-  or ``python -m ipykernel install --user`` to ensure a specific Python installation is used.
-* See `ipython kernel install --help` for the list of installation options like
-  naming the kernel, or non default install location.
-* The IPython kernel for Jupyter is provided by the `ipykernel` python package,
-  see `ipykernel documentation <http://ipykernel.readthedocs.org/>`_ if you
-  need more flexibility for installation.
+Using the Python version or environment for which you want to set up the kernel, run::
 
-
-For example:
-
-.. sourcecode:: bash
-
-    source activate kernel-environment
-    ipython kernel install --user
-    source deactivate kernel-environment
-
-or
-
-.. sourcecode:: bash
-
-    ~/envs/kernel-environment/python -m ipykernel install --user
+    pip install ipykernel  # or: conda install ipykernel
+    python -m ipykernel install --user
 
 The last command installs a :ref:`kernel spec <jupyterclient:kernelspecs>` file
 for the current python installation. Kernel spec files are JSON files, which
 can be viewed and changed with a normal text editor.
 
-
-.. note ::
-
-    The command `ipython kernelspec` is deprecated and will be removed in future versions.
-
+See `python -m ipykernel install --help` for the list of installation options like
+naming the kernel, or non default install location.
 
 .. _multiple_kernel_install:
 
-Multiple IPython installs
-=========================
+Multiple IPython installations
+==============================
 
 If you want to have multiple IPython kernels for different environments,
 you will need to specify unique names for the kernelspecs,