- update installation.rst to use pip, pyvenv, Python 3.4

- simplify installation.rst by removing not-Pyramid things (installing Python and requirements for installing packages) while providing official external references
- update cross-reference in quick_tutorial requirements.rst
- add glossary entry for pyvenv

3 files changed, 107 insertions, 274 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index ef90a0f41..858f3de51 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1095,3 +1095,8 @@ Glossary
    pip
       The `Python Packaging Authority <https://www.pypa.io/>`_ recommended tool
       for installing Python packages.
+
+   pyvenv
+      The Python Packaging Authority's recommended command for `creating
+      virtual environments on Python 3.4 and greater
+      <https://packaging.python.org/en/latest/installing/#creating-virtual-environments>`_.
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 4a2f228a3..5e2abb236 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -3,14 +3,21 @@
 Installing :app:`Pyramid`
 =========================
 
+.. note::
+
+    This installation guide now emphasizes the use of Python 3.4 and greater
+    for simplicity.
+
+
 .. index::
    single: install preparation
 
-Before You Install
-------------------
+Before You Install Pyramid
+--------------------------
 
-You will need `Python <http://python.org>`_ version 2.6 or better to run
-:app:`Pyramid`.
+Install Python version 3.4 or greater for your operating system, and satisfy
+the :ref:`requirements-for-installing-packages`, as described in
+the following sections.
 
 .. sidebar:: Python Versions
 
@@ -19,15 +26,21 @@ You will need `Python <http://python.org>`_ version 2.6 or better to run
     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+).
+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.
+However, some :app:`Pyramid` dependencies may attempt to build binary
+extensions from C code for performance speed ups. If a compiler or Python
+headers are unavailable, the dependency will fall back to using pure Python
+instead.
 
-Some :app:`Pyramid` dependencies may attempt to build C extensions for
-performance speedups. If a compiler or Python headers are unavailable the
-dependency will fall back to using pure Python instead.
+.. note::
+
+   If you see any warnings or errors related to failing to compile the binary
+   extensions, in most cases you may safely ignore those errors. If you wish to
+   use the binary extensions, please verify that you have a functioning
+   compiler and the Python header files installed for your operating system.
 
 
 .. _for-mac-os-x-users:
@@ -37,7 +50,7 @@ For Mac OS X Users
 
 Python comes pre-installed on Mac OS X, but due to Apple's release cycle, it is
 often out of date. 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.
+recommended to install the latest 3.x version of Python.
 
 You can install the latest verion of Python for Mac OS X from the binaries on
 `python.org <https://www.python.org/downloads/mac-osx/>`_.
@@ -46,10 +59,7 @@ Alternatively, you can use the `homebrew <http://brew.sh/>`_ package manager.
 
 .. code-block:: text
 
-   # for python 2.7
-   $ brew install python
-
-   # for python 3.5
+   # for python 3.x
    $ brew install python3
 
 If you use an installer for your Python, then you can skip to the section
@@ -66,250 +76,101 @@ 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)
-
-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.
-
-For example, on a Debian or Ubuntu system, use the following command:
-
-.. code-block:: text
-
-   $ sudo apt-get install python2.7-dev
-
-This command will install both the Python interpreter and its development
-header files.  Note that the headers are required by some (optional) C
-extensions in software depended upon by Pyramid, not by Pyramid itself.
-
-Once these steps are performed, the Python interpreter will usually be
-invokable via ``python2.7`` from a shell prompt.
-
-.. index::
-   pair: install; Python (from source, UNIX)
-
-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
-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:
-
-.. code-block:: text
-
-   $ sudo apt-get install build-essential
+.. seealso:: See the official Python documentation :ref:`Using Python on Unix
+   platforms <python:using-on-unix>` for full details.
 
-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:
-
-.. code-block:: text
-
-   $ cd ~
-   $ mkdir tmp
-   $ mkdir opt
-   $ cd tmp
-   $ wget http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz
-   $ tar xvzf Python-2.7.3.tgz
-   $ cd Python-2.7.3
-   $ ./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.
 
 .. index::
    pair: install; Python (from package, Windows)
 
+.. _if-you-don-t-yet-have-a-python-interpreter-windows:
+
 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
