Merge pull request pypa#162 from qwcode/current_update

mention that you may need to install wheel for wheel caching

Author: ncoghlan

source/current.rst

@@ -5,7 +5,7 @@ Tool Recommendations
 ====================
 
 :Page Status: Complete
-:Last Reviewed: 2014-11-11
+:Last Reviewed: 2015-08-31
 
 If you're familiar with Python packaging and installation, and just want to know
 what tools are currently recommended, then here it is.
@@ -15,10 +15,12 @@ Installation Tool Recommendations
 =================================
 
 * Use :ref:`pip` to install Python :term:`packages <Distribution Package>` from
-  :term:`PyPI <Python Package Index (PyPI)>`. [1]_ [2]_
+  :term:`PyPI <Python Package Index (PyPI)>`. [1]_ [2]_ Depending how :ref:`pip`
+  is installed, you made need to also install :ref:`wheel` to get the benefit
+  of :ref:`wheel caching <pip:Wheel cache>`. [3]_
 
 * Use :ref:`virtualenv`, or `pyvenv`_ to isolate application specific
-  dependencies from a shared Python installation. [3]_
+  dependencies from a shared Python installation. [4]_
 
 * If you're looking for management of fully integrated cross-platform software
   stacks, consider :ref:`buildout` (primarily focused on the web development
@@ -31,11 +33,11 @@ Packaging Tool Recommendations
 ==============================
 
 * Use :ref:`setuptools` to define projects and create :term:`Source Distributions
-  <Source Distribution (or "sdist")>`. [4]_ [5]_
+  <Source Distribution (or "sdist")>`. [5]_ [6]_
 
 * Use the ``bdist_wheel`` :ref:`setuptools` extension available from the
   :ref:`wheel project <wheel>` to create :term:`wheels <Wheel>`.  This is
-  especially beneficial, if your project contains binary extensions. [6]_
+  especially beneficial, if your project contains binary extensions. [7]_
 
 * Use `twine <https://pypi.python.org/pypi/twine>`_ for uploading distributions
   to :term:`PyPI <Python Package Index (PyPI)>`.
@@ -54,12 +56,17 @@ Packaging Tool Recommendations
        <http://www.python.org/dev/peps/pep-0453/#rationale>`_ from :ref:`PEP453
        <pypa:PEP453s>` as for why pip was chosen.
 
-.. [3] Beginning with Python 3.4, ``pyvenv`` will create virtualenv environments
+.. [3] :ref:`get-pip.py <pip:get-pip>` and :ref:`virtualenv` install
+       :ref:`wheel`, whereas :ref:`ensurepip` and :ref:`pyvenv <venv>` do not
+       currently.  Also, the common "python-pip" package that's found in various
+       linux distros, does not depend on "python-wheel" currently.
+
+.. [4] Beginning with Python 3.4, ``pyvenv`` will create virtualenv environments
        with ``pip`` installed, thereby making it an equal alternative to
        :ref:`virtualenv`. However, using :ref:`virtualenv` will still be
        recommended for users that need cross-version consistency.
 
-.. [4] Although you can use pure ``distutils`` for many projects, it does not
+.. [5] Although you can use pure ``distutils`` for many projects, it does not
        support defining dependencies on other projects and is missing several
        convenience utilities for automatically populating distribution metadata
        correctly that are provided by ``setuptools``. Being outside the
@@ -73,11 +80,11 @@ Packaging Tool Recommendations
        from a prebuilt :term:`wheel <Wheel>` file), it will actually build
        your project using :ref:`setuptools` instead.
 
-.. [5] `distribute`_ (a fork of setuptools) was merged back into
+.. [6] `distribute`_ (a fork of setuptools) was merged back into
        :ref:`setuptools` in June 2013, thereby making setuptools the default
        choice for packaging.
 
-.. [6] :term:`PyPI <Python Package Index (PyPI)>` currently only allows
+.. [7] :term:`PyPI <Python Package Index (PyPI)>` currently only allows
        uploading Windows and Mac OS X wheels, and they should be compatible with
        the binary installers provided for download from python.org. Enhancements
        will have to be made to the :ref:`wheel compatibility tagging scheme

source/projects.rst

@@ -285,6 +285,20 @@ deployment of Python applications as simple as ``cp``.
 Standard Library Projects
 #########################
 
+.. _ensurepip:
+
+ensurepip
+=========
+
+`Docs <https://docs.python.org/3/library/ensurepip.html>`__ |
+`Issues <http://bugs.python.org>`__
+
+A package in the Python Standard Library that provides support for bootstrapping
+:ref:`pip` into an existing Python installation or virtual environment.  In most
+cases, end users won't use this module, but rather it will be used during the
+build of the Python distribution.
+
+
 .. _distutils:
 
 distutils