- replace easy_install with pip

- bump Python version to 3.5 or generalize to Python 3
- rewrite seealso's
- use ps1con lexer for windows powershell console
- add hyperlink targets

2 files changed, 42 insertions, 82 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 767b16fc0..4a2f228a3 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -29,6 +29,9 @@ 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.
 
+
+.. _for-mac-os-x-users:
+
 For Mac OS X Users
 ~~~~~~~~~~~~~~~~~~
 
@@ -52,6 +55,9 @@ Alternatively, you can use the `homebrew <http://brew.sh/>`_ package manager.
 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 You Don't Yet Have a Python Interpreter (UNIX)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index f855dcb55..3373ba2bc 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -4,9 +4,9 @@
 Requirements
 ============
 
-Let's get our tutorial environment setup. Most of the setup work is in
-standard Python development practices (install Python,
-make an isolated environment, and setup packaging tools.)
+Let's get our tutorial environment set up. Most of the set up work is in
+standard Python development practices (install Python and make an isolated
+environment.)
 
 .. note::
 
@@ -19,16 +19,14 @@ make an isolated environment, and setup packaging tools.)
 
 This *Quick Tutorial* is based on:
 
-* **Python 3.3**. Pyramid fully supports Python 3.3+ and Python 2.6+.
-  This tutorial uses **Python 3.3** but runs fine under Python 2.7.
+* **Python 3.5**. Pyramid fully supports Python 3.3+ and Python 2.6+. This
+  tutorial uses **Python 3.5** but runs fine under Python 2.7.
 
-* **pyvenv**. We believe in virtual environments. For this tutorial,
-  we use Python 3.3's built-in solution, the ``pyvenv`` command.
-  For Python 2.7, you can install ``virtualenv``.
+* **pyvenv**. We believe in virtual environments. For this tutorial, we use
+  Python 3.5's built-in solution, the ``pyvenv`` command. For Python 2.7, you
+  can install ``virtualenv``.
 
-* **setuptools and easy_install**. We use
-  `setuptools <https://pypi.python.org/pypi/setuptools/>`_
-  and its ``easy_install`` for package management.
+* **pip**. We use ``pip`` for package management.
 
 * **Workspaces, projects, and packages.** Our home directory
   will contain a *tutorial workspace* with our Python virtual
@@ -46,34 +44,39 @@ This *Quick Tutorial* is based on:
 Steps
 =====
 
-#. :ref:`install-python-3.3-or-greater`
+#. :ref:`install-python-3`
 #. :ref:`create-a-project-directory-structure`
 #. :ref:`set-an-environment-variable`
 #. :ref:`create-a-virtual-environment`
-#. :ref:`install-setuptools-(python-packaging-tools)`
 #. :ref:`install-pyramid`
 
-.. _install-python-3.3-or-greater:
 
-Install Python 3.3 or greater
------------------------------
+.. _install-python-3:
 
-Download the latest standard Python 3.3+ release (not development release)
-from `python.org <https://www.python.org/downloads/>`_.
+Install Python 3
+----------------
 
 Windows and Mac OS X users can download and run an installer.
 
+Download the latest standard Python 3 release (not development release) from
+`python.org <https://www.python.org/downloads/>`_.
+
 Windows users should also 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.
 
-Linux users can either use their package manager to install Python 3.3
-or may `build Python 3.3 from source
+Linux users can either use their package manager to install Python 3
+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>`.
+
 
 .. _create-a-project-directory-structure:
 
@@ -142,6 +145,8 @@ environment. We set an environment variable to save typing later.
     # Mac and Linux
     $ export VENV=~/projects/quick_tutorial/env
 
+.. code-block:: ps1con
+
     # Windows
     # TODO: This command does not work
     c:\> set VENV=c:\projects\quick_tutorial\env
@@ -158,7 +163,7 @@ Create a Virtual Environment
     and `PEP 453 <http://www.python.org/dev/peps/pep-0453/>`_ for a proposed
     resolution.
 