+install it by downloading a Python 3.x-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.
-
-.. index::
-   single: installing on UNIX
-
-.. _installing_unix:
-
-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.
-
-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.
-
-The following command will not display anything if setuptools is already
-installed:
-
-.. code-block:: text
-
-   $ python2.7 -c 'import setuptools'
-
-Running the same command will yield the following output if setuptools is not
-yet installed:
-
-.. code-block:: text
+.. seealso:: See the official Python documentation :ref:`Using Python on
+   Windows <python:using-on-windows>` for full details.
 
-   Traceback (most recent call last):
-     File "<stdin>", line 1, in <module>
-   ImportError: No module named setuptools
-
-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
-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.
-
-.. code-block:: text
+.. seealso:: 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.
 
-   $ python ez_setup.py
+.. warning::
 
-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:
+   After you install Python on Windows, you may need to add the ``C:\Python3x``
+   directory to your environment's ``Path``, where ``x`` is the minor version
+   of installed Python, 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.
 
-.. code-block:: text
+   .. seealso:: See `Configuring Python (on Windows)
+      <https://docs.python.org/3/using/windows.html#configuring-python>`_ for
+      full details.
 
-   $ sudo python ez_setup.py
 
 .. index::
-   pair: install; virtualenv
+   single: requirements for installing packages
 
-Installing the ``virtualenv`` Package
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _requirements-for-installing-packages:
 
-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.
+Requirements for Installing Packages
+------------------------------------
 
-.. warning::
+Use :term:`pip` for installing packages and :term:`pyvenv` for creating a
+virtual environment. A virtual environment is a semi-isolated Python
+environment that allows packages to be installed for use by a particular
+application, rather than being installed system wide.
 
-   Python 3.3 includes ``pyvenv`` out of the box, which provides similar
-   functionality to ``virtualenv``.  We however suggest using ``virtualenv``
-   instead, which works well with Python 3.3.  This isn't a recommendation made
-   for technical reasons; it's made because it's not feasible for the authors
-   of this guide to explain setup using multiple virtual environment systems.
-   We are aiming to not need to make the installation documentation
-   Turing-complete.
+.. seealso:: See the Python Packaging Authority's (PyPA) documention
+   `Requirements for Installing Packages
+   <https://packaging.python.org/en/latest/installing/#requirements-for-installing-packages>`_
+   for full details.
 
-   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.
-
-.. 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:
-
-.. code-block:: text
-
-   $ sudo easy_install virtualenv
 
 .. index::
-   single: virtualenv
-   pair: Python; virtual environment
-
-Creating the Virtual Python Environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once the :term:`virtualenv` package is installed in your Python environment,
-you can then create a virtual environment.  To do so, invoke the following:
-
-.. code-block:: text
-
-   $ export VENV=~/env
-   $ virtualenv $VENV
-   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.
+   single: installing on UNIX
+   single: installing on Mac OS X
 
-.. warning::
+.. _installing_unix:
 
-   Avoid using the ``--system-site-packages`` option when creating the
-   virtualenv unless you know what you are doing. For versions of virtualenv
-   prior to 1.7, make sure to use the ``--no-site-packages`` option, because
-   this option was formerly not the default and may produce undesirable
-   results.
+Installing :app:`Pyramid` on a UNIX System
+------------------------------------------
 
-.. warning::
+After installing Python as described previously in :ref:`for-mac-os-x-users` or
+:ref:`if-you-don-t-yet-have-a-python-interpreter-unix`, and satisfying the
+:ref:`requirements-for-installing-packages`, you can now install Pyramid.
 
-    *do not* use ``sudo`` to run the ``virtualenv`` script.  It's perfectly
-    acceptable (and desirable) to create a virtualenv as a normal user.
+#. Make a :term:`virtualenv` workspace:
 
+   .. code-block:: bash
 
-Installing :app:`Pyramid` into the Virtual Python Environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      $ export VENV=~/env
+      $ pyvenv $VENV
 
-After you've got your virtualenv installed, you may install :app:`Pyramid`
-itself using the following commands:
+   You can either follow the use of the environment variable ``$VENV``, or
+   replace it with the root directory of the virtual environment. If you choose
+   the former approach, ensure that ``$VENV`` is an absolute path. In the
+   latter case, the ``export`` command can be skipped.
 
