Merge pull request pypa#399 from qwcode/secure_docs

secure installation docs

docs/conf.py

@@ -39,14 +39,8 @@
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
-try:
-    from virtualenv import __version__
-    # The short X.Y version.
-    version = '.'.join(__version__.split('.')[:2])
-    # The full version, including alpha/beta/rc tags.
-    release = __version__
-except ImportError:
-    version = release = 'dev'
+from virtualenv import __version__
+version = release = __version__
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

docs/index.txt

@@ -16,28 +16,38 @@ virtualenv
 Installation
 ------------
 
-On many linux systems `virtualenv` is available as an OS package and can be installed with tools like `yum` or `apt-get`,
-although the latest version may not be available.
+.. warning::
 
-To install with `pip` (if you have `pip` installed globally):
+    We advise installing virtualenv-1.9 or greater. Prior to version 1.9, the pip included in virtualenv did not
+    not download from PyPI over SSL.
 
-::
+.. warning::
 
- $ [sudo] pip install virtualenv
+    When using pip to install virtualenv, we advise using pip-1.3 or greater. Prior to version 1.3, pip did not
+    not download from PyPI over SSL.
 
-Or to get the latest unreleased dev version:
+.. warning::
 
-::
+    We advise against using easy_install to install virtualenv, because easy_install
+    does not download from PyPI over SSL.
 
- $ [sudo] pip install https://github.com/pypa/virtualenv/tarball/develop
+.. warning::
+
+    We currently advise against using virtualenv.py directly, without installing the virtualenv distribution.
+    Using virtualenv.py directly relies upon insecure bootstrap scripts, and easy_install to install Setuptools/Distribute and pip.
+
+
+To install with `pip` (if you have pip-1.3 or greater installed globally):
 
+::
+
+ $ [sudo] pip install virtualenv
 
-To install with `easy_install` (if you have `Setuptools <https://pypi.python.org/pypi/setuptools>`_ or
-`Distribute <https://pypi.python.org/pypi/distribute>`_ installed globally):
+Or to get the latest unreleased dev version:
 
 ::
 
- $ [sudo] easy_install virtualenv
+ $ [sudo] pip install https://github.com/pypa/virtualenv/tarball/develop
 
 
 To install from source:
@@ -49,10 +59,6 @@ To install from source:
  $ cd virtualenv-X.X
  $ [sudo] python setup.py install
 
-Lastly, you can just down the single file `virtualenv.py`_ and use it directly
-(without installing the virtualenv distribution).
-
-.. _virtualenv.py: https://raw.github.com/pypa/virtualenv/master/virtualenv.py
 
 What It Does
 ------------
@@ -85,9 +91,7 @@ Usage
 
 The basic usage is::
 
-    $ python virtualenv.py ENV
-
-If you install it you can also just do ``virtualenv ENV``.
+    $ virtualenv ENV
 
 This creates ``ENV/lib/pythonX.X/site-packages``, where any libraries you
 install will go.  It also creates ``ENV/bin/python``, which is a Python
@@ -100,7 +104,7 @@ It also installs either `Setuptools
 <http://pypi.python.org/pypi/distribute>`_ into the environment. To use
 Distribute instead of setuptools, just call virtualenv like this::
 
-    $ python virtualenv.py --distribute ENV
+    $ virtualenv --distribute ENV
 
 You can also set the environment variable VIRTUALENV_DISTRIBUTE.
 
@@ -229,11 +233,11 @@ virtualenv can not only be configured by passing command line options such as
   you can also set an environment variable::
 
       $ export VIRTUALENV_DISTRIBUTE=true
-      $ python virtualenv.py ENV
+      $ virtualenv ENV
 
   It's the same as passing the option to virtualenv directly::
 
-      $ python virtualenv.py --distribute ENV
+      $ virtualenv --distribute ENV
 
   This also works for appending command line options, like ``--find-links``.
   Just leave an empty space between the passsed values, e.g.::
@@ -243,7 +247,7 @@ virtualenv can not only be configured by passing command line options such as
 
   is the same as calling::
 
-      $ python virtualenv.py --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists ENV
+      $ virtualenv --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists ENV
 
 - Config files