Merge pull request #1084 from stevepiercy/master

Clean up directions for install Python 2 and 3 and Python extensions on ...

3 files changed, 128 insertions, 153 deletions

diff --git a/docs/index.rst b/docs/index.rst
index f899ddac3..d2a0008a8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -129,7 +129,7 @@ platforms.
    tutorials/bfg/index.rst
    tutorials/modwsgi/index.rst
 
-.. _api_documentation:
+.. _html_api_documentation:
 
 API Documentation
 =================
@@ -204,5 +204,4 @@ Index and Glossary
    :hidden:
 
    glossary
-   latexindex
 
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 13ba61648..eb14f5076 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _latexindex:
 
 =========================
@@ -28,8 +30,8 @@ Narrative Documentation
 
    narr/introduction
    narr/install
-   narr/configuration
    narr/firstapp
+   narr/configuration
    narr/project
    narr/startup
    narr/router
@@ -50,6 +52,7 @@ Narrative Documentation
    narr/vhosting
    narr/testing
    narr/resources
+   narr/hellotraversal
    narr/muchadoabouttraversal
    narr/traversal
    narr/security
@@ -60,6 +63,8 @@ Narrative Documentation
    narr/extending
    narr/advconfig
    narr/extconfig
+   narr/scaffolding
+   narr/upgrading
    narr/threadlocals
    narr/zca
 
@@ -71,42 +76,21 @@ Tutorials
 .. toctree::
    :maxdepth: 1
 
-   tutorials/wiki/index.rst
    tutorials/wiki2/index.rst
+   tutorials/wiki/index.rst
    tutorials/bfg/index.rst
    tutorials/modwsgi/index.rst
 
-.. _api_reference:
+.. _api_documentation:
 
-API Reference
-@@@@@@@@@@@@@
+API Documentation
+@@@@@@@@@@@@@@@@@
 
 .. toctree::
    :maxdepth: 1
+   :glob:
 
-   api/authorization
-   api/authentication
-   api/config
-   api/events
-   api/exceptions
-   api/httpexceptions
-   api/i18n
-   api/interfaces
-   api/location
-   api/paster
-   api/registry
-   api/renderers
-   api/request
-   api/response
-   api/scripting
-   api/security
-   api/settings
-   api/testing
-   api/threadlocal
-   api/traversal
-   api/url
-   api/view
-   api/wsgi
+   api/*
 
 .. backmatter::
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index ef5772f79..15e9e8699 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -9,49 +9,50 @@ Installing :app:`Pyramid`
 Before You Install
 ------------------
 
-You will need `Python <http://python.org>`_ version 2.6 or better to
-run :app:`Pyramid`.  
+You will need `Python <http://python.org>`_ version 2.6 or better to run
+:app:`Pyramid`.
 
 .. sidebar:: Python Versions
 
-    As of this writing, :app:`Pyramid` has been tested under Python 2.6,
-    Python 2.7, Python 3.2, and Python 3.3.  :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, Python
+    2.7, Python 3.2, and Python 3.3.  :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, Mac OS X, and FreeBSD as well as on Windows platforms.  It is
-also known to run on :term:`PyPy` (1.9+).
+:app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux,
+Mac OS X, and FreeBSD as well as on Windows platforms.  It is also 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
-requirements mentioned.
+:app:`Pyramid` installation does not require the compilation of any C code, so
+you need only a Python interpreter that meets the requirements mentioned.
 
 For Mac OS X Users
 ~~~~~~~~~~~~~~~~~~
 
 From `Python.org <http://python.org/download/mac/>`_:
 
-    Python comes pre-installed on Mac OS X, but due to Apple's release
-    cycle, it's often one or even two years old. The overwhelming
-    recommendation of the "MacPython" community is to upgrade your
-    Python by downloading and installing a newer version from
-    `the Python standard release page <http://python.org/download/releases/>`_.
+    Python comes pre-installed on Mac OS X, but due to Apple's release cycle,
+    it's often one or even two years old. The overwhelming recommendation of
+    the "MacPython" community is to upgrade your Python by downloading and
+    installing a newer version from `the Python standard release page
+    <http://python.org/download/releases/>`_.
 
-It is recommended to download one of the *installer* versions, unless you prefer to install your Python through a packgage manager (e.g., macports or homebrew) or to build your Python from source.
+It is recommended to download one of the *installer* versions, unless you
+prefer to install your Python through a packgage manager (e.g., macports or
+homebrew) or to build your Python from source.
 
-Unless you have a need for a specific earlier version, it is recommended
-to install the latest 2.x or 3.x version of Python.
+Unless you have a need for a specific earlier version, it is recommended to
+install the latest 2.x or 3.x version of Python.
 
-If you use an installer for your Python, then you can skip to the
-section :ref:`installing_unix`.
+If you use an installer for your Python, then you can skip to the section
+:ref:`installing_unix`.
 
 If You Don't Yet Have A Python Interpreter (UNIX)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If your system doesn't have a Python interpreter, and you're on UNIX,
-you can either install Python using your operating system's package
-manager *or* you can install Python from source fairly easily on any
-UNIX system that has development tools.
+If your system doesn't have a Python interpreter, and you're on UNIX, you can
+either install Python using your operating system's package manager *or* you
+can install Python from source fairly easily on any UNIX system that has
+development tools.
 
 .. index::
    pair: install; Python (from package, UNIX)
@@ -59,9 +60,8 @@ UNIX system that has development tools.
 Package Manager Method
 ++++++++++++++++++++++
 
-You can use your system's "package manager" to install Python.
-Each package manager is slightly different, but the "flavor" of
-them is usually the same.
+You can use your system's "package manager" to install Python. Each package
+manager is slightly different, but the "flavor" of them is usually the same.
 
 For example, on a Debian or Ubuntu system, use the following command:
 
@@ -82,28 +82,27 @@ invokable via ``python2.7`` from a shell prompt.
 Source Compile Method
 +++++++++++++++++++++
 
-It's useful to use a Python interpreter that *isn't* the "system"
-Python interpreter to develop your software.  The authors of
-:app:`Pyramid` tend not to use the system Python for development
-purposes; always a self-compiled one.  Compiling Python is usually
-easy, and often the "system" Python is compiled with options that
-aren't optimal for web development. For an explanation, see
+It's useful to use a Python interpreter that *isn't* the "system" Python
+interpreter to develop your software.  The authors of :app:`Pyramid` tend not
+to use the system Python for development purposes; always a self-compiled one. 
+Compiling Python is usually easy, and often the "system" Python is compiled
+with options that aren't optimal for web development. For an explanation, see
 https://github.com/Pylons/pyramid/issues/747.
 
-To compile software on your UNIX system, typically you need
-development tools.  Often these can be installed via the package
-manager.  For example, this works to do so on an Ubuntu Linux system:
+To compile software on your UNIX system, typically you need development tools. 
+Often these can be installed via the package manager.  For example, this works
+to do so on an Ubuntu Linux system:
 
 .. code-block:: text
 
    $ sudo apt-get install build-essential
 
-On Mac OS X, installing `XCode
-<http://developer.apple.com/tools/xcode/>`_ has much the same effect.
+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.7 interpreter from *source*, on the same system,
-using the following commands:
+Once you've got development tools installed on your system, you can install a
+Python 2.7 interpreter from *source*, on the same system, using the following
+commands:
 
 .. code-block:: text
 
@@ -117,9 +116,8 @@ using the following commands:
    $ ./configure --prefix=$HOME/opt/Python-2.7.3
    $ make && make install
 
-Once these steps are performed, the Python interpreter will be
-invokable via ``$HOME/opt/Python-2.7.3/bin/python`` from a shell
-prompt.
+Once these steps are performed, the Python interpreter will be invokable via
+``$HOME/opt/Python-2.7.3/bin/python`` from a shell prompt.
 
 .. index::
    pair: install; Python (from package, Windows)
@@ -127,24 +125,21 @@ prompt.
 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.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
-executable and accept the defaults during the installation process.
-You may also need to download and install the `Python for Windows
-extensions <http://sourceforge.net/projects/pywin32/files/>`_.
+If your Windows system doesn't have a Python interpreter, you'll need 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
+executable and accept the defaults during the installation process. You may
+also need to download and install the Python for Windows extensions.
 
 .. warning::
 
-   After you install Python on Windows, you may need to add the
-   ``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``
-   and add that directory to the end of the ``Path`` environment
-   variable.
+   After you install Python on Windows, you may need to add the ``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`` and add that directory to the end of the ``Path``
+   environment variable.
 
 .. index::
    single: installing on UNIX
@@ -154,20 +149,19 @@ extensions <http://sourceforge.net/projects/pywin32/files/>`_.
 Installing :app:`Pyramid` on a UNIX System
 ---------------------------------------------
 
-It is best practice to install :app:`Pyramid` into a "virtual"
-Python environment in order to obtain isolation from any "system"
-packages you've got installed in your Python version.  This can be
-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.
+It is best practice to install :app:`Pyramid` into a "virtual" Python
+environment in order to obtain isolation from any "system" packages you've got
+installed in your Python version.  This can be 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.  To do so, invoke
-``import setuptools`` within the Python interpreter you'd like to run
-:app:`Pyramid` under.
+:term:`setuptools` is installed.  To do so, invoke ``import setuptools`` within
+the Python interpreter you'd like to run :app:`Pyramid` under.
 
-The following command will not display anything if setuptools is
-already installed:
+The following command will not display anything if setuptools is already
+installed:
 
 .. code-block:: text
 
@@ -186,29 +180,28 @@ If ``import setuptools`` raises an :exc:`ImportError` as it does above, 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 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.
+third-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.
 
 Installing Setuptools
 ~~~~~~~~~~~~~~~~~~~~~
 
 To install setuptools by hand under Python 2, first download `ez_setup.py
-<https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_ then
-invoke it using the Python interpreter into which you want to install setuptools.
+<https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_ then invoke
+it using the Python interpreter into which you want to install setuptools.
 
 .. code-block:: text
 
    $ python ez_setup.py
 
-Once this command is invoked, setuptools 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:
+Once this command is invoked, setuptools 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
 
@@ -220,9 +213,9 @@ the script.  To remediate this, you may need to do:
 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 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.
 
 .. warning::
 
@@ -235,16 +228,16 @@ your setuptools-enabled Python interpreter, use the ``easy_install`` command.
    Turing-complete.
 
    If you insist on using ``pyvenv``, you'll need to understand how to install
-   software such as ``setuptools`` into the virtual environment manually,
-   which this guide does not cover.
+   software such as ``setuptools`` into the virtual environment manually, which
+   this guide does not cover.
 
 .. code-block:: text
 
    $ easy_install virtualenv
 
 This command should succeed, and tell you that the virtualenv package is now
-installed.  If it fails due to permission errors, you may need to install it
-as your system's administrative user.  For example:
+installed.  If it fails due to permission errors, you may need to install it as
+your system's administrative user.  For example:
 
 .. code-block:: text
 
@@ -267,32 +260,31 @@ you can then create a virtual environment.  To do so, invoke the following:
    New python executable in /home/foo/env/bin/python
    Installing setuptools.............done.
 
-You can either follow the use of the environment variable, ``$VENV``,
-or replace it with the root directory of the :term:`virtualenv`.
-In that case, the `export` command can be skipped.
-If you choose the former approach, ensure that it's an absolute path.
+You can either follow the use of the environment variable, ``$VENV``, or
+replace it with the root directory of the :term:`virtualenv`. In that case, the
+`export` command can be skipped. If you choose the former approach, ensure that
+it's an absolute path.
 
 .. warning::
 
-   Using ``--no-site-packages`` when generating your
-   virtualenv is *very important*. This flag provides the necessary
-   isolation for running the set of packages required by
-   :app:`Pyramid`.  If you do not specify ``--no-site-packages``,
-   it's possible that :app:`Pyramid` 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.
+   Using ``--no-site-packages`` when generating your virtualenv is *very
+   important*. This flag provides the necessary isolation for running the set
+   of packages required by :app:`Pyramid`.  If you do not specify
+   ``--no-site-packages``, it's possible that :app:`Pyramid` 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.
 
 .. warning:: *do not* use ``sudo`` to run the
-   ``virtualenv`` script.  It's perfectly acceptable (and desirable)
-   to create a virtualenv as a normal user.
+   ``virtualenv`` script.  It's perfectly acceptable (and desirable) to create
+   a virtualenv as a normal user.
 
 
 Installing :app:`Pyramid` Into the Virtual Python Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-After you've got your virtualenv installed, you may install
-:app:`Pyramid` itself using the following commands:
+After you've got your virtualenv installed, you may install :app:`Pyramid`
+itself using the following commands:
 
 .. code-block:: text
 
@@ -309,21 +301,22 @@ complete, as it downloads and installs a number of dependencies.
 Installing :app:`Pyramid` on a Windows System
 -------------------------------------------------
 
-You can use Pyramid on Windows under Python 2 or under Python 3.
+You can use Pyramid on Windows under Python 2 or 3.
 
-#. Install the most recent `Python 2.7.x or 3.3.x version
+#. Download and install the most recent `Python 2.7.x or 3.3.x version
    <http://www.python.org/download/>`_ 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.7 or Python 3.3 and install it
-   using the same Python installation from the previous step.
+#. Download and install the `Python for Windows extensions
+   <http://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read
+   the README.txt file at the end of the list of builds, and follow its
+   directions. Make sure you get the proper 32- or 64-bit build and Python
+   version.
 
-#. Install latest :term:`setuptools` distribution into the Python you
-   obtained/installed/found in the step above: download `ez_setup.py
-   <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_
-   and run it using the ``python`` interpreter of your Python 2.7 or 3.3
-   installation using a command prompt:
+#. Install latest :term:`setuptools` distribution into the Python from step 1
+   above: download `ez_setup.py
+   <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_ and run
+   it using the ``python`` interpreter of your Python 2.7 or 3.3 installation
+   using a command prompt:
 
    .. code-block:: text
 
@@ -348,17 +341,16 @@ You can use Pyramid on Windows under Python 2 or under Python 3.
    .. code-block:: text
 
       c:\> set VENV=c:\env
-      
       # modify the command according to the python version, e.g.:
       # for Python 2.7:
       c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV%
       # for Python 3.3:
       c:\> c:\Python33\Scripts\virtualenv --no-site-packages %VENV%
 
-   You can either follow the use of the environment variable, ``%VENV%``,
-   or replace it with the root directory of the :term:`virtualenv`.
-   In that case, the `set` command can be skipped.
-   If you choose the former approach, ensure that it's an absolute path.
+   You can either follow the use of the environment variable, ``%VENV%``, or
+   replace it with the root directory of the :term:`virtualenv`. In that case,
+   the `set` command can be skipped. If you choose the former approach, ensure
+   that it's an absolute path.
 
 #. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell
    environment wired to use the virtualenv.