update docs to recommend 2.7, add distribute-related instructions for python 3, add windows instructions for python 3, closes #653

1 files changed, 156 insertions, 57 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 172cfd6d3..e8482a289 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -14,13 +14,13 @@ run :app:`Pyramid`.
 
 .. sidebar:: Python Versions
 
-    As of this writing, :app:`Pyramid` has been tested under Python 2.6.6,
-    Python 2.7.2, and Python 3.2.  :app:`Pyramid` does not run under any
-    version of Python before 2.6.
+    As of this writing, :app:`Pyramid` has been tested under Python 2.6.8,
+    Python 2.7.3, Python 3.2.3, and Python 3.3b1.  :app:`Pyramid` does not
+    run under any version of Python before 2.6.
 
 :app:`Pyramid` is known to run on all popular UNIX-like systems such as
 Linux, MacOS X, and FreeBSD as well as on Windows platforms.  It is also
-known to run on :term:`PyPy` (1.6+).
+known to run on :term:`PyPy` (1.9+).
 
 :app:`Pyramid` installation does not require the compilation of any
 C code, so you need only a Python interpreter that meets the
@@ -45,15 +45,15 @@ system's package manager is slightly different, but the "flavor" of
 them is usually the same.
 
 For example, on an Ubuntu Linux system, to use the system package
-manager to install a Python 2.6 interpreter, use the following
+manager to install a Python 2.7 interpreter, use the following
 command:
 
 .. code-block:: text
 
-   $ sudo apt-get install python2.6-dev
+   $ sudo apt-get install python2.7-dev
 
 Once these steps are performed, the Python interpreter will usually be
-invokable via ``python2.6`` from a shell prompt.
+invokable via ``python2.7`` from a shell prompt.
 
 .. index::
    pair: install; Python (from source, UNIX)
@@ -80,7 +80,7 @@ On Mac OS X, installing `XCode
 <http://developer.apple.com/tools/xcode/>`_ has much the same effect.
 
 Once you've got development tools installed on your system, you can
-install a Python 2.6 interpreter from *source*, on the same system,
+install a Python 2.7 interpreter from *source*, on the same system,
 using the following commands:
 
 .. code-block:: text
@@ -90,15 +90,15 @@ using the following commands:
    [chrism@vitaminf ~]$ mkdir opt
    [chrism@vitaminf ~]$ cd tmp
    [chrism@vitaminf tmp]$ wget \
-          http://www.python.org/ftp/python/2.6.4/Python-2.6.4.tgz
-   [chrism@vitaminf tmp]$ tar xvzf Python-2.6.4.tgz
-   [chrism@vitaminf tmp]$ cd Python-2.6.4
-   [chrism@vitaminf Python-2.6.4]$ ./configure \
-           --prefix=$HOME/opt/Python-2.6.4
-   [chrism@vitaminf Python-2.6.4]$ make; make install
+          http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz
+   [chrism@vitaminf tmp]$ tar xvzf Python-2.7.3.tgz
+   [chrism@vitaminf tmp]$ cd Python-2.7.3
+   [chrism@vitaminf Python-2.7.3]$ ./configure \
+           --prefix=$HOME/opt/Python-2.7.3
+   [chrism@vitaminf Python-2.7.3]$ make; make install
 
 Once these steps are performed, the Python interpreter will be
-invokable via ``$HOME/opt/Python-2.6.4/bin/python`` from a shell
+invokable via ``$HOME/opt/Python-2.7.3/bin/python`` from a shell
 prompt.
 
 .. index::
@@ -108,7 +108,7 @@ If You Don't Yet Have A Python Interpreter (Windows)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If your Windows system doesn't have a Python interpreter, you'll need
-to install it by downloading a Python 2.6-series interpreter
+to install it by downloading a Python 2.7-series interpreter
 executable from `python.org's download section
 <http://python.org/download/>`_ (the files labeled "Windows
 Installer").  Once you've downloaded it, double click on the
@@ -119,7 +119,7 @@ extensions <http://sourceforge.net/projects/pywin32/files/>`_.
 .. warning::
 
    After you install Python on Windows, you may need to add the
-   ``C:\Python26`` directory to your environment's ``Path`` in order
+   ``C:\Python27`` directory to your environment's ``Path`` in order
    to make it possible to invoke Python from a command prompt by
    typing ``python``.  To do so, right click ``My Computer``, select
    ``Properties`` --> ``Advanced Tab`` --> ``Environment Variables``
@@ -141,39 +141,62 @@ done by using the :term:`virtualenv` package.  Using a virtualenv will
 also prevent :app:`Pyramid` from globally installing versions of
 packages that are not compatible with your system Python.
 
-To set up a virtualenv in which to install :app:`Pyramid`, first
-ensure that :term:`setuptools` is installed.  Invoke ``import
-setuptools`` within the Python interpreter you'd like to run
-:app:`Pyramid` under:
+To set up a virtualenv in which to install :app:`Pyramid`, first ensure that
+:term:`setuptools` or :term:`distribute` is installed.  To do so, invoke
+``import setuptools`` within the Python interpreter you'd like to run
+:app:`Pyramid` under.
+
+Here's the output you'll expect if setuptools or distribute is already
+installed:
 
 .. code-block:: text
 
-   [chrism@vitaminf pyramid]$ python
-   Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) 
-   [GCC 4.4.3] on linux2
+   [chrism@thinko docs]$ python2.7
+   Python 2.7.3 (default, Aug  1 2012, 05:14:39) 
+   [GCC 4.6.3] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import setuptools
+   >>> 
 
-If running ``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.  Note that above we're using a Python 2.6-series
-interpreter on Mac OS X; your output may differ if you're using a
-later Python version or a different platform.
-
-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 the setuptools package by 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 pre-chewed 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 into which you want to install
-setuptools.
+Here's the output you can expect if setuptools or distribute is not already
+installed:
+
+.. code-block:: text
+
+   [chrism@thinko docs]$ python2.7
+   Python 2.7.3 (default, Aug  1 2012, 05:14:39) 
+   [GCC 4.6.3] on linux2
+   Type "help", "copyright", "credits" or "license" for more information.
+   >>> import setutptools
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in <module>
+   ImportError: No module named setutptools
+   >>>
+
+If ``import setuptools`` raises an :exc:`ImportError` as it does above, you
+will need to install setuptools or distribute manually.  Note that above
+we're using a Python 2.7-series interpreter on Mac OS X; your output may
+differ if you're using a later Python version or a different platform.
+
+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 the
+setuptools or distribute package by 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 or distribute "by hand".  Installing
+setuptools or distribute "by hand" is always a reasonable thing to do, even
+if your package manager already has a pre-chewed version of setuptools for
+installation.
+
+If you're using Python 2, you'll want to install ``setuptools``.  If you're
+using Python 3, you'll want to install ``distribute``.  Below we tell you how
+to do both.
+
+Installing Setuptools On Python 2
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To install setuptools by hand under Python 2, first download `ez_setup.py
+<http://peak.telecommunity.com/dist/ez_setup.py>`_ then invoke it using the
+Python interpreter into which you want to install setuptools.
 
 .. code-block:: text
 
@@ -188,16 +211,37 @@ the script.  To remediate this, you may need to do:
 
    $ sudo python ez_setup.py
 
+Installing Distribute On Python 3
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``setuptools`` doesn't work under Python 3.  Instead, you can use
+``distribute``, which is a fork of setuptools that does work on Python 3.  To
+install it, first download `distribute_setup.py
+<http://python-distribute.org/distribute_setup.py>`_ then invoke it using the
+Python interpreter into which you want to install setuptools.
+
+.. code-block:: text
+
+   $ python3 distribute_setup.py
+
+Once this command is invoked, distribute should be installed on your system.
+If the command fails due to permission errors, you may need to be the
+administrative user on your system to successfully invoke the script.  To
+remediate this, you may need to do:
+
+.. code-block:: text
+
+   $ sudo python3 distribute_setup.py
+
 .. index::
    pair: install; virtualenv
 
 Installing the ``virtualenv`` Package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Once you've got setuptools installed, you should install the
-:term:`virtualenv` package.  To install the :term:`virtualenv` package
-into your setuptools-enabled Python interpreter, use the
-``easy_install`` command.
+Once you've got setuptools or distribute installed, you should install the
+:term:`virtualenv` package.  To install the :term:`virtualenv` package into
+your setuptools-enabled Python interpreter, use the ``easy_install`` command.
 
 .. code-block:: text
 
@@ -269,35 +313,90 @@ complete, as it downloads and installs a number of dependencies.
 Installing :app:`Pyramid` on a Windows System
 -------------------------------------------------
 
-#. Install, or find `Python 2.6
-   <http://python.org/download/releases/2.6.4/>`_ for your system.
+You can use Pyramid on Windows under Python 2 or under Python 3.  Directions
+for both versions are included below.
+
+Windows Using Python 2
+~~~~~~~~~~~~~~~~~~~~~~
+
+#. Install, or find `Python 2.7
+   <http://www.python.org/download/releases/2.7.3/>`_ for your system.
 
 #. Install the `Python for Windows extensions
    <http://sourceforge.net/projects/pywin32/files/>`_.  Make sure to
-   pick the right download for Python 2.6 and install it using the
+   pick the right download for Python 2.7 and install it using the
    same Python installation from the previous step.
 
 #. Install latest :term:`setuptools` distribution into the Python you
    obtained/installed/found in the step above: download `ez_setup.py
    <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.6 installation using a
+   the ``python`` interpreter of your Python 2.7 installation using a
    command prompt:
 
    .. code-block:: text
 
-      c:\> c:\Python26\python ez_setup.py
+      c:\> c:\Python27\python ez_setup.py
+
+#. Use that Python's `bin/easy_install` to install `virtualenv`:
+
+   .. code-block:: text
+
+      c:\> c:\Python27\Scripts\easy_install virtualenv
+
+#. Use that Python's virtualenv to make a workspace:
+
+   .. code-block:: text
+
+      c:\> c:\Python27\Scripts\virtualenv --no-site-packages env
+
+#. Switch to the ``env`` directory:
+
+   .. code-block:: text
+
+      c:\> cd env
+
+#. (Optional) Consider using ``Scripts\activate.bat`` to make your shell
+   environment wired to use the virtualenv.
+
+#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies
+   installed:
+
+   .. code-block:: text
+
+      c:\env> Scripts\easy_install pyramid
+
+Windows Using Python 3
+~~~~~~~~~~~~~~~~~~~~~~
+
+#. Install, or find `Python 3.2
+   <http://www.python.org/download/releases/3.2.3/>`_ for your system.
+
+#. Install the `Python for Windows extensions
+   <http://sourceforge.net/projects/pywin32/files/>`_.  Make sure to
+   pick the right download for Python 3.2 and install it using the
+   same Python installation from the previous step.
+
+#. Install latest :term:`distribute` distribution into the Python you
+   obtained/installed/found in the step above: download `distribute_setup.py
+   <http://python-distribute.org/distribute_setup.py>`_ and run it using the
+   ``python`` interpreter of your Python 3.2 installation using a command
+   prompt:
+
+   .. code-block:: text
+
+      c:\> c:\Python32\python distribute_setup.py
 
 #. Use that Python's `bin/easy_install` to install `virtualenv`:
 
    .. code-block:: text
 
-      c:\> c:\Python26\Scripts\easy_install virtualenv
+      c:\> c:\Python32\Scripts\easy_install virtualenv
 
 #. Use that Python's virtualenv to make a workspace:
 
    .. code-block:: text
 
-      c:\> c:\Python26\Scripts\virtualenv --no-site-packages env
+      c:\> c:\Python32\Scripts\virtualenv --no-site-packages env
 
 #. Switch to the ``env`` directory:
 
@@ -308,8 +407,8 @@ Installing :app:`Pyramid` on a Windows System
 #. (Optional) Consider using ``Scripts\activate.bat`` to make your shell
    environment wired to use the virtualenv.
 
-#. Use ``easy_install`` pointed at the "current" index to get
-   :app:`Pyramid` and its direct dependencies installed:
+#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies
+   installed:
 
    .. code-block:: text