- a new "Do I need to install pip?" section

- a new subsection for the get-pip options
  (which now mentions --no-wheel and --no-setuptools)
- explain that get-pip.py installs setuptools and wheel, and why.
- mention support for Python3.5

docs/installing.rst

@@ -3,40 +3,59 @@
 Installation
 ============
 
-Python & OS Support
--------------------
+Do I need to install pip?
+-------------------------
 
-pip works with CPython versions 2.6, 2.7, 3.2, 3.3, 3.4 and also pypy.
+Distributions of Python 2.7.9 and later (in the Python 2 series), and
+Python 3.4 and later (in the Python 3 series) may already include pip by
+default. [1]_
 
-pip works on Unix/Linux, OS X, and Windows.
+Additionally, it's common to be working in a :ref:`Virtual Envionment
+<pypug:Creating and using Virtual Environments>` created by a tool like
+:ref:`pypug:virtualenv` or :ref:`pyvenv <pypug:venv>`, which handles installing
+pip for you.
 
-.. note::
-
-  Python 2.5 was supported through v1.3.1, and Python 2.4 was supported through v1.1.
-
-pip included with Python
-------------------------
-Python 2.7.9 and later (on the python2 series), and Python 3.4
-and later include pip by default [1]_, so you may have pip already.
 
 .. _`get-pip`:
 
-Install pip
------------
+Installing with get-pip.py
+--------------------------
 
 To install pip, securely download `get-pip.py
 <https://bootstrap.pypa.io/get-pip.py>`_. [2]_
 
-Then run the following (which may require administrator access):
+Then run the following:
 
 ::
 
  python get-pip.py
 
-If `setuptools`_ is not already installed, ``get-pip.py`` will install
-`setuptools`_ for you. [3]_
 
-To upgrade an existing `setuptools`_, run ``pip install -U setuptools``.
+.. warning::
+
+   Be cautious if you're using a Python install that's managed by your operating
+   system or another package manager. get-pip.py does not coordinate with
+   those tools, and may leave your system in an inconsistent state.
+
+get-pip.py will also intall :ref:`pypug:setuptools` [3]_ and :ref:`pypug:wheel`,
+if they're not already. :ref:`pypug:setuptools` is required to install
+:term:`source distributions <pypug:Source Distribution (or "sdist")>`.  Both are
+required to be able to build a :ref:`Wheel cache` (which improves installation
+speed), although neither are required to install pre-built :term:`wheels
+<pypug:Wheel>`.
+
+
+get-pip.py options
+~~~~~~~~~~~~~~~~~~~
+
+.. option:: --no-setuptools
+
+    If set, don't attempt to install :ref:`pypug:setuptools`
+
+.. option:: --no-wheel
+
+    If set, don't attempt to install :ref:`pypug:wheel`
+
 
 Additionally, ``get-pip.py`` supports using the :ref:`pip install options <pip
 install Options>` and the :ref:`general options <General Options>`. Below are
@@ -55,24 +74,6 @@ Install behind a proxy::
   python get-pip.py --proxy="[user:passwd@]proxy.server:port"
 
 
-Upgrade pip
------------
-
-On Linux or OS X:
-
-::
-
- pip install -U pip
-
-
-On Windows [5]_:
-
-::
-
- python -m pip install -U pip
-
-
-
 Using OS Package Managers
 -------------------------
 
@@ -89,9 +90,40 @@ On Fedora::
    sudo yum install python-pip
 
 
+Upgrading
+---------
+
+On Linux or OS X:
+
+::
+
+ pip install -U pip
+
+
+On Windows [5]_:
+
+::
+
+ python -m pip install -U pip
+
+
+Python and OS Compatibility
+---------------------------
+
+pip works with CPython versions 2.6, 2.7, 3.2, 3.3, 3.4, 3.5 and also pypy.
+
+pip works on Unix/Linux, OS X, and Windows.
+
+.. note::
+
+  Python 2.5 was supported through v1.3.1, and Python 2.4 was supported through
+  v1.1.
+
+
 ----
 
-.. [1] https://docs.python.org/3/installing/
+.. [1] For Python 2, see https://docs.python.org/2/installing, and for Python3,
+       see https://docs.python.org/3/installing.
 
 .. [2] "Secure" in this context means using a modern browser or a
        tool like `curl` that verifies SSL certificates when downloading from
@@ -107,6 +139,3 @@ On Fedora::
        <https://github.com/pypa/pip/issues/1668>`_.
 
 .. [5] https://github.com/pypa/pip/issues/1299
-
-.. _setuptools: https://pypi.python.org/pypi/setuptools
-.. _distribute: https://pypi.python.org/pypi/distribute

docs/reference/pip_install.rst

@@ -415,6 +415,8 @@ Windows
   :file:`<CSIDL_LOCAL_APPDATA>\\pip\\Cache`
 
 
+.. _`Wheel cache`:
+
 Wheel cache
 ***********