Merge pull request #2774 from stevepiercy/1.7-branch

Steve Piercy

2016-09-27 04de2d545add61c08be035104d015bfd658abeac

Merge pull request #2774 from stevepiercy/1.7-branch

backport to 1.7 branch, Why use venv/bin/pip instead of source bin/activate then pip?

 docs/narr/install.rst

@@ -192,6 +192,29 @@

      $ $VENV/bin/pip install "pyramid==\ |release|\ "

.. index::
   single: $VENV/bin/pip vs. source bin/activate

.. _venv-bin-pip-vs-source-bin-activate:

.. note:: Why use ``$VENV/bin/pip`` instead of ``source bin/activate``, then
   ``pip``?

   ``$VENV/bin/pip`` clearly specifies that ``pip`` is run from within the
   virtual environment and not at the system level.

   ``activate`` drops turds into the user's shell environment, leaving them
   vulnerable to executing commands in the wrong context. ``deactivate`` might
   not correctly restore previous shell environment variables.

   Although using ``source bin/activate``, then ``pip``, requires fewer key
   strokes to issue commands once invoked, there are other things to consider.
   Michael F. Lamb (datagrok) presents a summary in `Virtualenv's bin/activate
   is Doing It Wrong <https://gist.github.com/datagrok/2199506>`_.

   Ultimately we prefer to keep things clear and simple, so we use
   ``$VENV/bin/pip``.


.. index::
   single: installing on Windows
@@ -228,6 +251,9 @@

      c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "

.. note:: See the note above for :ref:`Why use $VENV/bin/pip instead of source
   bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.


What Gets Installed
-------------------

 docs/quick_tour.rst

@@ -59,7 +59,9 @@

.. seealso:: See also:
    :ref:`Quick Tutorial section on Requirements <qtut_requirements>`,
    :ref:`installing_unix`, :ref:`Before You Install <installing_chapter>`, and
    :ref:`installing_unix`, :ref:`Before You Install <installing_chapter>`,
    :ref:`Why use $VENV/bin/pip instead of source bin/activate, then pip
    <venv-bin-pip-vs-source-bin-activate>`, and
    :ref:`Installing Pyramid on a Windows System <installing_windows>`.



 docs/quick_tutorial/requirements.rst

@@ -179,6 +179,9 @@
    # Windows
    c:\> %VENV%\Scripts\pip install --upgrade pip setuptools

.. seealso:: See also :ref:`Why use $VENV/bin/pip instead of source
   bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.


.. _install-pyramid: