Explain in terms of virtualenv.

2 files changed, 139 insertions, 75 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index bb99d5b7b..57ce8a700 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -1,3 +1,5 @@
+.. _installing_chapter:
+
 Installing :mod:`repoze.bfg`
 ============================
 
@@ -33,27 +35,49 @@ installed.
    maillist <http://lists.repoze.org/listinfo/repoze-dev>`_ if you'd
    like to try to tackle the job of compilation and maintenance.
 
+Creating a Virtualenv
+---------------------
+
 It is advisable to install :mod:`repoze.bfg` into a :term:`virtualenv`
 in order to obtain isolation from any "system" packages you've got
 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).
 
-After you've got the requisite dependencies installed, you may install
-:mod:`repoze.bfg` into your Python environment using the following
-command::
+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:
+
+.. code-block:: bash
+   :linenos:
+
+   $ virtualenv --no-site-packages bfgenv
+   New python executable in bfgenv/bin/python
+   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.
+
+You should perform any following commands that mention a "bin"
+directory from within the ``bfgenv`` virtualenv dir.
 
-  $ easy_install -i http://dist.repoze.org/lemonade/dev/simple repoze.bfg
+Installing :mod:`repoze.bfg` Into A Virtualenv
+----------------------------------------------
 
-.. note:: If you can't get :mod:`repoze.bfg` installed using
-   ``easy_install`` because ``lxml`` fails to compile on your system,
-   you can try the `repoze.bfg buildout
-   <http://svn.repoze.org/buildouts/repoze.bfg/trunk/README.txt>`_.
-   This installation mechanism builds known-compatible ``libxml2`` and
-   ``libxslt`` from source and causes ``lxml`` to link against these
-   instead of your system packages, as version incompatibilities
-   between system packages and ``lxml`` versions are typically to
-   blame for compilation problems.
+After you've got your ``bfgenv`` virtualenv installed, you may install
+:mod:`repoze.bfg` itself using the following commands from within the
+virtualenv (``bfgenv``) directory:
+
+.. code-block:: bash
+   :linenos:
+
+   $ bin/easy_install -i http://dist.repoze.org/lemonade/dev/simple repoze.bfg
 
 What Gets Installed
 -------------------
@@ -64,3 +88,18 @@ WebOb, Paste, PasteScript, and PasteDeploy libraries are installed.
 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 You Can't Install Via ``easy_install`` (Alternate Installation)
+------------------------------------------------------------------
+
+If you can't get :mod:`repoze.bfg` installed using ``easy_install``
+because ``lxml`` fails to compile on your system, you can try the
+`repoze.bfg buildout
+<http://svn.repoze.org/buildouts/repoze.bfg/trunk/README.txt>`_.  This
+installation mechanism builds known-compatible ``libxml2`` and
+``libxslt`` from source and causes ``lxml`` to link against these
+instead of your system packages, as version incompatibilities between
+system packages and ``lxml`` versions are typically to blame for
+compilation problems.
+
+
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 2f310f89f..2e597b240 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -11,43 +11,50 @@ Creating the Project
 --------------------
 
 To start a :mod:`repoze.bfg` :term:`project`, use the ``paster
-create`` facility::
+create`` facility using the interpreter from the virtualenv
+(``bfgenv``) directory you created in :ref:`installing_chapter`.
 
-  $ paster create -t bfg
+.. code-block:: bash
+   :linenos:
+
+   $ bin/paster create -t bfg
 
 ``paster create`` will ask you a single question: the *name* of the
 project.  You should use a string without spaces and with only letters
 in it.  Here's sample output from a run of ``paster create`` for a
-project we name ``MyProject``::
-
-  $ bin/paster create -t bfg
-  Selected and implied templates:
-    repoze.bfg#bfg  repoze.bfg starter project
-
-  Enter project name: MyProject
-  Variables:
-    egg:      MyProject
-    package:  myproject
-    project:  MyProject
-  Creating template bfg
-  Creating directory ./MyProject
-    Recursing into +package+
-      Creating ./MyProject/myproject/
-      Copying __init__.py to ./MyProject/myproject/__init__.py
-      Copying configure.zcml to ./MyProject/myproject/configure.zcml
-      Copying models.py to ./MyProject/myproject/models.py
-      Copying run.py_tmpl to ./MyProject/myproject/run.py
-      Recursing into templates
-        Creating ./MyProject/myproject/templates/
-        Copying mytemplate.pt to ./MyProject/myproject/templates/mytemplate.pt
-      Copying tests.py_tmpl to ./MyProject/myproject/tests.py
-      Copying views.py_tmpl to ./MyProject/myproject/views.py
-    Copying +project+.ini_tmpl to ./MyProject/MyProject.ini
-    Copying CHANGES.txt_tmpl to ./MyProject/CHANGES.txt
-    Copying README.txt_tmpl to ./MyProject/README.txt
-    Copying ez_setup.py to ./MyProject/ez_setup.py
-    Copying setup.py_tmpl to ./MyProject/setup.py
-  Running /Users/chrism/projects/repoze/bfg/bin/python setup.py egg_info
+project we name ``MyProject``:
+
+.. code-block:: bash
+   :linenos:
+
+   $ bin/paster create -t bfg
+   Selected and implied templates:
+     repoze.bfg#bfg  repoze.bfg starter project
+
+   Enter project name: MyProject
+   Variables:
+     egg:      MyProject
+     package:  myproject
+     project:  MyProject
+   Creating template bfg
+   Creating directory ./MyProject
+     Recursing into +package+
+       Creating ./MyProject/myproject/
+       Copying __init__.py to ./MyProject/myproject/__init__.py
+       Copying configure.zcml to ./MyProject/myproject/configure.zcml
+       Copying models.py to ./MyProject/myproject/models.py
+       Copying run.py_tmpl to ./MyProject/myproject/run.py
+       Recursing into templates
+         Creating ./MyProject/myproject/templates/
+         Copying mytemplate.pt to ./MyProject/myproject/templates/mytemplate.pt
+       Copying tests.py_tmpl to ./MyProject/myproject/tests.py
+       Copying views.py_tmpl to ./MyProject/myproject/views.py
+     Copying +project+.ini_tmpl to ./MyProject/MyProject.ini
+     Copying CHANGES.txt_tmpl to ./MyProject/CHANGES.txt
+     Copying README.txt_tmpl to ./MyProject/README.txt
+     Copying ez_setup.py to ./MyProject/ez_setup.py
+     Copying setup.py_tmpl to ./MyProject/setup.py
+   Running /Users/chrism/projects/repoze/bfg/bin/python setup.py egg_info
 
 As a result of the above, a project is created in a directory named
 ``MyProject``.  That directory is a :term:`setuptools` :term:`project`
@@ -72,15 +79,21 @@ application's Python code and templates.
 Installing your Newly Created Project for Development
 -----------------------------------------------------
 
-Using your favorite Python interpreter (or, better, the interpreter
-from a :term:`virtualenv`), invoke the following command when inside
-the project directory against the generated ``setup.py``::
+Using the interpreter from the :term:`virtualenv` you create during
+:ref:`installing_chapter`, invoke the following command when inside
+the project directory against the generated ``setup.py``:
+
+.. code-block:: bash
+   :linenos:
+
+   $ ../bin/python setup.py develop
 
-  $ python setup.py develop
+Elided output from a run of this command is shown below:
 
-Elided output from a run of this command is shown below::
+.. code-block:: bash
+   :linenos:
 
-  $ python setup.py develop
+   $ ../bin/python setup.py develop
    ...
    Finished processing dependencies for MyProject==0.1
 
@@ -92,28 +105,34 @@ Running The Tests For Your Application
 --------------------------------------
 
 To run unit tests for your application, you should invoke them like
-so::
+so:
+
+.. code-block:: bash
+   :linenos:
 
-  $ python setup.py test -q
+   $ ../bin/python setup.py test -q
 
-Here's sample output from a test run::
+Here's sample output from a test run:
 
-  $ python setup.py test -q
-  running test
-  running egg_info
-  writing requirements to MyProject.egg-info/requires.txt
-  writing MyProject.egg-info/PKG-INFO
-  writing top-level names to MyProject.egg-info/top_level.txt
-  writing dependency_links to MyProject.egg-info/dependency_links.txt
-  writing entry points to MyProject.egg-info/entry_points.txt
-  reading manifest file 'MyProject.egg-info/SOURCES.txt'
-  writing manifest file 'MyProject.egg-info/SOURCES.txt'
-  running build_ext
-  ..
-  ----------------------------------------------------------------------
-  Ran 2 tests in 0.647s
+.. code-block:: bash
+   :linenos:
 
-OK
+   $ python setup.py test -q
+   running test
+   running egg_info
+   writing requirements to MyProject.egg-info/requires.txt
+   writing MyProject.egg-info/PKG-INFO
+   writing top-level names to MyProject.egg-info/top_level.txt
+   writing dependency_links to MyProject.egg-info/dependency_links.txt
+   writing entry points to MyProject.egg-info/entry_points.txt
+   reading manifest file 'MyProject.egg-info/SOURCES.txt'
+   writing manifest file 'MyProject.egg-info/SOURCES.txt'
+   running build_ext
+   ..
+   ----------------------------------------------------------------------
+   Ran 2 tests in 0.647s
+
+   OK
 
 The tests are found in the ``tests.py`` module in your ``paster
 create``-generated project.  Two sample tests exist.
@@ -123,15 +142,21 @@ Runnning The Project Application
 
 Once the project is installed for development, you can run the
 application it represents using the ``paster serve`` command against
-the generated ``MyProject.ini`` configuration file::
+the generated ``MyProject.ini`` configuration file:
 
-  $ paster serve MyProject.ini
+.. code-block:: bash
+   :linenos:
+
+   $ bin/paster serve MyProject.ini
 
-Here's sample output from a run::
+Here's sample output from a run:
+
+.. code-block:: bash
+   :linenos:
 
-  $ paster serve MyProject.ini
-  Starting server in PID 16601.
-  serving on 0.0.0.0:6543 view at http://127.0.0.1:6543
+   $ paster serve MyProject.ini
+   Starting server in PID 16601.
+   serving on 0.0.0.0:6543 view at http://127.0.0.1:6543
 
 By default, generated :mod:`repoze.bfg` applications will listen on
 port 6543.