-``pyvenv`` is a tool to create isolated Python 3.3 environments, each
+``pyvenv`` is a tool to create isolated Python 3 environments, each
 with its own Python binary and independent set of installed Python
 packages in its site directories. Let's create one, using the location
 we just specified in the environment variable.
@@ -168,46 +173,13 @@ we just specified in the environment variable.
     # Mac and Linux
     $ pyvenv $VENV
 
-    # Windows
-    c:\> c:\Python33\python -m venv %VENV%
-
-.. seealso:: See also Python 3's :mod:`venv module <python3:venv>`,
-   Python 2's `virtualenv <http://www.virtualenv.org/en/latest/>`_
-   package,
-   :ref:`Installing Pyramid on a Windows System <installing_windows>`
-
-
-.. _install-setuptools-(python-packaging-tools):
-
-Install ``setuptools`` (Python packaging tools)
------------------------------------------------
-
-The following command will download a script to install ``setuptools``, then
-pipe it to your environment's version of Python.
-
-.. code-block:: bash
-
-    # Mac and Linux
-    $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python
+.. code-block:: ps1con
 
     # Windows
-    #
-    # Use your web browser to download this file:
-    #   https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
-    #
-    # ...and save it to:
-    # c:\projects\quick_tutorial\ez_setup.py
-    #
-    # Then run the following command:
-
-    c:\> %VENV%\Scripts\python ez_setup.py
-
-If ``wget`` complains with a certificate error, then run this command instead:
+    c:\> c:\Python35\python -m venv %VENV%
 
-.. code-block:: bash
-
-    # Mac and Linux
-    $ wget --no-check-certificate https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python
+.. seealso:: See also Python 3's :mod:`venv module <python3:venv>` and Python
+   2's `virtualenv <http://www.virtualenv.org/en/latest/>`_ package.
 
 
 .. _install-pyramid:
@@ -221,10 +193,10 @@ part is pretty easy:
 .. parsed-literal::
 
     # Mac and Linux
-    $ $VENV/bin/easy_install "pyramid==\ |release|\ "
+    $ $VENV/bin/pip install "pyramid==\ |release|\ "
 
     # Windows
-    c:\\> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ "
+    c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
 
 Our Python virtual environment now has the Pyramid software available.
 
@@ -234,30 +206,12 @@ during this tutorial:
 .. code-block:: bash
 
     # Mac and Linux
-    $ $VENV/bin/easy_install nose webtest deform sqlalchemy \
+    $ $VENV/bin/pip install nose webtest deform sqlalchemy \
        pyramid_chameleon pyramid_debugtoolbar waitress \
        pyramid_tm zope.sqlalchemy
 
-    # Windows
-    c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar waitress pyramid_tm zope.sqlalchemy
-
-
-.. note::
+.. code-block:: ps1con
 
-    Why ``easy_install`` and not ``pip``? Pyramid encourages use of namespace
-    packages, for which ``pip``'s support is less-than-optimal. Also, Pyramid's
-    dependencies use some optional C extensions for performance:   with
-    ``easy_install``, Windows users can get these extensions without needing
-    a C compiler (``pip`` does not support installing binary Windows
-    distributions, except for ``wheels``, which are not yet available for
-    all dependencies).
-
-.. seealso:: See also :ref:`installing_unix`. For instructions to set up your
-    Python environment for development using Windows or Python 2, see Pyramid's
-    :ref:`Before You Install <installing_chapter>`.
-
-    See also Python 3's :mod:`venv module <python3:venv>`, the `setuptools
-    installation instructions
-    <https://pypi.python.org/pypi/setuptools/0.9.8#installation-instructions>`_,
-    and `easy_install help <https://pypi.python.org/pypi/setuptools/0.9.8#using-setuptools-and-easyinstall>`_.
+    # Windows
+    c:\> %VENV%\Scripts\pip install nose webtest deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar waitress pyramid_tm zope.sqlalchemy