Re-land: Removed virtualenv from depot_tools

bootstrap/virtualenv/docs/index.rst

-Virtualenv
-==========
-
-`Mailing list <http://groups.google.com/group/python-virtualenv>`_ |
-`Issues <https://github.com/pypa/virtualenv/issues>`_ |
-`Github <https://github.com/pypa/virtualenv>`_ |
-`PyPI <https://pypi.python.org/pypi/virtualenv/>`_ |
-User IRC: #pypa
-Dev IRC: #pypa-dev
-
-Introduction
-------------
-
-``virtualenv`` is a tool to create isolated Python environments.
-
-The basic problem being addressed is one of dependencies and versions,
-and indirectly permissions. Imagine you have an application that
-needs version 1 of LibFoo, but another application requires version
-2. How can you use both these applications?  If you install
-everything into ``/usr/lib/python2.7/site-packages`` (or whatever your
-platform's standard location is), it's easy to end up in a situation
-where you unintentionally upgrade an application that shouldn't be
-upgraded.
-
-Or more generally, what if you want to install an application *and
-leave it be*?  If an application works, any change in its libraries or
-the versions of those libraries can break the application.
-
-Also, what if you can't install packages into the global
-``site-packages`` directory?  For instance, on a shared host.
-
-In all these cases, ``virtualenv`` can help you. It creates an
-environment that has its own installation directories, that doesn't
-share libraries with other virtualenv environments (and optionally
-doesn't access the globally installed libraries either).
-
-.. comment: split here
-
-.. toctree::
-   :maxdepth: 2
-
-   installation
-   userguide
-   reference
-   development
-   changes
-
-.. warning::
-
-   Python bugfix releases 2.6.8, 2.7.3, 3.1.5 and 3.2.3 include a change that
-   will cause "import random" to fail with "cannot import name urandom" on any
-   virtualenv created on a Unix host with an earlier release of Python
-   2.6/2.7/3.1/3.2, if the underlying system Python is upgraded. This is due to
-   the fact that a virtualenv uses the system Python's standard library but
-   contains its own copy of the Python interpreter, so an upgrade to the system
-   Python results in a mismatch between the version of the Python interpreter
-   and the version of the standard library. It can be fixed by removing
-   ``$ENV/bin/python`` and re-running virtualenv on the same target directory
-   with the upgraded Python.
-
-Other Documentation and Links
------------------------------
-
-* `Blog announcement of virtualenv`__.
-
-  .. __: http://blog.ianbicking.org/2007/10/10/workingenv-is-dead-long-live-virtualenv/
-
-* James Gardner has written a tutorial on using `virtualenv with
-  Pylons
-  <http://wiki.pylonshq.com/display/pylonscookbook/Using+a+Virtualenv+Sandbox>`_.
-
-* Chris Perkins created a `showmedo video including virtualenv
-  <http://showmedo.com/videos/video?name=2910000&fromSeriesID=291>`_.
-
-* Doug Hellmann's `virtualenvwrapper`_ is a useful set of scripts to make
-  your workflow with many virtualenvs even easier. `His initial blog post on it`__.
-  He also wrote `an example of using virtualenv to try IPython`__.
-
-  .. _virtualenvwrapper: https://pypi.python.org/pypi/virtualenvwrapper/
-  .. __: http://www.doughellmann.com/articles/CompletelyDifferent-2008-05-virtualenvwrapper/index.html
-  .. __: http://www.doughellmann.com/articles/CompletelyDifferent-2008-02-ipython-and-virtualenv/index.html
-
-* `Pew`_ is another wrapper for virtualenv that makes use of a different
-  activation technique.
-
-  .. _Pew: https://pypi.python.org/pypi/pew/
-
-* `Using virtualenv with mod_wsgi
-  <http://code.google.com/p/modwsgi/wiki/VirtualEnvironments>`_.
-
-* `virtualenv commands
-  <https://github.com/thisismedium/virtualenv-commands>`_ for some more
-  workflow-related tools around virtualenv.
-
-* PyCon US 2011 talk: `Reverse-engineering Ian Bicking's brain: inside pip and virtualenv
-  <http://pyvideo.org/video/568/reverse-engineering-ian-bicking--39-s-brain--insi>`_.
-  By the end of the talk, you'll have a good idea exactly how pip
-  and virtualenv do their magic, and where to go looking in the source
-  for particular behaviors or bug fixes.
-
-Compare & Contrast with Alternatives
-------------------------------------
-
-There are several alternatives that create isolated environments:
-
-* ``workingenv`` (which I do not suggest you use anymore) is the
-  predecessor to this library. It used the main Python interpreter,
-  but relied on setting ``$PYTHONPATH`` to activate the environment.
-  This causes problems when running Python scripts that aren't part of
-  the environment (e.g., a globally installed ``hg`` or ``bzr``). It
-  also conflicted a lot with Setuptools.
-
-* `virtual-python
-  <http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python>`_
-  is also a predecessor to this library. It uses only symlinks, so it
-  couldn't work on Windows. It also symlinks over the *entire*
-  standard library and global ``site-packages``. As a result, it
-  won't see new additions to the global ``site-packages``.
-
-  This script only symlinks a small portion of the standard library
-  into the environment, and so on Windows it is feasible to simply
-  copy these files over. Also, it creates a new/empty
-  ``site-packages`` and also adds the global ``site-packages`` to the
-  path, so updates are tracked separately. This script also installs
-  Setuptools automatically, saving a step and avoiding the need for
-  network access.
-
-* `zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ doesn't
-  create an isolated Python environment in the same style, but
-  achieves similar results through a declarative config file that sets
-  up scripts with very particular packages. As a declarative system,
-  it is somewhat easier to repeat and manage, but more difficult to
-  experiment with. ``zc.buildout`` includes the ability to setup
-  non-Python systems (e.g., a database server or an Apache instance).
-
-I *strongly* recommend anyone doing application development or
-deployment use one of these tools.