-.. parsed-literal::
+#. (Optional) Consider using ``$VENV/bin/activate`` to make your shell
+   environment wired to use the virtual environment.
 
-   $ $VENV/bin/easy_install "pyramid==\ |release|\ "
+#. Use ``pip`` to get :app:`Pyramid` and its direct dependencies installed:
 
-The ``easy_install`` command will take longer than the previous ones to
-complete, as it downloads and installs a number of dependencies.
+   .. parsed-literal::
 
-.. note::
+      $ $VENV/bin/pip install "pyramid==\ |release|\ "
 
-   If you see any warnings and/or errors related to failing to compile the C
-   extensions, in most cases you may safely ignore those errors. If you wish to
-   use the C extensions, please verify that you have a functioning compiler and
-   the Python header files installed.
 
 .. index::
    single: installing on Windows
@@ -319,72 +180,38 @@ 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 3.
-
-#. Download and install the most recent `Python 2.7.x or 3.3.x version
-   <http://www.python.org/download/>`_ for your system.
-
-#. 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 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
-
-      # modify the command according to the python version, e.g.:
-      # for Python 2.7:
-      c:\> c:\Python27\python ez_setup.py
-      # for Python 3.3:
-      c:\> c:\Python33\python ez_setup.py
-
-#. Install `virtualenv`:
-
-   .. code-block:: text
-
-      # modify the command according to the python version, e.g.:
-      # for Python 2.7:
-      c:\> c:\Python27\Scripts\easy_install virtualenv
-      # for Python 3.3:
-      c:\> c:\Python33\Scripts\easy_install virtualenv
+After installing Python as described previously in
+:ref:`if-you-don-t-yet-have-a-python-interpreter-windows`, and satisfying the
+:ref:`requirements-for-installing-packages`, you can now install Pyramid.
 
 #. Make a :term:`virtualenv` workspace:
 
-   .. code-block:: text
+   .. code-block:: ps1con
 
       c:\> set VENV=c:\env
-      # modify the command according to the python version, e.g.:
-      # for Python 2.7:
-      c:\> c:\Python27\Scripts\virtualenv %VENV%
-      # for Python 3.3:
-      c:\> c:\Python33\Scripts\virtualenv %VENV%
+      # replace "x" with your minor version of Python 3
+      c:\> c:\Python3x\Scripts\pyvenv %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 virtual environment. If you choose
+   the former approach, ensure that ``%VENV%`` is an absolute path. In the
+   latter case, the ``set`` command can be skipped.
 
 #. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell
-   environment wired to use the virtualenv.
+   environment wired to use the virtual environment.
 
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies
-   installed:
+#. Use ``pip`` to get :app:`Pyramid` and its direct dependencies installed:
 
    .. parsed-literal::
 
-      c:\\env> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ "
+      c:\\env> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
+
 
 What Gets Installed
 -------------------
 
-When you ``easy_install`` :app:`Pyramid`, various other libraries such as
-WebOb, PasteDeploy, and others are installed.
+When you install :app:`Pyramid`, various libraries such as WebOb, PasteDeploy,
+and others are installed.
 
 Additionally, as chronicled in :ref:`project_narr`, scaffolds will be
 registered, which make it easy to start a new :app:`Pyramid` project.
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index 299ad2ac0..c4e6beecb 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -72,10 +72,11 @@ or may `build Python 3 from source
 <http://pyramid.readthedocs.org/en/master/narr/install.html#package-manager-
 method>`_.
 
-.. seealso:: See also :ref:`For Mac OS X Users <for-mac-os-x-users>`,
-   :ref:`If You Don't Yet Have a Python Interpreter (UNIX)
-   <if-you-don-t-yet-have-a-python-interpreter-unix>`, and :ref:`Installing
-   Pyramid on a Windows System <installing_windows>`.
+.. seealso:: See also :ref:`For Mac OS X Users <for-mac-os-x-users>`, :ref:`If
+   You Don't Yet Have a Python Interpreter (UNIX)
+   <if-you-don-t-yet-have-a-python-interpreter-unix>`, and :ref:`If You Don't
+   Yet Have a Python Interpreter (Windows)
+   <if-you-don-t-yet-have-a-python-interpreter-windows>`.
 
 
 .. _create-a-project-directory-structure: