Better virtualenv docs.

1 files changed, 93 insertions, 27 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index e6bf7c089..b9c5fe6f7 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -3,8 +3,8 @@
 Installing :mod:`repoze.bfg`
 ============================
 
-How To Install
---------------
+Before You Install
+------------------
 
 You will need `Python <http://python.org>`_ version 2.4 or better to
 run :mod:`repoze.bfg`.  It has been tested under Python 2.4.5, Python
@@ -45,9 +45,65 @@ installed in your Python version (and likewise, to prevent
 :mod:`repoze.bfg` from globally installing versions of packages that
 are not compatible with your system Python).
 
-To set up a virtualenv to install :mod:`repoze.bfg` within, make sure
-that the :term:`virtualenv` package is installed in your Python, then
-invoke:
+To set up a virtualenv to install :mod:`repoze.bfg` within, first
+ensure that setuptools is installed.  Invoke ``import setuptools``
+within the Python interpreter you'd like to run :mod:`repoze.bfg`
+under.
+
+.. code-block:: bash
+
+  [chrism@vitaminf bfg]$ python
+  Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
+  [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
+  Type "help", "copyright", "credits" or "license" for more information.
+  >>> import setuptools
+
+If ``import setuptools`` does not raise an ``ImportError``, it means
+that setuptools is already installed into your Python interpreter.  If
+``import setuptools`` fails, you will need to install setuptools
+manually.  If you are using a "system" Python (one installed by your
+OS distributor or a 3rd-party packager such as Fink or MacPorts), you
+can usually install a setuptools package using your system's package
+manager.  If you cannot do this, or if you're using a self-installed
+version of Python, you will need to install setuptools "by hand".
+Installing setuptools "by hand" is always a reasonable thing to do,
+even if your package manager already has a prechewed version of
+setuptools for installation.
+
+To install setuptools by hand, first download `ez_setup.py
+<http://peak.telecommunity.com/dist/ez_setup.py>`_ then invoke it
+using the Python interpreter you want to install setuptools into (you
+may need to be the administrative user on your system to do so,
+depending on the file permissions of your Python files).
+
+.. code-block:: bash
+
+  $ python ez_setup.py
+
+Once this command is invoked, setuptools should be installed on your
+system.
+
+Installing The ``virtualenv`` Package
+-------------------------------------
+
+Once you've got setuptools installed, you should install
+:term:`virtualenv`.  This is a package that creates a "virtual" Python
+interpreter.  Software installed into this interpreter will not
+pollute the parent Python, which is useful for evaluation and
+sandboxing.  To install the :term:`virtualenv` package into your
+setuptools-enabled Python interpreter, use the ``easy_install``
+command.
+
+.. code-block:: bash
+
+  $ easy_install virtualenv
+
+Creating a Virtual Python Environment
+-------------------------------------
+
+Once the :term:`virtualenv` package is installed in your Python, you
+can actually create a virtual environment.  To do so, invoke the
+following:
 
 .. code-block:: bash
    :linenos:
@@ -57,19 +113,19 @@ invoke:
    Installing setuptools.............done.
 
 .. warning:: Using ``--no-site-packages`` when generating your
-   virtualenv is important. This flag provides the necessary isolation
-   for running the set of packages required by :mod:`repoze.bfg`.  If
-   you do not specify ``--no-site-packages``, it's possible that
-   :mod:`repoze.bfg` will not install properly into the virtualenv,
-   or, even if it does, may not run properly, depending on the
-   packages you've already got installed into your Python's "main"
-   site-packages dir.
+   virtualenv is *very important*. This flag provides the necessary
+   isolation for running the set of packages required by
+   :mod:`repoze.bfg`.  If you do not specify ``--no-site-packages``,
+   it's possible that :mod:`repoze.bfg` will not install properly into
+   the virtualenv, or, even if it does, may not run properly,
+   depending on the packages you've already got installed into your
+   Python's "main" site-packages dir.
 
 You should perform any following commands that mention a "bin"
 directory from within the ``bfgenv`` virtualenv dir.
 
-Installing :mod:`repoze.bfg` Into A Virtualenv
-----------------------------------------------
+Installing :mod:`repoze.bfg` Into the Virtual Python Environment
+----------------------------------------------------------------
 
 After you've got your ``bfgenv`` virtualenv installed, you may install
 :mod:`repoze.bfg` itself using the following commands from within the
@@ -80,15 +136,23 @@ virtualenv (``bfgenv``) directory:
 
    $ bin/easy_install -i http://dist.repoze.org/lemonade/dev/simple repoze.bfg
 
-What Gets Installed
--------------------
+.. warning:: Note carefully the ``-i
+   http://dist.repoze.org/lemonade/dev/simple`` above.  It is
+   required.  :mod:`repoze.bfg` software is maintained in its own
+   index; :mod:`repoze.bfg` cannot be installed from PyPI.
 
-When you ``easy_install`` :mod:`repoze.bfg`, various Zope libraries,
-WebOb, Paste, PasteScript, and PasteDeploy libraries are installed.
+If ``lxml`` Fails to Compile During ``easy_install``
+----------------------------------------------------
 
-Additionally, as shown in the next section, PasteScript (aka *paster*)
-templates will be registered that make it easy to start a new
-:mod:`repoze.bfg` project.
+If the installation of :mod:`repoze.bfg` fails due to problems
+compiling ``lxml``, you should try installing ``lxml`` before
+installing :mod:`repoze.bfg`.  To do so, invoke ``easy_install``,
+instructing ``lxml`` to download its own copy of ``libxml2``::
+
+  $ STATIC_DEPS=true bin/easy_install lxml
+
+Once that completes, you can start a subsequent ``easy_install`` of
+:mod:`repoze.bfg` as per the instructions above; it should then work.
 
 If You Can't Install Via ``easy_install`` (Alternate Installation)
 ------------------------------------------------------------------
@@ -103,11 +167,13 @@ instead of your system packages, as version incompatibilities between
 system packages and ``lxml`` versions are typically to blame for
 compilation problems.
 
-Alternatively, you can try installing ``lxml`` before installing
-:mod:`repoze.bfg`, and instructing ``lxml`` to download its own copy
-of ``libxml2``::
+What Gets Installed
+-------------------
+
+When you ``easy_install`` :mod:`repoze.bfg`, various Zope libraries,
+WebOb, Paste, PasteScript, and PasteDeploy libraries are installed.
 
-  $ STATIC_DEPS=true easy_install lxml
+Additionally, as shown in the next section, PasteScript (aka *paster*)
+templates will be registered that make it easy to start a new
+:mod:`repoze.bfg` project.
 
-Once that completes, ``easy_install`` will know that ``lxml`` is
-already installed.