Merge branch 'master' into feature/require-csrf

16 files changed, 349 insertions, 507 deletions

diff --git a/docs/narr/MyProject/README.txt b/docs/narr/MyProject/README.txt
index c28d0d94a..70759eba1 100644
--- a/docs/narr/MyProject/README.txt
+++ b/docs/narr/MyProject/README.txt
@@ -1 +1,12 @@
 MyProject README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/pserve development.ini
+
diff --git a/docs/narr/MyProject/development.ini b/docs/narr/MyProject/development.ini
index 749e574eb..94fece8ce 100644
--- a/docs/narr/MyProject/development.ini
+++ b/docs/narr/MyProject/development.ini
@@ -1,6 +1,6 @@
 ###
 # app configuration
-# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
 ###
 
 [app:main]
@@ -29,7 +29,7 @@ port = 6543
 
 ###
 # logging configuration
-# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
 ###
 
 [loggers]
diff --git a/docs/narr/MyProject/myproject/static/theme.min.css b/docs/narr/MyProject/myproject/static/theme.min.css
deleted file mode 100644
index 2f924bcc5..000000000
--- a/docs/narr/MyProject/myproject/static/theme.min.css
+++ /dev/null
@@ -1 +0,0 @@
-@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);body{font-family:"Open Sans","Helvetica Neue",Helvetica,Arial,sans-serif;font-weight:300;color:#fff;background:#bc2131}h1,h2,h3,h4,h5,h6{font-family:"Open Sans","Helvetica Neue",Helvetica,Arial,sans-serif;font-weight:300}p{font-weight:300}.font-normal{font-weight:400}.font-semi-bold{font-weight:600}.font-bold{font-weight:700}.starter-template{margin-top:250px}.starter-template .content{margin-left:10px}.starter-template .content h1{margin-top:10px;font-size:60px}.starter-template .content h1 .smaller{font-size:40px;color:#f2b7bd}.starter-template .content .lead{font-size:25px;color:#f2b7bd}.starter-template .content .lead .font-normal{color:#fff}.starter-template .links{float:right;right:0;margin-top:125px}.starter-template .links ul{display:block;padding:0;margin:0}.starter-template .links ul li{list-style:none;display:inline;margin:0 10px}.starter-template .links ul li:first-child{margin-left:0}.starter-template .links ul li:last-child{margin-right:0}.starter-template .links ul li.current-version{color:#f2b7bd;font-weight:400}.starter-template .links ul li a{color:#fff}.starter-template .links ul li a:hover{text-decoration:underline}.starter-template .links ul li .icon-muted{color:#eb8b95;margin-right:5px}.starter-template .links ul li:hover .icon-muted{color:#fff}.starter-template .copyright{margin-top:10px;font-size:.9em;color:#f2b7bd;text-transform:lowercase;float:right;right:0}@media (max-width:1199px){.starter-template .content h1{font-size:45px}.starter-template .content h1 .smaller{font-size:30px}.starter-template .content .lead{font-size:20px}}@media (max-width:991px){.starter-template{margin-top:0}.starter-template .logo{margin:40px auto}.starter-template .content{margin-left:0;text-align:center}.starter-template .content h1{margin-bottom:20px}.starter-template .links{float:none;text-align:center;margin-top:60px}.starter-template .copyright{float:none;text-align:center}}@media (max-width:767px){.starter-template .content h1 .smaller{font-size:25px;display:block}.starter-template .content .lead{font-size:16px}.starter-template .links{margin-top:40px}.starter-template .links ul li{display:block;margin:0}.starter-template .links ul li .icon-muted{display:none}.starter-template .copyright{margin-top:20px}}
\ No newline at end of file
diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt
index 65d7f0609..543663fe8 100644
--- a/docs/narr/MyProject/myproject/templates/mytemplate.pt
+++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt
@@ -34,15 +34,15 @@
           <div class="col-md-10">
             <div class="content">
               <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Starter scaffold</span></h1>
-              <p class="lead">Welcome to <span class="font-normal">${project}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.6b2</span>.</p>
+              <p class="lead">Welcome to <span class="font-normal">${project}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7</span>.</p>
             </div>
           </div>
         </div>
         <div class="row">
           <div class="links">
             <ul>
-              <li class="current-version">Generated by v1.6b2</li>
-              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.6-branch/">Docs</a></li>
+              <li class="current-version">Generated by v1.7</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
               <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
               <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
               <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
diff --git a/docs/narr/MyProject/myproject/tests.py b/docs/narr/MyProject/myproject/tests.py
index 37df08a2a..fd414cced 100644
--- a/docs/narr/MyProject/myproject/tests.py
+++ b/docs/narr/MyProject/myproject/tests.py
@@ -26,4 +26,4 @@ class FunctionalTests(unittest.TestCase):
 
     def test_root(self):
         res = self.testapp.get('/', status=200)
-        self.assertTrue('Pyramid' in res.body)
+        self.assertTrue(b'Pyramid' in res.body)
diff --git a/docs/narr/MyProject/production.ini b/docs/narr/MyProject/production.ini
index 3ccbe6619..1174b1cc7 100644
--- a/docs/narr/MyProject/production.ini
+++ b/docs/narr/MyProject/production.ini
@@ -1,6 +1,6 @@
 ###
 # app configuration
-# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
 ###
 
 [app:main]
@@ -23,7 +23,7 @@ port = 6543
 
 ###
 # logging configuration
-# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
 ###
 
 [loggers]
diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py
index 8c019af51..a911eff6d 100644
--- a/docs/narr/MyProject/setup.py
+++ b/docs/narr/MyProject/setup.py
@@ -15,16 +15,22 @@ requires = [
     'waitress',
     ]
 
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
+
 setup(name='MyProject',
       version='0.0',
       description='MyProject',
       long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Programming Language :: Python",
-        "Framework :: Pyramid",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
       author='',
       author_email='',
       url='',
@@ -32,9 +38,10 @@ setup(name='MyProject',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
+      extras_require={
+          'testing': tests_require,
+      },
       install_requires=requires,
-      tests_require=requires,
-      test_suite="myproject",
       entry_points="""\
       [paste.app_factory]
       main = myproject:main
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 34b12e1e9..6cd90d42f 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -119,7 +119,7 @@ The Interactive Shell
 
 .. seealso:: See also the output of :ref:`pshell --help <pshell_script>`.
 
-Once you've installed your program for development using ``setup.py develop``,
+Once you've installed your program for development using ``pip install -e .``,
 you can use an interactive Python shell to execute expressions in a Python
 environment exactly like the one that will be used when your application runs
 "for real".  To do so, use the ``pshell`` command line utility.
@@ -294,7 +294,7 @@ You may use the ``--list-shells`` option to see the available shells.
      python
 
 If you want to use a shell that isn't supported out of the box, you can
-introduce a new shell by registering an entry point in your setup.py:
+introduce a new shell by registering an entry point in your ``setup.py``:
 
 .. code-block:: python
 
@@ -578,10 +578,10 @@ Using Custom Arguments to Python when Running ``p*`` Scripts
 .. versionadded:: 1.5
 
 Each of Pyramid's console scripts (``pserve``, ``pviews``, etc.) can be run
-directly using ``python -m``, allowing custom arguments to be sent to the
+directly using ``python3 -m``, allowing custom arguments to be sent to the
 Python interpreter at runtime. For example::
 
-      python -3 -m pyramid.scripts.pserve development.ini
+      python3 -m pyramid.scripts.pserve development.ini
 
 
 .. index::
@@ -815,17 +815,17 @@ Making Your Script into a Console Script
 ----------------------------------------
 
 A "console script" is :term:`setuptools` terminology for a script that gets
-installed into the ``bin`` directory of a Python :term:`virtualenv` (or "base"
-Python environment) when a :term:`distribution` which houses that script is
-installed.  Because it's installed into the ``bin`` directory of a virtualenv
-when the distribution is installed, it's a convenient way to package and
-distribute functionality that you can call from the command-line. It's often
-more convenient to create a console script than it is to create a ``.py``
-script and instruct people to call it with the "right" Python interpreter.  A
-console script generates a file that lives in ``bin``, and when it's invoked it
-will always use the "right" Python environment, which means it will always be
-invoked in an environment where all the libraries it needs (such as Pyramid)
-are available.
+installed into the ``bin`` directory of a Python :term:`virtual environment`
+(or "base" Python environment) when a :term:`distribution` which houses that
+script is installed. Because it's installed into the ``bin`` directory of a
+virtual environment when the distribution is installed, it's a convenient way
+to package and distribute functionality that you can call from the
+command-line. It's often more convenient to create a console script than it is
+to create a ``.py`` script and instruct people to call it with the "right"
+Python interpreter. A console script generates a file that lives in ``bin``,
+and when it's invoked it will always use the "right" Python environment, which
+means it will always be invoked in an environment where all the libraries it
+needs (such as Pyramid) are available.
 
 In general, you can make your script into a console script by doing the
 following:
@@ -840,12 +840,11 @@ following:
   distribution which creates a mapping between a script name and a dotted name
   representing the callable you added to your distribution.
 
-- Run ``setup.py develop``, ``setup.py install``, or ``easy_install`` to get
-  your distribution reinstalled.  When you reinstall your distribution, a file
-  representing the script that you named in the last step will be in the
-  ``bin`` directory of the virtualenv in which you installed the distribution.
-  It will be executable.  Invoking it from a terminal will execute your
-  callable.
+- Run ``pip install -e .`` or ``pip install .`` to get your distribution
+  reinstalled. When you reinstall your distribution, a file representing the
+  script that you named in the last step will be in the ``bin`` directory of
+  the virtual environment in which you installed the distribution. It will be
+  executable. Invoking it from a terminal will execute your callable.
 
 As an example, let's create some code that can be invoked by a console script
 that prints the deployment settings of a Pyramid application.  To do so, we'll
@@ -927,16 +926,22 @@ top-level directory, your ``setup.py`` file will look something like this:
 
    requires = ['pyramid', 'pyramid_debugtoolbar']
 
+   tests_require = [
+       'WebTest >= 1.3.1',  # py3 compat
+       'pytest',  # includes virtualenv
+       'pytest-cov',
+       ]
+
    setup(name='MyProject',
          version='0.0',
          description='My project',
          long_description=README + '\n\n' +  CHANGES,
          classifiers=[
-           "Programming Language :: Python",
-           "Framework :: Pylons",
-           "Topic :: Internet :: WWW/HTTP",
-           "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-           ],
+             "Programming Language :: Python",
+             "Framework :: Pyramid",
+             "Topic :: Internet :: WWW/HTTP",
+             "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+         ],
          author='',
          author_email='',
          url='',
@@ -945,20 +950,23 @@ top-level directory, your ``setup.py`` file will look something like this:
          include_package_data=True,
          zip_safe=False,
          install_requires=requires,
-         tests_require=requires,
-         test_suite="myproject",
+         extras_require={
+             'testing': tests_require,
+         },
          entry_points = """\
          [paste.app_factory]
          main = myproject:main
          """,
          )
 
-We're going to change the setup.py file to add a ``[console_scripts]`` section
-within the ``entry_points`` string.  Within this section, you should specify a
-``scriptname = dotted.path.to:yourfunction`` line.  For example::
+We're going to change the ``setup.py`` file to add a ``[console_scripts]``
+section within the ``entry_points`` string. Within this section, you should
+specify a ``scriptname = dotted.path.to:yourfunction`` line.  For example:
+
+.. code-block:: ini
 
-  [console_scripts]
-  show_settings = myproject.scripts:settings_show
+   [console_scripts]
+   show_settings = myproject.scripts:settings_show
 
 The ``show_settings`` name will be the name of the script that is installed
 into ``bin``.  The colon (``:``) between ``myproject.scripts`` and
@@ -971,6 +979,7 @@ The result will be something like:
 
 .. code-block:: python
    :linenos:
+   :emphasize-lines: 43-44
 
    import os
 
@@ -984,16 +993,22 @@ The result will be something like:
 
    requires = ['pyramid', 'pyramid_debugtoolbar']
 
+   tests_require = [
+       'WebTest >= 1.3.1',  # py3 compat
+       'pytest',  # includes virtualenv
+       'pytest-cov',
+       ]
+
    setup(name='MyProject',
          version='0.0',
          description='My project',
          long_description=README + '\n\n' +  CHANGES,
          classifiers=[
-           "Programming Language :: Python",
-           "Framework :: Pylons",
-           "Topic :: Internet :: WWW/HTTP",
-           "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-           ],
+             "Programming Language :: Python",
+             "Framework :: Pyramid",
+             "Topic :: Internet :: WWW/HTTP",
+             "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+         ],
          author='',
          author_email='',
          url='',
@@ -1002,8 +1017,9 @@ The result will be something like:
          include_package_data=True,
          zip_safe=False,
          install_requires=requires,
-         tests_require=requires,
-         test_suite="myproject",
+         extras_require={
+             'testing': tests_require,
+         },
          entry_points = """\
          [paste.app_factory]
          main = myproject:main
@@ -1012,15 +1028,17 @@ The result will be something like:
          """,
          )
 
-Once you've done this, invoking ``$$VENV/bin/python setup.py develop`` will
-install a file named ``show_settings`` into the ``$somevirtualenv/bin``
-directory with a small bit of Python code that points to your entry point.  It
-will be executable.  Running it without any arguments will print an error and
-exit.  Running it with a single argument that is the path of a config file will
-print the settings.  Running it with an ``--omit=foo`` argument will omit the
-settings that have keys that start with ``foo``.  Running it with two "omit"
-options (e.g., ``--omit=foo --omit=bar``) will omit all settings that have keys
-that start with either ``foo`` or ``bar``::
+Once you've done this, invoking ``$VENV/bin/pip install -e .`` will install a
+file named ``show_settings`` into the ``$somevenv/bin`` directory with a
+small bit of Python code that points to your entry point. It will be
+executable. Running it without any arguments will print an error and exit.
+Running it with a single argument that is the path of a config file will print
+the settings. Running it with an ``--omit=foo`` argument will omit the settings
+that have keys that start with ``foo``. Running it with two "omit" options
+(e.g., ``--omit=foo --omit=bar``) will omit all settings that have keys that
+start with either ``foo`` or ``bar``:
+
+.. code-block:: bash
 
   $ $VENV/bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar
   debug_routematch                             False
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index d28eb341d..9dc042024 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -197,8 +197,8 @@ this:
   elements, such as templates and static assets as necessary.
 
 - Install the new package into the same Python environment as the original
-  application (e.g., ``$VENV/bin/python setup.py develop`` or 
-  ``$VENV/bin/python setup.py install``).
+  application (e.g., ``$VENV/bin/pip install -e .`` or ``$VENV/bin/pip install
+  .``).
 
 - Change the ``main`` function in the new package's ``__init__.py`` to include
   the original :app:`Pyramid` application's configuration functions via
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index b385eaf96..a3f730f0c 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -265,18 +265,18 @@ available you can install it through the packaging system from your OS; the
 package name is almost always ``gettext``. For example on a Debian or Ubuntu
 system run this command:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ sudo apt-get install gettext
 
 Installing Lingua is done with the Python packaging tools. If the
-:term:`virtualenv` into which you've installed your :app:`Pyramid` application
-lives in ``/my/virtualenv``, you can install Lingua like so:
+:term:`virtual environment` into which you've installed your :app:`Pyramid`
+application lives at the environment variable ``$VENV``, you can install Lingua
+like so:
 
-.. code-block:: text
+.. code-block:: bash
 
-   $ cd /my/virtualenv
-   $ $VENV/bin/easy_install lingua
+   $ $VENV/bin/pip install lingua
 
 Installation on Windows
 +++++++++++++++++++++++
@@ -288,12 +288,13 @@ compile it yourself. Make sure the installation path is added to your
 ``$PATH``.
 
 Installing Lingua is done with the Python packaging tools. If the
-:term:`virtualenv` into which you've installed your :app:`Pyramid` application
-lives in ``C:\my\virtualenv``, you can install Lingua like so:
+:term:`virtual environment` into which you've installed your :app:`Pyramid`
+application lives at the environment variable ``%VENV%``, you can install
+Lingua like so:
 
-.. code-block:: text
+.. code-block:: ps1con
 
-   C> %VENV%\Scripts\easy_install lingua
+   C> %VENV%\Scripts\pip install lingua
 
 
 .. index::
@@ -308,9 +309,9 @@ Once Lingua is installed, you may extract a message catalog template from the
 code and :term:`Chameleon` templates which reside in your :app:`Pyramid`
 application.  You run a ``pot-create`` command to extract the messages:
 
-.. code-block:: text
+.. code-block:: bash
 
-   $ cd /place/where/myapplication/setup.py/lives
+   $ cd /file/path/to/myapplication_setup.py
    $ mkdir -p myapplication/locale
    $ $VENV/bin/pot-create -o myapplication/locale/myapplication.pot src
 
@@ -331,9 +332,9 @@ represents translations of a particular set of messages to a particular locale.
 Initialize a ``.po`` file for a specific locale from a pre-generated ``.pot``
 template by using the ``msginit`` command from Gettext:
 
-.. code-block:: text
+.. code-block:: bash
 
-   $ cd /place/where/myapplication/setup.py/lives
+   $ cd /file/path/to/myapplication_setup.py
    $ cd myapplication/locale
    $ mkdir -p es/LC_MESSAGES
    $ msginit -l es -o es/LC_MESSAGES/myapplication.po
@@ -362,9 +363,9 @@ translated or re-translated.
 First, regenerate the ``.pot`` file as per :ref:`extracting_messages`. Then use
 the ``msgmerge`` command from Gettext.
 
-.. code-block:: text
+.. code-block:: bash
 
-   $ cd /place/where/myapplication/setup.py/lives
+   $ cd /file/path/to/myapplication_setup.py
    $ cd myapplication/locale
    $ msgmerge --update es/LC_MESSAGES/myapplication.po myapplication.pot
 
@@ -380,9 +381,9 @@ Finally, to prepare an application for performing actual runtime translations,
 compile ``.po`` files to ``.mo`` files using the ``msgfmt`` command from
 Gettext:
 
-.. code-block:: text
+.. code-block:: bash
 
-   $ cd /place/where/myapplication/setup.py/lives
+   $ cd /file/path/to/myapplication_setup.py
    $ msgfmt -o myapplication/locale/es/LC_MESSAGES/myapplication.mo \
          myapplication/locale/es/LC_MESSAGES/myapplication.po
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 767b16fc0..c767ed95a 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -3,38 +3,54 @@
 Installing :app:`Pyramid`
 =========================
 
+.. note::
+
+    This installation guide 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
 
-    As of this writing, :app:`Pyramid` has been tested under Python 2.6, Python
-    2.7, Python 3.3, Python 3.4, Python 3.5, PyPy, and PyPy3. :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.7,
+    Python 3.3, Python 3.4, Python 3.5, PyPy, and PyPy3. :app:`Pyramid` does
+    not run under any version of Python before 2.7.
 
 :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:
 
 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/>`_.
@@ -43,15 +59,15 @@ 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
 :ref:`installing_unix`.
 
+
+.. _if-you-don-t-yet-have-a-python-interpreter-unix:
+
 If You Don't Yet Have a Python Interpreter (UNIX)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -60,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.
+.. seealso:: See the official Python documentation :ref:`Using Python on Unix
+   platforms <python:using-on-unix>` for full details.
 
-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
-
-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'
+.. seealso:: See the official Python documentation :ref:`Using Python on
+   Windows <python:using-on-windows>` for full details.
 
-Running the same command will yield the following output if setuptools is not
-yet installed:
-
-.. code-block:: text
-
-   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.
-
-.. warning::
+Requirements for Installing Packages
+------------------------------------
 
-   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.
-
-   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
+Use :term:`pip` for installing packages and ``python3 -m venv env`` 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.
 
-   $ easy_install virtualenv
+.. 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.
 
-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:`virtual environment` workspace:
 
+   .. code-block:: bash
 
-Installing :app:`Pyramid` into the Virtual Python Environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      $ export VENV=~/env
+      $ python3 -m venv $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
@@ -313,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.
+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.
 
-#. Download and install the most recent `Python 2.7.x or 3.3.x version
-   <http://www.python.org/download/>`_ for your system.
+#. Make a :term:`virtual environment` workspace:
 
-#. 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
-
-#. 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\python3 -m venv %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/narr/introduction.rst b/docs/narr/introduction.rst
index 8db52dc21..24c9f6b93 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -859,14 +859,15 @@ Testing
 Every release of Pyramid has 100% statement coverage via unit and integration
 tests, as measured by the ``coverage`` tool available on PyPI.  It also has
 greater than 95% decision/condition coverage as measured by the
-``instrumental`` tool available on PyPI.  It is automatically tested by the
-Jenkins tool on Python 2.6, Python 2.7, Python 3.3, Python 3.4, Python 3.5,
-PyPy, and PyPy3 after each commit to its GitHub repository. Official Pyramid
-add-ons are held to a similar testing standard.  We still find bugs in Pyramid
-and its official add-ons, but we've noticed we find a lot more of them while
-working on other projects that don't have a good testing regime.
-
-Example: http://jenkins.pylonsproject.org/
+``instrumental`` tool available on PyPI. It is automatically tested by Travis,
+and Jenkins on Python 2.7, Python 3.3, Python 3.4, Python 3.5, PyPy, and PyPy3
+after each commit to its GitHub repository. Official Pyramid add-ons are held
+to a similar testing standard.  We still find bugs in Pyramid and its official
+add-ons, but we've noticed we find a lot more of them while working on other
+projects that don't have a good testing regime.
+
+Travis: https://travis-ci.org/Pylons/pyramid
+Jenkins: http://jenkins.pylonsproject.org/job/pyramid/
 
 Support
 ~~~~~~~
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 923fde436..24e484c11 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -67,14 +67,14 @@ Creating the Project
 .. seealso:: See also the output of :ref:`pcreate --help <pcreate_script>`.
 
 In :ref:`installing_chapter`, you created a virtual Python environment via the
-``virtualenv`` command.  To start a :app:`Pyramid` :term:`project`, use the
-``pcreate`` command installed within the virtualenv.  We'll choose the
+``venv`` command.  To start a :app:`Pyramid` :term:`project`, use the
+``pcreate`` command installed within the virtual environment.  We'll choose the
 ``starter`` scaffold for this purpose.  When we invoke ``pcreate``, it will
 create a directory that represents our project.
 
-In :ref:`installing_chapter` we called the virtualenv directory ``env``. The
-following commands assume that our current working directory is the ``env``
-directory.
+In :ref:`installing_chapter` we called the virtual environment directory
+``env``. The following commands assume that our current working directory is
+the ``env`` directory.
 
 The below example uses the ``pcreate`` command to create a project with the
 ``starter`` scaffold.
@@ -90,24 +90,13 @@ Or on Windows:
 .. code-block:: text
 
    > %VENV%\Scripts\pcreate -s starter MyProject
-   
-Here's sample output from a run of ``pcreate`` on UNIX for a project we name
-``MyProject``:
-
-.. code-block:: bash
-
-   $ $VENV/bin/pcreate -s starter MyProject
-   Creating template pyramid
-   Creating directory ./MyProject
-   # ... more output ...
-   Running /Users/chrism/projects/pyramid/bin/python setup.py egg_info
 
 As a result of invoking the ``pcreate`` command, a directory named
 ``MyProject`` is created.  That directory is a :term:`project` directory. The
 ``setup.py`` file in that directory can be used to distribute your application,
 or install your application for deployment or development.
 
-A ``.ini`` file named ``development.ini`` will be created in the project
+An ``.ini`` file named ``development.ini`` will be created in the project
 directory.  You will use this ``.ini`` file to configure a server, to run your
 application, and to debug your application.  It contains configuration that
 enables an interactive debugger and settings optimized for development.
@@ -123,16 +112,16 @@ The ``MyProject`` project directory contains an additional subdirectory named
 which holds very simple :app:`Pyramid` sample code.  This is where you'll edit
 your application's Python code and templates.
 
-We created this project within an ``env`` virtualenv directory.  However, note
-that this is not mandatory.  The project directory can go more or less anywhere
-on your filesystem.  You don't need to put it in a special "web server"
-directory, and you don't need to put it within a virtualenv directory.  The
-author uses Linux mainly, and tends to put project directories which he creates
-within his ``~/projects`` directory.  On Windows, it's a good idea to put
-project directories within a directory that contains no space characters, so
-it's wise to *avoid* a path that contains, i.e., ``My Documents``.  As a
-result, the author, when he uses Windows, just puts his projects in
-``C:\projects``.
+We created this project within an ``env`` virtual environment directory.
+However, note that this is not mandatory. The project directory can go more or
+less anywhere on your filesystem. You don't need to put it in a special "web
+server" directory, and you don't need to put it within a virtual environment
+directory. The author uses Linux mainly, and tends to put project directories
+which he creates within his ``~/projects`` directory. On Windows, it's a good
+idea to put project directories within a directory that contains no space
+characters, so it's wise to *avoid* a path that contains, i.e., ``My
+Documents``. As a result, the author, when he uses Windows, just puts his
+projects in ``C:\projects``.
 
 .. warning::
 
@@ -151,8 +140,9 @@ Installing your Newly Created Project for Development
 
 To install a newly created project for development, you should ``cd`` to the
 newly created project directory and use the Python interpreter from the
-:term:`virtualenv` you created during :ref:`installing_chapter` to invoke the
-command ``python setup.py develop``
+:term:`virtual environment` you created during :ref:`installing_chapter` to
+invoke the command ``pip install -e .``, which installs the project in
+development mode (``-e`` is for "editable") into the current directory (``.``).
 
 The file named ``setup.py`` will be in the root of the pcreate-generated
 project directory.  The ``python`` you're invoking should be the one that lives
@@ -165,23 +155,24 @@ On UNIX:
 .. code-block:: bash
 
    $ cd MyProject
-   $ $VENV/bin/python setup.py develop
+   $ $VENV/bin/pip install -e .
 
 Or on Windows:
 
-.. code-block:: text
+.. code-block:: ps1con
 
    > cd MyProject
-   > %VENV%\Scripts\python.exe setup.py develop
+   > %VENV%\Scripts\pip install -e .
 
 Elided output from a run of this command on UNIX is shown below:
 
 .. code-block:: bash
 
    $ cd MyProject
-   $ $VENV/bin/python setup.py develop
+   $ $VENV/bin/pip install -e .
    ...
-   Finished processing dependencies for MyProject==0.0
+   Successfully installed Chameleon-2.24 Mako-1.0.4 MyProject \
+   pyramid-chameleon-0.3 pyramid-debugtoolbar-2.4.2 pyramid-mako-1.0.2
 
 This will install a :term:`distribution` representing your project into the
 virtual environment interpreter's library set so it can be found by ``import``
@@ -195,65 +186,54 @@ statements and by other console scripts such as ``pserve``, ``pshell``,
 Running the Tests for Your Application
 --------------------------------------
 
-To run unit tests for your application, you should invoke them using the Python
-interpreter from the :term:`virtualenv` you created during
-:ref:`installing_chapter` (the ``python`` command that lives in the ``bin``
-directory of your virtualenv).
+To run unit tests for your application, you must first install the testing
+dependencies.
 
 On UNIX:
 
 .. code-block:: bash
 
-   $ $VENV/bin/python setup.py test -q
+   $ $VENV/bin/pip install -e ".[testing]"
 
-Or on Windows:
+On Windows:
 
-.. code-block:: text
+.. code-block:: ps1con
+
+   > %VENV%\Scripts\pip install -e ".[testing]"
+
+Once the testing requirements are installed, then you can run the tests using
+the ``py.test`` command that was just installed in the ``bin`` directory of
+your virtual environment.
+
+On UNIX:
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test myproject/tests.py -q
+
+On Windows:
+
+.. code-block:: ps1con
 
-   > %VENV%\Scripts\python.exe setup.py test -q
+   > %VENV%\Scripts\py.test myproject\tests.py -q
 
 Here's sample output from a test run on UNIX:
 
 .. code-block:: bash
 
-   $ $VENV/bin/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'
-   reading manifest template 'MANIFEST.in'
-   warning: no files found matching '*.cfg'
-   warning: no files found matching '*.rst'
-   warning: no files found matching '*.ico' under directory 'myproject'
-   warning: no files found matching '*.gif' under directory 'myproject'
-   warning: no files found matching '*.jpg' under directory 'myproject'
-   warning: no files found matching '*.txt' under directory 'myproject'
-   warning: no files found matching '*.mak' under directory 'myproject'
-   warning: no files found matching '*.mako' under directory 'myproject'
-   warning: no files found matching '*.js' under directory 'myproject'
-   warning: no files found matching '*.html' under directory 'myproject'
-   warning: no files found matching '*.xml' under directory 'myproject'
-   writing manifest file 'MyProject.egg-info/SOURCES.txt'
-   running build_ext
-   .
-   ----------------------------------------------------------------------
-   Ran 1 test in 0.008s
-
-   OK
+   $ $VENV/bin/py.test myproject/tests.py -q
+   ..
+   2 passed in 0.47 seconds
 
 The tests themselves are found in the ``tests.py`` module in your ``pcreate``
-generated project.  Within a project generated by the ``starter`` scaffold, a
-single sample test exists.
+generated project.  Within a project generated by the ``starter`` scaffold,
+only two sample tests exist.
 
 .. note::
 
-    The ``-q`` option is passed to the ``setup.py test`` command to limit the
-    output to a stream of dots.  If you don't pass ``-q``, you'll see more
-    verbose test result output (which normally isn't very useful).
+    The ``-q`` option is passed to the ``py.test`` command to limit the output
+    to a stream of dots. If you don't pass ``-q``, you'll see verbose test
+    result output (which normally isn't very useful).
 
 .. index::
    single: running an application
@@ -432,9 +412,8 @@ like this to enable the toolbar when your system contacts Pyramid:
    # .. other settings ...
    debugtoolbar.hosts = 192.168.1.1
 
-For more information about what the debug toolbar allows you to do, see `the
-documentation for pyramid_debugtoolbar
-<http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest/>`_.
+For more information about what the debug toolbar allows you to do, see the
+:ref:`documentation for pyramid_debugtoolbar <toolbar:overview>`.
 
 The debug toolbar will not be shown (and all debugging will be turned off) when
 you use the ``production.ini`` file instead of the ``development.ini`` ini file
@@ -688,16 +667,16 @@ control system, you may need to install a setuptools add-on such as
 ~~~~~~~~~~~~
 
 The ``setup.py`` file is a :term:`setuptools` setup file.  It is meant to be
-run directly from the command line to perform a variety of functions, such as
-testing, packaging, and distributing your application.
+used to define requirements for installing dependencies for your package and
+testing, as well as distributing your application.
 
 .. note::
 
    ``setup.py`` is the de facto standard which Python developers use to
    distribute their reusable code.  You can read more about ``setup.py`` files
-   and their usage in the `Setuptools documentation
-   <http://peak.telecommunity.com/DevCenter/setuptools>`_ and `Python Packaging
-   User Guide <https://packaging.python.org/en/latest/>`_.
+   and their usage in the `Python Packaging User Guide
+   <https://packaging.python.org/en/latest/>`_ and `Setuptools documentation
+   <http://pythonhosted.org/setuptools/>`_.
 
 Our generated ``setup.py`` looks like this:
 
@@ -706,7 +685,7 @@ Our generated ``setup.py`` looks like this:
    :linenos:
 
 The ``setup.py`` file calls the setuptools ``setup`` function, which does
-various things depending on the arguments passed to ``setup.py`` on the command
+various things depending on the arguments passed to ``pip`` on the command
 line.
 
 Within the arguments to this function call, information about your application
@@ -717,8 +696,8 @@ exists in this file in this section.
 Your application's name can be any string; it is specified in the ``name``
 field.  The version number is specified in the ``version`` value.  A short
 description is provided in the ``description`` field.  The ``long_description``
-is conventionally the content of the README and CHANGES file appended together.
-The ``classifiers`` field is a list of `Trove
+is conventionally the content of the ``README`` and ``CHANGES`` files appended
+together. The ``classifiers`` field is a list of `Trove
 <http://pypi.python.org/pypi?%3Aaction=list_classifiers>`_ classifiers
 describing your application.  ``author`` and ``author_email`` are text fields
 which probably don't need any description.  ``url`` is a field that should
@@ -726,14 +705,13 @@ point at your application project's URL (if any). ``packages=find_packages()``
 causes all packages within the project to be found when packaging the
 application.  ``include_package_data`` will include non-Python files when the
 application is packaged if those files are checked into version control. 
-``zip_safe`` indicates that this package is not safe to use as a zipped egg;
-instead it will always unpack as a directory, which is more convenient. 
-``install_requires`` and ``tests_require`` indicate that this package depends
-on the ``pyramid`` package.  ``test_suite`` points at the package for our
-application, which means all tests found in the package will be run when
-``setup.py test`` is invoked.  We examined ``entry_points`` in our discussion
-of the ``development.ini`` file; this file defines the ``main`` entry point
-that represents our project's application.
+``zip_safe=False`` indicates that this package is not safe to use as a zipped
+egg; instead it will always unpack as a directory, which is more convenient.
+``install_requires`` indicate that this package depends on the ``pyramid``
+package. ``extras_require`` is a Python dictionary that defines what is
+required to be installed for running tests. We examined ``entry_points`` in our
+discussion of the ``development.ini`` file; this file defines the ``main``
+entry point that represents our project's application.
 
 Usually you only need to think about the contents of the ``setup.py`` file when
 distributing your application to other people, when adding Python package
@@ -745,7 +723,7 @@ you can try this command now:
    $ $VENV/bin/python setup.py sdist
 
 This will create a tarball of your application in a ``dist`` subdirectory named
-``MyProject-0.1.tar.gz``.  You can send this tarball to other people who want
+``MyProject-0.0.tar.gz``.  You can send this tarball to other people who want
 to install and use your application.
 
 .. index::
@@ -928,13 +906,13 @@ The ``tests.py`` module includes unit tests for your application.
 
 .. literalinclude:: MyProject/myproject/tests.py
    :language: python
-   :lines: 1-17
    :linenos:
 
-This sample ``tests.py`` file has a single unit test defined within it.  This
-test is executed when you run ``python setup.py test``.  You may add more tests
-here as you build your application.  You are not required to write tests to use
-:app:`Pyramid`. This file is simply provided for convenience and example.
+This sample ``tests.py`` file has one unit test and one functional test defined
+within it. These tests are executed when you run ``py.test myproject/tests.py
+-q``. You may add more tests here as you build your application. You are not
+required to write tests to use :app:`Pyramid`. This file is simply provided for
+convenience and example.
 
 See :ref:`testing_chapter` for more information about writing :app:`Pyramid`
 unit tests.
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
index e02142e6e..e45e6f4a8 100644
--- a/docs/narr/router.rst
+++ b/docs/narr/router.rst
@@ -41,19 +41,24 @@ request enters a :app:`Pyramid` application through to the point that
    user-defined :term:`route` matches the current WSGI environment.  The
    :term:`router` passes the request as an argument to the mapper.
 
-#. If any route matches, the route mapper adds attributes to the request:
-   ``matchdict`` and ``matched_route`` attributes are added to the request
-   object.  The former contains a dictionary representing the matched dynamic
-   elements of the request's ``PATH_INFO`` value, and the latter contains the
+#. If any route matches, the route mapper adds the attributes ``matchdict``
+   and ``matched_route`` to the request object. The former contains a
+   dictionary representing the matched dynamic elements of the request's
+   ``PATH_INFO`` value, and the latter contains the
    :class:`~pyramid.interfaces.IRoute` object representing the route which
-   matched.  The root object associated with the route found is also generated:
-   if the :term:`route configuration` which matched has an associated
-   ``factory`` argument, this factory is used to generate the root object,
-   otherwise a default :term:`root factory` is used.
+   matched.
 
-#. If a route match was *not* found, and a ``root_factory`` argument was passed
+#. A :class:`~pyramid.events.BeforeTraversal` :term:`event` is sent to any
+   subscribers.
+
+#. Continuing, if any route matches, the root object associated with the found
+   route is generated. If the :term:`route configuration` which matched has an
+   associated ``factory`` argument, then this factory is used to generate the
+   root object; otherwise a default :term:`root factory` is used.
+
+   However, if no route matches, and if a ``root_factory`` argument was passed
    to the :term:`Configurator` constructor, that callable is used to generate
-   the root object.  If the ``root_factory`` argument passed to the
+   the root object. If the ``root_factory`` argument passed to the
    Configurator constructor was ``None``, a default root factory is used to
    generate a root object.
 
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index a3f62058b..354a462d4 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -275,7 +275,7 @@ without needing to invoke the actual application configuration implied by its
            
 In the above example, we create a ``MyTest`` test case that inherits from
 :class:`unittest.TestCase`.  If it's in our :app:`Pyramid` application, it will
-be found when ``setup.py test`` is run.  It has two test methods.
+be found when ``py.test`` is run.  It has two test methods.
 
 The first test method, ``test_view_fn_forbidden`` tests the ``view_fn`` when
 the authentication policy forbids the current user the ``edit`` permission. Its
@@ -365,46 +365,37 @@ Functional tests test your literal application.
 
 In Pyramid, functional tests are typically written using the :term:`WebTest`
 package, which provides APIs for invoking HTTP(S) requests to your application.
+We also like ``py.test`` and ``pytest-cov`` to provide simple testing and
+coverage reports.
 
-Regardless of which testing :term:`package` you use, ensure to add a
-``tests_require`` dependency on that package to your application's
-``setup.py`` file.  Using the project ``MyProject`` generated by the starter
-scaffold as described in :doc:`project`, we would insert the following code immediately following the
-``requires`` block in the file ``MyProject/setup.py``.
+Regardless of which testing :term:`package` you use, be sure to add a
+``tests_require`` dependency on that package to your application's ``setup.py``
+file. Using the project ``MyProject`` generated by the starter scaffold as
+described in :doc:`project`, we would insert the following code immediately
+following the ``requires`` block in the file ``MyProject/setup.py``.
 
-.. code-block:: ini
+.. literalinclude:: MyProject/setup.py
+    :language: python
     :linenos:
+    :lines: 11-22
     :lineno-start: 11
     :emphasize-lines: 8-
 
-    requires = [
-        'pyramid',
-        'pyramid_chameleon',
-        'pyramid_debugtoolbar',
-        'waitress',
-        ]
-
-    test_requires = [
-        'webtest',
-        ]
-
 Remember to change the dependency.
 
-.. code-block:: ini
+.. literalinclude:: MyProject/setup.py
+    :language: python
     :linenos:
-    :lineno-start: 39
-    :emphasize-lines: 2
-
-      install_requires=requires,
-      tests_require=test_requires,
-      test_suite="myproject",
+    :lines: 40-44
+    :lineno-start: 40
+    :emphasize-lines: 2-4
 
-As always, whenever you change your dependencies, make sure to run the
-following command.
+As always, whenever you change your dependencies, make sure to run the correct
+``pip install -e`` command.
 
 .. code-block:: bash
 
-    $VENV/bin/python setup.py develop
+    $VENV/bin/pip install -e ".[testing]"
 
 In your ``MyPackage`` project, your :term:`package` is named ``myproject``
 which contains a ``views`` module, which in turn contains a :term:`view`
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index cacfba92a..fcdce4f8d 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -127,8 +127,6 @@ you can see DeprecationWarnings printed to the console when the tests run.
    $ python -Wd setup.py test -q
 
 The ``-Wd`` argument tells Python to print deprecation warnings to the console.
-Note that the ``-Wd`` flag is only required for Python 2.7 and better: Python
-versions 2.6 and older print deprecation warnings to the console by default.
 See `the Python -W flag documentation
 <http://docs.python.org/using/cmdline.html#cmdoption-W>`_ for more information.