Merge upstream master

34 files changed, 1212 insertions, 773 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 a9a26e56b..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]
@@ -11,7 +11,7 @@ pyramid.debug_authorization = false
 pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.default_locale_name = en
-pyramid.includes = 
+pyramid.includes =
     pyramid_debugtoolbar
 
 # By default, the toolbar only appears for clients from IP addresses
@@ -24,12 +24,12 @@ pyramid.includes =
 
 [server:main]
 use = egg:waitress#main
-host = 0.0.0.0
+host = 127.0.0.1
 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]
@@ -57,4 +57,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
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 e6b00a145..543663fe8 100644
--- a/docs/narr/MyProject/myproject/templates/mytemplate.pt
+++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt
@@ -8,12 +8,12 @@
     <meta name="author" content="Pylons Project">
     <link rel="shortcut icon" href="${request.static_url('myproject:static/pyramid-16x16.png')}">
 
-    <title>Starter Template for The Pyramid Web Framework</title>
+    <title>Starter Scaffold for The Pyramid Web Framework</title>
 
     <!-- Bootstrap core CSS -->
     <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
 
-    <!-- Custom styles for this template -->
+    <!-- Custom styles for this scaffold -->
     <link href="${request.static_url('myproject:static/theme.css')}" rel="stylesheet">
 
     <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
@@ -33,19 +33,20 @@
           </div>
           <div class="col-md-10">
             <div class="content">
-              <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">starter template</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</span>.</p>
+              <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.7</span>.</p>
             </div>
           </div>
         </div>
         <div class="row">
           <div class="links">
             <ul>
-              <li class="current-version">Currently v1.5</li>
-              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org">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>
+            </ul>
           </div>
         </div>
         <div class="row">
diff --git a/docs/narr/MyProject/myproject/tests.py b/docs/narr/MyProject/myproject/tests.py
index 8c60407e5..fd414cced 100644
--- a/docs/narr/MyProject/myproject/tests.py
+++ b/docs/narr/MyProject/myproject/tests.py
@@ -16,31 +16,6 @@ class ViewTests(unittest.TestCase):
         info = my_view(request)
         self.assertEqual(info['project'], 'MyProject')
 
-class ViewIntegrationTests(unittest.TestCase):
-    def setUp(self):
-        """ This sets up the application registry with the
-        registrations your application declares in its ``includeme``
-        function.
-        """
-        self.config = testing.setUp()
-        self.config.include('myproject')
-
-    def tearDown(self):
-        """ Clear out the application registry """
-        testing.tearDown()
-
-    def test_my_view(self):
-        from myproject.views import my_view
-        request = testing.DummyRequest()
-        result = my_view(request)
-        self.assertEqual(result.status, '200 OK')
-        body = result.app_iter[0]
-        self.assertTrue('Welcome to' in body)
-        self.assertEqual(len(result.headerlist), 2)
-        self.assertEqual(result.headerlist[0],
-                         ('Content-Type', 'text/html; charset=UTF-8'))
-        self.assertEqual(result.headerlist[1], ('Content-Length',
-                                                str(len(body))))
 
 class FunctionalTests(unittest.TestCase):
     def setUp(self):
@@ -51,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 9eae9e03f..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]
@@ -51,4 +51,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py
index 9f34540a7..a911eff6d 100644
--- a/docs/narr/MyProject/setup.py
+++ b/docs/narr/MyProject/setup.py
@@ -1,30 +1,24 @@
-"""Setup for the MyProject package.
-
-"""
 import os
-from setuptools import setup, find_packages
-
-
-HERE = os.path.abspath(os.path.dirname(__file__))
 
+from setuptools import setup, find_packages
 
-with open(os.path.join(HERE, 'README.txt')) as fp:
-    README = fp.read()
-
-
-with open(os.path.join(HERE, 'CHANGES.txt')) as fp:
-    CHANGES = fp.read()
-
+here = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
-REQUIRES = [
+requires = [
     'pyramid',
     'pyramid_chameleon',
     'pyramid_debugtoolbar',
     'waitress',
     ]
 
-TESTS_REQUIRE = [
-    'webtest'
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
     ]
 
 setup(name='MyProject',
@@ -32,10 +26,10 @@ setup(name='MyProject',
       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='',
@@ -44,10 +38,12 @@ setup(name='MyProject',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      install_requires=REQUIRES,
-      tests_require=TESTS_REQUIRE,
-      test_suite='myproject',
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
       entry_points="""\
       [paste.app_factory]
       main = myproject:main
-      """)
+      """,
+      )
diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index ba9bd1352..bdcdf45a4 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -417,7 +417,6 @@ added in configuration execution order.
 More Information
 ----------------
 
-For more information, see the article `"A Whirlwind Tour of Advanced
-Configuration Tactics"
-<http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/configuration/whirlwind_tour.html>`_
-in the Pyramid Cookbook.
+For more information, see the article :ref:`A Whirlwind Tour of Advanced
+Configuration Tactics <cookbook:whirlwind-adv-conf>` in the Pyramid Community
+Cookbook.
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 0f819570c..58f547fc9 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -366,8 +366,7 @@ resource and requests the asset, regardless of any caching policy set for the
 resource's old URL.
 
 :app:`Pyramid` can be configured to produce cache busting URLs for static
-assets by passing the optional argument, ``cachebust`` to
-:meth:`~pyramid.config.Configurator.add_static_view`:
+assets using :meth:`~pyramid.config.Configurator.add_cache_buster`:
 
 .. code-block:: python
    :linenos:
@@ -376,14 +375,13 @@ assets by passing the optional argument, ``cachebust`` to
    from pyramid.static import QueryStringConstantCacheBuster
 
    # config is an instance of pyramid.config.Configurator
-   config.add_static_view(
-       name='static', path='mypackage:folder/static',
-       cachebust=QueryStringConstantCacheBuster(str(int(time.time()))),
-   )
+   config.add_static_view(name='static', path='mypackage:folder/static/')
+   config.add_cache_buster(
+       'mypackage:folder/static/',
+       QueryStringConstantCacheBuster(str(int(time.time()))))
 
-Setting the ``cachebust`` argument instructs :app:`Pyramid` to use a cache
-busting scheme which adds the curent time for a static asset to the query
-string in the asset's URL:
+Adding the cachebuster instructs :app:`Pyramid` to add the current time for
+a static asset to the query string in the asset's URL:
 
 .. code-block:: python
    :linenos:
@@ -392,10 +390,7 @@ string in the asset's URL:
    # Returns: 'http://www.example.com/static/js/myapp.js?x=1445318121'
 
 When the web server restarts, the time constant will change and therefore so
-will its URL.  Supplying the ``cachebust`` argument also causes the static
-view to set headers instructing clients to cache the asset for ten years,
-unless the ``cache_max_age`` argument is also passed, in which case that
-value is used.
+will its URL.
 
 .. note::
 
@@ -410,7 +405,7 @@ Disabling the Cache Buster
 
 It can be useful in some situations (e.g., development) to globally disable all
 configured cache busters without changing calls to
-:meth:`~pyramid.config.Configurator.add_static_view`.  To do this set the
+:meth:`~pyramid.config.Configurator.add_cache_buster`.  To do this set the
 ``PYRAMID_PREVENT_CACHEBUST`` environment variable or the
 ``pyramid.prevent_cachebust`` configuration value to a true value.
 
@@ -419,9 +414,9 @@ configured cache busters without changing calls to
 Customizing the Cache Buster
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``cachebust`` option to
-:meth:`~pyramid.config.Configurator.add_static_view` may be set to any object
-that implements the interface :class:`~pyramid.interfaces.ICacheBuster`.
+Calls to :meth:`~pyramid.config.Configurator.add_cache_buster` may use
+any object that implements the interface
+:class:`~pyramid.interfaces.ICacheBuster`.
 
 :app:`Pyramid` ships with a very simplistic
 :class:`~pyramid.static.QueryStringConstantCacheBuster`, which adds an
@@ -451,18 +446,45 @@ the hash of the current commit:
        from an egg repository like PYPI, you can use this cachebuster to get
        the current commit's SHA1 to use as the cache bust token.
        """
-       def __init__(self, param='x'):
+       def __init__(self, param='x', repo_path=None):
            super(GitCacheBuster, self).__init__(param=param)
-           here = os.path.dirname(os.path.abspath(__file__))
+           if repo_path is None:
+               repo_path = os.path.dirname(os.path.abspath(__file__))
            self.sha1 = subprocess.check_output(
                ['git', 'rev-parse', 'HEAD'],
-               cwd=here).strip()
+               cwd=repo_path).strip()
 
        def tokenize(self, pathspec):
            return self.sha1
 
-Choosing a Cache Buster
-~~~~~~~~~~~~~~~~~~~~~~~
+A simple cache buster that modifies the path segment can be constructed as
+well:
+
+.. code-block:: python
+   :linenos:
+
+   import posixpath
+
+   class PathConstantCacheBuster(object):
+       def __init__(self, token):
+           self.token = token
+
+       def __call__(self, request, subpath, kw):
+           base_subpath, ext = posixpath.splitext(subpath)
+           new_subpath = base_subpath + self.token + ext
+           return new_subpath, kw
+
+The caveat with this approach is that modifying the path segment
+changes the file name, and thus must match what is actually on the
+filesystem in order for :meth:`~pyramid.config.Configurator.add_static_view`
+to find the file. It's better to use the
+:class:`~pyramid.static.ManifestCacheBuster` for these situations, as
+described in the next section.
+
+.. _path_segment_cache_busters:
+
+Path Segments and Choosing a Cache Buster
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Many caching HTTP proxies will fail to cache a resource if the URL contains
 a query string.  Therefore, in general, you should prefer a cache busting
@@ -504,28 +526,19 @@ The following code would set up a cachebuster:
 
    config.add_static_view(
        name='http://mycdn.example.com/',
-       path='mypackage:static',
-       cachebust=ManifestCacheBuster('myapp:static/manifest.json'))
-
-A simpler approach is to use the
-:class:`~pyramid.static.QueryStringConstantCacheBuster` to generate a global
-token that will bust all of the assets at once. The advantage of this strategy
-is that it is simple and by using the query string there doesn't need to be
-any shared information between your application and the static assets.
-
-The following code would set up a cachebuster that just uses the time at
-start up as a cachebust token:
+       path='mypackage:static')
 
-.. code-block:: python
-   :linenos:
-
-   import time
-   from pyramid.static import QueryStringConstantCacheBuster
+   config.add_cache_buster(
+       'mypackage:static/',
+       ManifestCacheBuster('myapp:static/manifest.json'))
 
-   config.add_static_view(
-       name='http://mycdn.example.com/',
-       path='mypackage:static',
-       cachebust=QueryStringConstantCacheBuster(str(int(time.time()))))
+It's important to note that the cache buster only handles generating
+cache-busted URLs for static assets. It does **NOT** provide any solutions for
+serving those assets. For example, if you generated a URL for
+``css/main-678b7c80.css`` then that URL needs to be valid either by
+configuring ``add_static_view`` properly to point to the location of the files
+or some other mechanism such as the files existing on your CDN or rewriting
+the incoming URL to remove the cache bust tokens.
 
 .. index::
    single: static assets view
@@ -536,25 +549,38 @@ CSS and JavaScript source and cache busting
 Often one needs to refer to images and other static assets inside CSS and
 JavaScript files. If cache busting is active, the final static asset URL is not
 available until the static assets have been assembled. These URLs cannot be
-handwritten. Thus, when having static asset references in CSS and JavaScript,
-one needs to perform one of the following tasks:
+handwritten. Below is an example of how to integrate the cache buster into
+the entire stack. Remember, it is just an example and should be modified to
+fit your specific tools.
 
-* Process the files by using a precompiler which rewrites URLs to their final
-  cache busted form. Then, you can use the
+* First, process the files by using a precompiler which rewrites URLs to their
+  final cache-busted form. Then, you can use the
   :class:`~pyramid.static.ManifestCacheBuster` to synchronize your asset
   pipeline with :app:`Pyramid`, allowing the pipeline to have full control
   over the final URLs of your assets.
 
-* Templatize JS and CSS, and call ``request.static_url()`` inside their
-  template code.
+Now that you are able to generate static URLs within :app:`Pyramid`,
+you'll need to handle URLs that are out of our control. To do this you may
+use some of the following options to get started:
 
-* Pass static URL references to CSS and JavaScript via other means.
+* Configure your asset pipeline to rewrite URL references inline in
+  CSS and JavaScript. This is the best approach because then the files
+  may be hosted by :app:`Pyramid` or an external CDN without having to
+  change anything. They really are static.
+
+* Templatize JS and CSS, and call ``request.static_url()`` inside their
+  template code. While this approach may work in certain scenarios, it is not
+  recommended because your static assets will not really be static and are now
+  dependent on :app:`Pyramid` to be served correctly. See
+  :ref:`advanced_static` for more information on this approach.
 
 If your CSS and JavaScript assets use URLs to reference other assets it is
 recommended that you implement an external asset pipeline that can rewrite the
 generated static files with new URLs containing cache busting tokens. The
 machinery inside :app:`Pyramid` will not help with this step as it has very
-little knowledge of the asset types your application may use.
+little knowledge of the asset types your application may use. The integration
+into :app:`Pyramid` is simply for linking those assets into your HTML and
+other dynamic content.
 
 .. _advanced_static:
 
@@ -793,3 +819,56 @@ when an override is used.
   As of Pyramid 1.6, it is also possible to override an asset by supplying an
   absolute path to a file or directory. This may be useful if the assets are
   not distributed as part of a Python package.
+
+Cache Busting and Asset Overrides
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Overriding static assets that are being hosted using
+:meth:`pyramid.config.Configurator.add_static_view` can affect your cache
+busting strategy when using any cache busters that are asset-aware such as
+:class:`pyramid.static.ManifestCacheBuster`. What sets asset-aware cache
+busters apart is that they have logic tied to specific assets. For example,
+a manifest is only generated for a specific set of pre-defined assets. Now,
+imagine you have overridden an asset defined in this manifest with a new,
+unknown version. By default, the cache buster will be invoked for an asset
+it has never seen before and will likely end up returning a cache busting
+token for the original asset rather than the asset that will actually end up
+being served! In order to get around this issue, it's possible to attach a
+different :class:`pyramid.interfaces.ICacheBuster` implementation to the
+new assets. This would cause the original assets to be served by their
+manifest, and the new assets served by their own cache buster. To do this,
+:meth:`pyramid.config.Configurator.add_cache_buster` supports an ``explicit``
+option. For example:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.static import ManifestCacheBuster
+
+   # define a static view for myapp:static assets
+   config.add_static_view('static', 'myapp:static')
+
+   # setup a cache buster for your app based on the myapp:static assets
+   my_cb = ManifestCacheBuster('myapp:static/manifest.json')
+   config.add_cache_buster('myapp:static', my_cb)
+
+   # override an asset
+   config.override_asset(
+       to_override='myapp:static/background.png',
+       override_with='theme:static/background.png')
+
+   # override the cache buster for theme:static assets
+   theme_cb = ManifestCacheBuster('theme:static/manifest.json')
+   config.add_cache_buster('theme:static', theme_cb, explicit=True)
+
+In the above example there is a default cache buster, ``my_cb``, for all
+assets served from the ``myapp:static`` folder. This would also affect
+``theme:static/background.png`` when generating URLs via
+``request.static_url('myapp:static/background.png')``.
+
+The ``theme_cb`` is defined explicitly for any assets loaded from the
+``theme:static`` folder. Explicit cache busters have priority and thus
+``theme_cb`` would be invoked for
+``request.static_url('myapp:static/background.png')``, but ``my_cb`` would
+be used for any other assets like
+``request.static_url('myapp:static/favicon.ico')``.
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index eb79dffb6..6cd90d42f 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -6,6 +6,7 @@ Command-Line Pyramid
 Your :app:`Pyramid` application can be controlled and inspected using a variety
 of command-line utilities.  These utilities are documented in this chapter.
 
+
 .. index::
    pair: matching views; printing
    single: pviews
@@ -15,6 +16,8 @@ of command-line utilities.  These utilities are documented in this chapter.
 Displaying Matching Views for a Given URL
 -----------------------------------------
 
+.. seealso:: See also the output of :ref:`pviews --help <pviews_script>`.
+
 For a big application with several views, it can be hard to keep the view
 configuration details in your head, even if you defined all the views yourself.
 You can use the ``pviews`` command in a terminal window to print a summary of
@@ -114,7 +117,9 @@ found* message.
 The Interactive Shell
 ---------------------
 
-Once you've installed your program for development using ``setup.py develop``,
+.. seealso:: See also the output of :ref:`pshell --help <pshell_script>`.
+
+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.
@@ -179,6 +184,7 @@ hash after the filename:
 
 Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
 
+
 .. index::
    pair: pshell; extending
 
@@ -261,6 +267,7 @@ request is configured to generate urls from the host
     >>> request.route_url('home')
     'https://www.example.com/'
 
+
 .. _ipython_or_bpython:
 
 Alternative Shells
@@ -287,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
 
@@ -317,6 +324,7 @@ arguments, ``env`` and ``help``, which would look like this:
    ``ipython`` and ``bpython`` have been moved into their respective
    packages ``pyramid_ipython`` and ``pyramid_bpython``.
 
+
 Setting a Default Shell
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -331,6 +339,7 @@ specify a list of preferred shells.
 
 .. versionadded:: 1.6
 
+
 .. index::
    pair: routes; printing
    single: proutes
@@ -340,6 +349,8 @@ specify a list of preferred shells.
 Displaying All Application Routes
 ---------------------------------
 
+.. seealso:: See also the output of :ref:`proutes --help <proutes_script>`.
+
 You can use the ``proutes`` command in a terminal window to print a summary of
 routes related to your application.  Much like the ``pshell`` command (see
 :ref:`interactive_shell`), the ``proutes`` command accepts one argument with
@@ -421,6 +432,8 @@ include. The current available formats are ``name``, ``pattern``, ``view``, and
 Displaying "Tweens"
 -------------------
 
+.. seealso:: See also the output of :ref:`ptweens --help <ptweens_script>`.
+
 A :term:`tween` is a bit of code that sits between the main Pyramid application
 request handler and the WSGI application which calls it.  A user can get a
 representation of both the implicit tween ordering (the ordering specified by
@@ -497,6 +510,7 @@ used:
 
 See :ref:`registering_tweens` for more information about tweens.
 
+
 .. index::
    single: invoking a request
    single: prequest
@@ -506,6 +520,8 @@ See :ref:`registering_tweens` for more information about tweens.
 Invoking a Request
 ------------------
 
+.. seealso:: See also the output of :ref:`prequest --help <prequest_script>`.
+
 You can use the ``prequest`` command-line utility to send a request to your
 application and see the response body without starting a server.
 
@@ -555,22 +571,34 @@ of the ``prequest`` process is used as the ``POST`` body::
 
    $ $VENV/bin/prequest -mPOST development.ini / < somefile
 
+
 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::
+   single: pdistreport
+   single: distributions, showing installed
+   single: showing installed distributions
+
+.. _showing_distributions:
 
 Showing All Installed Distributions and Their Versions
 ------------------------------------------------------
 
 .. versionadded:: 1.5
 
+.. seealso:: See also the output of :ref:`pdistreport --help
+   <pdistreport_script>`.
+
 You can use the ``pdistreport`` command to show the :app:`Pyramid` version in
 use, the Python version in use, and all installed versions of Python
 distributions in your Python environment::
@@ -590,6 +618,7 @@ pastebin when you are having problems and need someone with more familiarity
 with Python packaging and distribution than you have to look at your
 environment.
 
+
 .. _writing_a_script:
 
 Writing a Script
@@ -702,6 +731,7 @@ The above example specifies the ``another`` ``app``, ``pipeline``, or
 object present in the ``env`` dictionary returned by
 :func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router`.
 
+
 Changing the Request
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -742,6 +772,7 @@ Now you can readily use Pyramid's APIs for generating URLs:
    env['request'].route_url('verify', code='1337')
    # will return 'https://example.com/prefix/verify/1337'
 
+
 Cleanup
 ~~~~~~~
 
@@ -757,6 +788,7 @@ callback:
 
    env['closer']()
 
+
 Setting Up Logging
 ~~~~~~~~~~~~~~~~~~
 
@@ -773,6 +805,7 @@ use the following command:
 See :ref:`logging_chapter` for more information on logging within
 :app:`Pyramid`.
 
+
 .. index::
    single: console script
 
@@ -782,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:
@@ -807,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
@@ -894,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='',
@@ -912,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:
 
-  [console_scripts]
-  show_settings = myproject.scripts:settings_show
+.. code-block:: ini
+
+   [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
@@ -938,6 +979,7 @@ The result will be something like:
 
 .. code-block:: python
    :linenos:
+   :emphasize-lines: 43-44
 
    import os
 
@@ -951,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='',
@@ -969,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
@@ -979,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/extconfig.rst b/docs/narr/extconfig.rst
index fee8d0d3a..babfa0a98 100644
--- a/docs/narr/extconfig.rst
+++ b/docs/narr/extconfig.rst
@@ -259,7 +259,9 @@ Pre-defined Phases
 - :meth:`pyramid.config.Configurator.add_route_predicate`
 - :meth:`pyramid.config.Configurator.add_subscriber_predicate`
 - :meth:`pyramid.config.Configurator.add_view_predicate`
+- :meth:`pyramid.config.Configurator.add_view_deriver`
 - :meth:`pyramid.config.Configurator.set_authorization_policy`
+- :meth:`pyramid.config.Configurator.set_default_csrf_options`
 - :meth:`pyramid.config.Configurator.set_default_permission`
 - :meth:`pyramid.config.Configurator.set_view_mapper`
 
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/firstapp.rst b/docs/narr/firstapp.rst
index 6a952dec9..ad05976c0 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -27,15 +27,15 @@ installed, an HTTP server is started on TCP port 8080.
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/python helloworld.py
 
 On Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   C:\> %VENV%\Scripts\python.exe helloworld.py
+   c:\> %VENV%\Scripts\python helloworld.py
 
 This command will not return and nothing will be printed to the console. When
 port 8080 is visited by a browser on the URL ``/hello/world``, the server will
@@ -197,7 +197,7 @@ method returns a :term:`WSGI` application object that can be used by any WSGI
 server to present an application to a requestor. :term:`WSGI` is a protocol
 that allows servers to talk to Python applications.  We don't discuss
 :term:`WSGI` in any depth within this book, but you can learn more about it by
-visiting `wsgi.org <http://wsgi.org>`_.
+reading its `documentation <http://wsgi.readthedocs.org/en/latest/>`_.
 
 The :app:`Pyramid` application object, in particular, is an instance of a class
 representing a :app:`Pyramid` :term:`router`.  It has a reference to the
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 6aa1a99c2..49ef29d3f 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -262,7 +262,7 @@ already constructed a :term:`configurator`, it can also be registered via the
 Adding Methods or Properties to a Request Object
 ------------------------------------------------
 
-.. versionadded:: 1.4.
+.. versionadded:: 1.4
 
 Since each Pyramid application can only have one :term:`request` factory,
 :ref:`changing the request factory <changing_the_request_factory>` is not that
@@ -300,13 +300,38 @@ added as a property and its result is cached per-request by setting
 ``reify=True``. This way, we eliminate the overhead of running the function
 multiple times.
 
+.. testsetup:: group1
+
+   from pyramid.config import Configurator
+
+
+   def total(request, *args):
+       return sum(args)
+
+
+   def prop(request):
+       print("getting the property")
+       return "the property"
+
+
+
+   config = Configurator()
+   config.add_request_method(total)
+   config.add_request_method(prop, reify=True)
+   config.commit()
+
+   from pyramid.scripting import prepare
+   request = prepare(registry=config.registry)["request"]
+
+.. doctest:: group1
+
    >>> request.total(1, 2, 3)
    6
    >>> request.prop
    getting the property
-   the property
+   'the property'
    >>> request.prop
-   the property
+   'the property'
 
 To not cache the result of ``request.prop``, set ``property=True`` instead of
 ``reify=True``.
@@ -338,13 +363,42 @@ Here is an example of passing a class to ``Configurator.add_request_method``:
 
 We attach and cache an object named ``extra`` to the ``request`` object.
 
+.. testsetup:: group2
+
+   from pyramid.config import Configurator
+   from pyramid.decorator import reify
+
+   class ExtraStuff(object):
+
+       def __init__(self, request):
+           self.request = request
+
+       def total(self, *args):
+           return sum(args)
+
+       # use @property if you don't want to cache the result
+       @reify
+       def prop(self):
+           print("getting the property")
+           return "the property"
+
+   config = Configurator()
+   config.add_request_method(ExtraStuff, 'extra', reify=True)
+   config.commit()
+
+   from pyramid.scripting import prepare
+   request = prepare(registry=config.registry)["request"]
+
+.. doctest:: group2
+
    >>> request.extra.total(1, 2, 3)
    6
    >>> request.extra.prop
    getting the property
-   the property
+   'the property'
    >>> request.extra.prop
-   the property
+   'the property'
+
 
 .. index::
    single: response factory
@@ -1547,3 +1601,185 @@ in every subscriber registration.  It is not the responsibility of the
 predicate author to make every predicate make sense for every event type; it is
 the responsibility of the predicate consumer to use predicates that make sense
 for a particular event type registration.
+
+
+.. index::
+   single: view derivers
+
+.. _view_derivers:
+
+View Derivers
+-------------
+
+.. versionadded:: 1.7
+
+Every URL processed by :app:`Pyramid` is matched against a custom view
+pipeline. See :ref:`router_chapter` for how this works. The view pipeline
+itself is built from the user-supplied :term:`view callable`, which is then
+composed with :term:`view derivers <view deriver>`. A view deriver is a
+composable element of the view pipeline which is used to wrap a view with
+added functionality. View derivers are very similar to the ``decorator``
+argument to :meth:`pyramid.config.Configurator.add_view`, except that they have
+the option to execute for every view in the application.
+
+It is helpful to think of a :term:`view deriver` as middleware for views.
+Unlike tweens or WSGI middleware which are scoped to the application itself,
+a view deriver is invoked once per view in the application, and can use
+configuration options from the view to customize its behavior.
+
+Built-in View Derivers
+~~~~~~~~~~~~~~~~~~~~~~
+
+There are several built-in view derivers that :app:`Pyramid` will automatically
+apply to any view. Below they are defined in order from furthest to closest to
+the user-defined :term:`view callable`:
+
+``secured_view``
+
+  Enforce the ``permission`` defined on the view. This element is a no-op if no
+  permission is defined. Note there will always be a permission defined if a
+  default permission was assigned via
+  :meth:`pyramid.config.Configurator.set_default_permission`.
+
+  This element will also output useful debugging information when
+  ``pyramid.debug_authorization`` is enabled.
+
+``csrf_view``
+
+  Used to check the CSRF token provided in the request. This element is a
+  no-op if ``require_csrf`` view option is not ``True``. Note there will
+  always be a ``require_csrf`` option if a default value was assigned via
+  :meth:`pyramid.config.Configurator.set_default_csrf_options`.
+
+``owrapped_view``
+
+  Invokes the wrapped view defined by the ``wrapper`` option.
+
+``http_cached_view``
+
+  Applies cache control headers to the response defined by the ``http_cache``
+  option. This element is a no-op if the ``pyramid.prevent_http_cache`` setting
+  is enabled or the ``http_cache`` option is ``None``.
+
+``decorated_view``
+
+  Wraps the view with the decorators from the ``decorator`` option.
+
+``rendered_view``
+
+  Adapts the result of the :term:`view callable` into a :term:`response`
+  object. Below this point the result may be any Python object.
+
+``mapped_view``
+
+  Applies the :term:`view mapper` defined by the ``mapper`` option or the
+  application's default view mapper to the :term:`view callable`. This
+  is always the closest deriver to the user-defined view and standardizes the
+  view pipeline interface to accept ``(context, request)`` from all previous
+  view derivers.
+
+.. warning::
+
+   Any view derivers defined ``under`` the ``rendered_view`` are not
+   guaranteed to receive a valid response object. Rather they will receive the
+   result from the :term:`view mapper` which is likely the original response
+   returned from the view. This is possibly a dictionary for a renderer but it
+   may be any Python object that may be adapted into a response.
+
+Custom View Derivers
+~~~~~~~~~~~~~~~~~~~~
+
+It is possible to define custom view derivers which will affect all views in an
+application. There are many uses for this, but most will likely be centered
+around monitoring and security. In order to register a custom :term:`view
+deriver`, you should create a callable that conforms to the
+:class:`pyramid.interfaces.IViewDeriver` interface, and then register it with
+your application using :meth:`pyramid.config.Configurator.add_view_deriver`.
+For example, below is a callable that can provide timing information for the
+view pipeline:
+
+.. code-block:: python
+   :linenos:
+
+   import time
+
+   def timing_view(view, info):
+       if info.options.get('timed'):
+           def wrapper_view(context, request):
+               start = time.time()
+               response = view(context, request)
+               end = time.time()
+               response.headers['X-View-Performance'] = '%.3f' % (end - start,)
+               return response
+           return wrapper_view
+       return view
+
+   timing_view.options = ('timed',)
+
+   config.add_view_deriver(timing_view)
+
+The setting of ``timed`` on the timing_view signifies to Pyramid that ``timed``
+is a valid ``view_config`` keyword argument now.  The ``timing_view`` custom
+view deriver as registered above will only be active for any view defined with
+a ``timed=True`` value passed as one of its ``view_config`` keywords.
+
+For example, this view configuration will *not* be a timed view:
+
+.. code-block:: python
+   :linenos:
+
+   @view_config(route_name='home')
+   def home(request):
+       return Response('Home')
+
+But this view *will* have timing information added to the response headers:
+
+.. code-block:: python
+   :linenos:
+
+   @view_config(route_name='home', timed=True)
+   def home(request):
+       return Response('Home')
+
+View derivers are unique in that they have access to most of the options
+passed to :meth:`pyramid.config.Configurator.add_view` in order to decide what
+to do, and they have a chance to affect every view in the application.
+
+Ordering View Derivers
+~~~~~~~~~~~~~~~~~~~~~~
+
+By default, every new view deriver is added between the ``decorated_view`` and
+``rendered_view`` built-in derivers. It is possible to customize this ordering
+using the ``over`` and ``under`` options. Each option can use the names of
+other view derivers in order to specify an ordering. There should rarely be a
+reason to worry about the ordering of the derivers except when the deriver
+depends on other operations in the view pipeline.
+
+Both ``over`` and ``under`` may also be iterables of constraints. For either
+option, if one or more constraints was defined, at least one must be satisfied,
+else a :class:`pyramid.exceptions.ConfigurationError` will be raised. This may
+be used to define fallback constraints if another deriver is missing.
+
+Two sentinel values exist, :attr:`pyramid.viewderivers.INGRESS` and
+:attr:`pyramid.viewderivers.VIEW`, which may be used when specifying
+constraints at the edges of the view pipeline. For example, to add a deriver
+at the start of the pipeline you may use ``under=INGRESS``.
+
+It is not possible to add a view deriver under the ``mapped_view`` as the
+:term:`view mapper` is intimately tied to the signature of the user-defined
+:term:`view callable`. If you simply need to know what the original view
+callable was, it can be found as ``info.original_view`` on the provided
+:class:`pyramid.interfaces.IViewDeriverInfo` object passed to every view
+deriver.
+
+.. warning::
+
+   The default constraints for any view deriver are ``over='rendered_view'``
+   and ``under='decorated_view'``. When escaping these constraints you must
+   take care to avoid cyclic dependencies between derivers. For example, if
+   you want to add a new view deriver before ``secured_view`` then
+   simply specifying ``over='secured_view'`` is not enough, because the
+   default is also under ``decorated view`` there will be an unsatisfiable
+   cycle. You must specify a valid ``under`` constraint as well, such as
+   ``under=INGRESS`` to fall between INGRESS and ``secured_view`` at the
+   beginning of the view pipeline.
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index bb0bbe511..3549b53a5 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:: doscon
 
-   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
@@ -342,7 +343,7 @@ This will create a new message catalog ``.po`` file in
 ``myapplication/locale/es/LC_MESSAGES/myapplication.po``.
 
 Once the file is there, it can be worked on by a human translator. One tool
-which may help with this is `Poedit <http://www.poedit.net/>`_.
+which may help with this is `Poedit <https://poedit.net/>`_.
 
 Note that :app:`Pyramid` itself ignores the existence of all ``.po`` files.
 For a running application to have translations available, a ``.mo`` file must
@@ -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
 
@@ -585,10 +586,10 @@ Performing Date Formatting and Currency Formatting
 :app:`Pyramid` does not itself perform date and currency formatting for
 different locales.  However, :term:`Babel` can help you do this via the
 :class:`babel.core.Locale` class.  The `Babel documentation for this class
-<http://babel.edgewall.org/wiki/ApiDocs/babel.core#babel.core:Locale>`_
-provides minimal information about how to perform date and currency related
-locale operations.  See :ref:`installing_babel` for information about how to
-install Babel.
+<http://babel.pocoo.org/en/latest/api/core.html#basic-interface>`_ provides
+minimal information about how to perform date and currency related locale
+operations. See :ref:`installing_babel` for information about how to install
+Babel.
 
 The :class:`babel.core.Locale` class requires a :term:`locale name` as an
 argument to its constructor. You can use :app:`Pyramid` APIs to obtain the
@@ -646,7 +647,7 @@ before being rendered:
 
 The features represented by attributes of the ``i18n`` namespace of Chameleon
 will also consult the :app:`Pyramid` translations. See
-http://chameleon.readthedocs.org/en/latest/reference.html#id50.
+http://chameleon.readthedocs.org/en/latest/reference.html#translation-i18n.
 
 .. note::
 
@@ -666,9 +667,24 @@ can always use the more manual translation facility described in
 Mako Pyramid i18n Support
 -------------------------
 
-There exists a recipe within the :term:`Pyramid Cookbook` named ":ref:`Mako
-Internationalization <cookbook:mako_i18n>`" which explains how to add idiomatic
-i18n support to :term:`Mako` templates.
+There exists a recipe within the :term:`Pyramid Community Cookbook` named
+:ref:`Mako Internationalization <cookbook:mako_i18n>` which explains how to add
+idiomatic i18n support to :term:`Mako` templates.
+
+
+.. index::
+   single: Jinja2 i18n
+
+Jinja2 Pyramid i18n Support
+---------------------------
+
+The add-on `pyramid_jinja2 <https://github.com/Pylons/pyramid_jinja2>`_
+provides a scaffold with an example of how to use internationalization with
+Jinja2 in Pyramid. See the documentation sections `Internalization (i18n)
+<http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/#internalization-i18n>`_
+and `Paster Template I18N
+<http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/#paster-template-i18n>`_.
+
 
 .. index::
    single: localization deployment settings
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 26d458727..c59ced2a5 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.2, Python 3.3, Python 3.4, 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.4
+   # 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,122 @@ 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
-`python.org's download section <http://python.org/download/>`_ (the files
+install it by downloading a Python 3.x-series interpreter executable from
+`python.org's download section <https://www.python.org/downloads/>`_ (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.
+executable, and select appropriate options during the installation process. To
+standardize this documentation, we used the GUI installer and selected the
+following options:
+
+- Screen 1: Install Python 3.x.x (32- or 64-bit)
+    - Check "Install launcher for all users (recommended)"
+    - Check "Add Python 3.x to PATH"
+    - Click "Customize installation"
+- Screen 2: Optional Features
+    - Check all options
+    - Click "Next"
+- Screen 3: Advanced Options
+    - Check all options
+    - Customize install location: "C:\\Python3x", where "x" is the minor
+      version of Python
+    - Click "Next"
+
+You might also need to download and install the Python for Windows extensions.
+
+.. seealso:: See the official Python documentation :ref:`Using Python on
+   Windows <python:using-on-windows>` for full details.
+
+.. seealso:: Download and install the `Python for Windows extensions
+   <https://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.
+
+.. seealso:: `Python launcher for Windows
+   <https://docs.python.org/3/using/windows.html#launcher>`_ provides a command
+   ``py`` that allows users to run any installed version of Python.
 
 .. 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``
+   After you install Python on Windows, you might 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.
 
-.. 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
+   .. seealso:: See `Configuring Python (on Windows)
+      <https://docs.python.org/3/using/windows.html#configuring-python>`_ for
+      full details.
 
-   $ python2.7 -c 'import setuptools'
-
-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
-
-   $ python ez_setup.py
-
-Once this command is invoked, setuptools should be installed on your system.
-If the command fails due to permission errors, you may need to be the
-administrative user on your system to successfully invoke the script.  To
-remediate this, you may need to do:
-
-.. code-block:: text
-
-   $ sudo python ez_setup.py
 
 .. index::
-   pair: install; virtualenv
-
-Installing the ``virtualenv`` Package
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once you've got setuptools installed, you should install the :term:`virtualenv`
-package.  To install the :term:`virtualenv` package into your
-setuptools-enabled Python interpreter, use the ``easy_install`` command.
-
-.. warning::
+   single: 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.
+.. _requirements-for-installing-packages:
 
-   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.
+Requirements for Installing Packages
+------------------------------------
 
-.. 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:
+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.
 
-.. code-block:: text
+.. 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.
 
-   $ 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.
+   single: installing on UNIX
+   single: installing on Mac OS X
 
-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.
+.. _installing_unix:
 
-.. warning::
+Installing :app:`Pyramid` on a UNIX System
+------------------------------------------
 
-   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.
+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.
 
-.. warning::
+#. Make a :term:`virtual environment` workspace:
 
-    *do not* use ``sudo`` to run the ``virtualenv`` script.  It's perfectly
-    acceptable (and desirable) to create a virtualenv as a normal user.
+   .. code-block:: bash
 
+      $ export VENV=~/env
+      $ python3 -m venv $VENV
 
-Installing :app:`Pyramid` into the Virtual Python Environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   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.
 
-After you've got your virtualenv installed, you may install :app:`Pyramid`
-itself using the following commands:
+#. (Optional) Consider using ``$VENV/bin/activate`` to make your shell
+   environment wired to use the virtual environment.
 
-.. parsed-literal::
-      
-   $ $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 +201,39 @@ 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:: doscon
 
       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\python -m venv %VENV%
+      c:\> cd %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:\\> %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 7906dd85d..de6ac408b 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -221,7 +221,7 @@ send email, let you use the Jinja2 templating system, let you use XML-RPC or
 JSON-RPC, let you integrate with jQuery Mobile, etc.
 
 Examples:
-http://docs.pylonsproject.org/en/latest/docs/pyramid.html#pyramid-add-on-documentation
+https://trypyramid.com/resources-extending-pyramid.html
 
 Class-based and function-based views
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -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.2, Python 3.3, Python 3.4,
-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.
+``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.
 
-Example: http://jenkins.pylonsproject.org/
+Travis: https://travis-ci.org/Pylons/pyramid
+Jenkins: http://jenkins.pylonsproject.org/job/pyramid/
 
 Support
 ~~~~~~~
@@ -880,7 +881,7 @@ new-user-friendly.
 
 Example: Visit irc\://freenode.net#pyramid (the ``#pyramid`` channel on
 irc.freenode.net in an IRC client) or the pylons-discuss maillist at
-http://groups.google.com/group/pylons-discuss/.
+https://groups.google.com/forum/#!forum/pylons-discuss.
 
 Documentation
 ~~~~~~~~~~~~~
@@ -892,8 +893,7 @@ also maintain a "cookbook" of recipes, which are usually demonstrations of
 common integration scenarios too specific to add to the official narrative
 docs.  In any case, the Pyramid documentation is comprehensive.
 
-Example: The Pyramid Cookbook at
-http://docs.pylonsproject.org/projects/pyramid-cookbook/en/latest/.
+Example: The :ref:`Pyramid Community Cookbook <cookbook:pyramid-cookbook>`.
 
 .. index::
    single: Pylons Project
@@ -903,7 +903,7 @@ What Is The Pylons Project?
 
 :app:`Pyramid` is a member of the collection of software published under the
 Pylons Project.  Pylons software is written by a loose-knit community of
-contributors.  The `Pylons Project website <http://pylonsproject.org>`_
+contributors.  The `Pylons Project website <http://www.pylonsproject.org>`_
 includes details about how :app:`Pyramid` relates to the Pylons Project.
 
 .. index::
@@ -967,9 +967,9 @@ nor discouraging the decision.
 
 Other Python web frameworks advertise themselves as members of a class of web
 frameworks named `model-view-controller
-<http://en.wikipedia.org/wiki/Model–view–controller>`_ frameworks. Insofar as
-this term has been claimed to represent a class of web frameworks,
-:app:`Pyramid` also generally fits into this class.
+<https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller>`_
+frameworks. Insofar as this term has been claimed to represent a class of web
+frameworks, :app:`Pyramid` also generally fits into this class.
 
 .. sidebar:: You Say :app:`Pyramid` is MVC, but Where's the Controller?
 
diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index 98315ac9f..c9fecd4f4 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -337,6 +337,31 @@ introspectables in categories not described here.
 
     The permission name passed to ``set_default_permission``.
 
+``default csrf options``
+
+  There will be one and only one introspectable in the ``default csrf options``
+  category. It represents a call to the
+  :meth:`pyramid.config.Configurator.set_default_csrf_options` method. It
+  will have the following data.
+
+  ``require_csrf``
+
+    The default value for ``require_csrf`` if left unspecified on calls to
+    :meth:`pyramid.config.Configurator.add_view`.
+
+  ``token``
+
+    The name of the token searched in ``request.POST`` to find a valid CSRF
+    token.
+
+  ``header``
+
+    The name of the request header searched to find a valid CSRF token.
+
+  ``safe_methods``
+
+    The list of HTTP methods considered safe and exempt from CSRF checks.
+
 ``views``
 
   Each introspectable in the ``views`` category represents a call to
diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index 9c6e8a319..c7b4b9d6f 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -292,7 +292,8 @@ Logging Exceptions
 
 To log or email exceptions generated by your :app:`Pyramid` application, use
 the :term:`pyramid_exclog` package.  Details about its configuration are in its
-`documentation <http://docs.pylonsproject.org/projects/pyramid_exclog/dev/>`_.
+`documentation
+<http://docs.pylonsproject.org/projects/pyramid_exclog/en/latest/>`_.
 
 .. index::
    single: TransLogger
diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst
index 3e00a295a..02cd8ee3a 100644
--- a/docs/narr/muchadoabouttraversal.rst
+++ b/docs/narr/muchadoabouttraversal.rst
@@ -8,9 +8,7 @@ Much Ado About Traversal
 
 .. note::
 
-   This chapter was adapted, with permission, from a blog post by `Rob Miller
-   <http://blog.nonsequitarian.org/>`_, originally published at
-   http://blog.nonsequitarian.org/2010/much-ado-about-traversal/.
+   This chapter was adapted, with permission, from a blog post by Rob Miller.
 
 Traversal is an alternative to :term:`URL dispatch` which allows :app:`Pyramid`
 applications to map URLs to code.
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 25f3931e9..71bd176f6 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -53,57 +53,50 @@ The included scaffolds are these:
 ``alchemy``
   URL mapping via :term:`URL dispatch` and persistence via :term:`SQLAlchemy`
 
+
 .. index::
    single: creating a project
    single: project
+   single: pcreate
 
 .. _creating_a_project:
 
 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.
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/pcreate -s starter MyProject
 
 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:: doscon
 
-.. code-block:: text
-
-   $ $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
+   c:\> %VENV%\Scripts\pcreate -s starter MyProject
 
 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.
@@ -119,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::
 
@@ -147,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
@@ -158,26 +152,27 @@ created project directory.
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ cd MyProject
-   $ $VENV/bin/python setup.py develop
+   $ $VENV/bin/pip install -e .
 
 Or on Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   > cd MyProject
-   > %VENV%\Scripts\python.exe setup.py develop
+   c:\> cd MyProject
+   c:\> %VENV%\Scripts\pip install -e .
 
 Elided output from a run of this command on UNIX is shown below:
 
-.. code-block:: text
+.. 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``
@@ -191,53 +186,74 @@ 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:: text
+.. 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:: doscon
+
+   c:\> %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 -q
 
-   > %VENV%\Scripts\python.exe setup.py test -q
+On Windows:
+
+.. code-block:: doscon
+
+   c:\> %VENV%\Scripts\py.test -q
 
 Here's sample output from a test run on UNIX:
 
-.. code-block:: text
+.. 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'
-   writing manifest file 'MyProject.egg-info/SOURCES.txt'
-   running build_ext
+   $ $VENV/bin/py.test -q
    ..
-   ----------------------------------------------------------------------
-   Ran 1 test in 0.108s
-
-   OK
+   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).
+
+Alternatively, if you'd like to see test coverage, pass the ``--cov`` option
+to ``py.test``:
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test --cov -q
+
+Scaffolds include configuration defaults for ``py.test`` and test coverage.
+These configuration files are ``pytest.ini`` and ``.coveragerc``, located at
+the root of your package. Without these defaults, we would need to specify the
+path to the module on which we want to run tests and coverage.
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test --cov=myproject myproject/tests.py -q
+
+.. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke
+   ``py.test -h`` to see its full set of options.
+
 
 .. index::
    single: running an application
@@ -250,13 +266,15 @@ single sample test exists.
 Running the Project Application
 -------------------------------
 
+.. seealso:: See also the output of :ref:`pserve --help <pserve_script>`.
+
 Once a project is installed for development, you can run the application it
 represents using the ``pserve`` command against the generated configuration
 file.  In our case, this file is named ``development.ini``.
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/pserve development.ini
 
@@ -264,42 +282,42 @@ On Windows:
 
 .. code-block:: text
 
-   > %VENV%\Scripts\pserve development.ini
+   c:\> %VENV%\Scripts\pserve development.ini
 
 Here's sample output from a run of ``pserve`` on UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/pserve development.ini
-   Starting server in PID 16601.
-   serving on http://0.0.0.0:6543
-
-When you use ``pserve`` to start the application implied by the default
-rendering of a scaffold, it will respond to requests on *all* IP addresses
-possessed by your system, not just requests to ``localhost``.  This is what the
-``0.0.0.0`` in ``serving on http://0.0.0.0:6543`` means.  The server will
-respond to requests made to ``127.0.0.1`` and on any external IP address. For
-example, your system might be configured to have an external IP address
-``192.168.1.50``.  If that's the case, if you use a browser running on the same
-system as Pyramid, it will be able to access the application via
-``http://127.0.0.1:6543/`` as well as via ``http://192.168.1.50:6543/``.
-However, *other people* on other computers on the same network will also be
-able to visit your Pyramid application in their browser by visiting
-``http://192.168.1.50:6543/``.
-
-If you want to restrict access such that only a browser running on the same
-machine as Pyramid will be able to access your Pyramid application, edit the
+   Starting server in PID 16208.
+   serving on http://127.0.0.1:6543
+
+Access is restricted such that only a browser running on the same machine as
+Pyramid will be able to access your Pyramid application.  However, if you want
+to open access to other machines on the same network, then edit the
 ``development.ini`` file, and replace the ``host`` value in the
-``[server:main]`` section.  Change it from ``0.0.0.0`` to ``127.0.0.1``.  For
+``[server:main]`` section, changing it from ``127.0.0.1`` to ``0.0.0.0``.  For
 example:
 
 .. code-block:: ini
 
    [server:main]
    use = egg:waitress#main
-   host = 127.0.0.1
+   host = 0.0.0.0
    port = 6543
 
+Now when you use ``pserve`` to start the application, it will respond to
+requests on *all* IP addresses possessed by your system, not just requests to
+``localhost``.  This is what the ``0.0.0.0`` in
+``serving on http://0.0.0.0:6543`` means.  The server will respond to requests
+made to ``127.0.0.1`` and on any external IP address. For example, your system
+might be configured to have an external IP address ``192.168.1.50``.  If that's
+the case, if you use a browser running on the same system as Pyramid, it will
+be able to access the application via ``http://127.0.0.1:6543/`` as well as via
+``http://192.168.1.50:6543/``. However, *other people* on other computers on
+the same network will also be able to visit your Pyramid application in their
+browser by visiting ``http://192.168.1.50:6543/``.
+
 You can change the port on which the server runs on by changing the same
 portion of the ``development.ini`` file.  For example, you can change the
 ``port = 6543`` line in the ``development.ini`` file's ``[server:main]``
@@ -347,7 +365,7 @@ For example, on UNIX:
    $ $VENV/bin/pserve development.ini --reload
    Starting subprocess with file monitor
    Starting server in PID 16601.
-   serving on http://0.0.0.0:6543
+   serving on http://127.0.0.1:6543
 
 Now if you make a change to any of your project's ``.py`` files or ``.ini``
 files, you'll see the server restart automatically:
@@ -357,7 +375,7 @@ files, you'll see the server restart automatically:
    development.ini changed; reloading...
    -------------------- Restarting --------------------
    Starting server in PID 16602.
-   serving on http://0.0.0.0:6543
+   serving on http://127.0.0.1:6543
 
 Changes to template files (such as ``.pt`` or ``.mak`` files) won't cause the
 server to restart.  Changes to template files don't require a server restart as
@@ -414,9 +432,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
@@ -429,7 +446,7 @@ commenting out a line.  For example, instead of:
    :linenos:
 
    [app:main]
-   ...
+   # ... elided configuration
    pyramid.includes =
        pyramid_debugtoolbar
 
@@ -439,7 +456,7 @@ Put a hash mark at the beginning of the ``pyramid_debugtoolbar`` line:
    :linenos:
 
    [app:main]
-   ...
+   # ... elided configuration
    pyramid.includes =
    #    pyramid_debugtoolbar
 
@@ -579,18 +596,16 @@ file.  The name ``main`` is a convention used by PasteDeploy signifying that it
 is the default application.
 
 The ``[server:main]`` section of the configuration file configures a WSGI
-server which listens on TCP port 6543.  It is configured to listen on all
-interfaces (``0.0.0.0``).  This means that any remote system which has TCP
-access to your system can see your Pyramid application.
+server which listens on TCP port 6543.  It is configured to listen on localhost
+only (``127.0.0.1``).
 
 .. _MyProject_ini_logging:
 
-The sections that live between the markers ``# Begin logging configuration``
-and ``# End logging configuration`` represent Python's standard library
-:mod:`logging` module configuration for your application.  The sections between
-these two markers are passed to the `logging module's config file configuration
-engine <http://docs.python.org/howto/logging.html#configuring-logging>`_ when
-the ``pserve`` or ``pshell`` commands are executed.  The default configuration
+The sections after ``# logging configuration`` represent Python's standard
+library :mod:`logging` module configuration for your application.  These
+sections are passed to the `logging module's config file configuration engine
+<https://docs.python.org/2/howto/logging.html#configuring-logging>`_ when the
+``pserve`` or ``pshell`` commands are executed.  The default configuration
 sends application logging output to the standard error output of your terminal.
 For more information about logging configuration, see :ref:`logging_chapter`.
 
@@ -633,8 +648,8 @@ setup.py sdist``.  Due to the information contained in the default
 ``MANIFEST.in``, an sdist of your Pyramid project will include ``.txt`` files,
 ``.ini`` files, ``.rst`` files, graphics files, and template files, as well as
 ``.py`` files.  See
-http://docs.python.org/distutils/sourcedist.html#the-manifest-in-template for
-more information about the syntax and usage of ``MANIFEST.in``.
+https://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template
+for more information about the syntax and usage of ``MANIFEST.in``.
 
 Without the presence of a ``MANIFEST.in`` file or without checking your source
 code into a version control repository, ``setup.py sdist`` places only *Python
@@ -652,8 +667,8 @@ files with extensions other than the files named in the project's
 ``MANIFEST.in`` and you don't make use of a setuptools-compatible version
 control system, you'll need to edit the ``MANIFEST.in`` file and include the
 statements necessary to include your new files.  See
-http://docs.python.org/distutils/sourcedist.html#principle for more information
-about how to do this.
+https://docs.python.org/2/distutils/sourcedist.html#principle for more
+information about how to do this.
 
 You can also delete ``MANIFEST.in`` from your project and rely on a setuptools
 feature which simply causes all files checked into a version control system to
@@ -672,16 +687,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 `The Hitchhiker's
-   Guide to Packaging <http://guide.python-distribute.org/>`_.
+   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:
 
@@ -690,7 +705,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
@@ -701,23 +716,22 @@ 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
-<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
-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.
+is conventionally the content of the ``README`` and ``CHANGES`` files appended
+together. The ``classifiers`` field is a list of `Trove classifiers
+<https://pypi.python.org/pypi?%3Aaction=list_classifiers>`_ describing your
+application.  ``author`` and ``author_email`` are text fields which probably
+don't need any description. ``url`` is a field that should 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=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``
+indicates 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
@@ -729,7 +743,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::
@@ -912,13 +926,13 @@ The ``tests.py`` module includes unit tests for your application.
 
 .. literalinclude:: MyProject/myproject/tests.py
    :language: python
-   :lines: 1-18
    :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 -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/renderers.rst b/docs/narr/renderers.rst
index 50e85813a..e06c78028 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -317,7 +317,7 @@ JSONP Renderer
 .. versionadded:: 1.1
 
 :class:`pyramid.renderers.JSONP` is a `JSONP
-<http://en.wikipedia.org/wiki/JSONP>`_ renderer factory helper which implements
+<https://en.wikipedia.org/wiki/JSONP>`_ renderer factory helper which implements
 a hybrid JSON/JSONP renderer.  JSONP is useful for making cross-domain AJAX
 requests.
 
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/scaffolding.rst b/docs/narr/scaffolding.rst
index 8677359de..164ceb3bf 100644
--- a/docs/narr/scaffolding.rst
+++ b/docs/narr/scaffolding.rst
@@ -22,10 +22,10 @@ found by the ``pcreate`` command.
 
 To create a scaffold template, create a Python :term:`distribution` to house
 the scaffold which includes a ``setup.py`` that relies on the ``setuptools``
-package.  See `Creating a Package
-<http://guide.python-distribute.org/creation.html>`_ for more information about
-how to do this.  For example, we'll pretend the distribution you create is
-named ``CoolExtension``, and it has a package directory within it named
+package.  See `Packaging and Distributing Projects
+<https://packaging.python.org/en/latest/distributing/>`_ for more information
+about how to do this.  For example, we'll pretend the distribution you create
+is named ``CoolExtension``, and it has a package directory within it named
 ``coolextension``.
 
 Once you've created the distribution, put a "scaffolds" directory within your
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 7cbea113c..77e7fd707 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -290,6 +290,14 @@ properties of the instance.
        def __init__(self, owner):
            self.owner = owner
 
+.. warning::
+
+   Writing ``__acl__`` as properties is discouraged because an
+   ``AttributeError`` occurring in ``fget`` or ``fset`` will be silently
+   dismissed (this is consistent with Python ``getattr`` and ``hasattr``
+   behaviors). For dynamic ACLs, simply use callables, as documented above.
+
+
 .. index::
    single: ACE
    single: access control entry
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index db554a93b..a1319e45f 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -260,19 +260,28 @@ added to the flash queue, and empties the queue.
 
 .. method:: pop_flash(queue='')
 
->>> request.session.flash('info message')
->>> request.session.pop_flash()
-['info message']
+.. testsetup::
+
+   from pyramid import testing
+   request = testing.DummyRequest()
+
+.. doctest::
+
+   >>> request.session.flash('info message')
+   >>> request.session.pop_flash()
+   ['info message']
 
 Calling ``session.pop_flash()`` again like above without a corresponding call
 to ``session.flash()`` will return an empty list, because the queue has already
 been popped.
 
->>> request.session.flash('info message')
->>> request.session.pop_flash()
-['info message']
->>> request.session.pop_flash()
-[]
+.. doctest::
+
+   >>> request.session.flash('info message')
+   >>> request.session.pop_flash()
+   ['info message']
+   >>> request.session.pop_flash()
+   []
 
 .. index::
    single: session.peek_flash
@@ -287,15 +296,17 @@ flash storage.
 
 .. method:: peek_flash(queue='')
 
->>> request.session.flash('info message')
->>> request.session.peek_flash()
-['info message']
->>> request.session.peek_flash()
-['info message']
->>> request.session.pop_flash()
-['info message']
->>> request.session.peek_flash()
-[]
+.. doctest::
+
+   >>> request.session.flash('info message')
+   >>> request.session.peek_flash()
+   ['info message']
+   >>> request.session.peek_flash()
+   ['info message']
+   >>> request.session.pop_flash()
+   ['info message']
+   >>> request.session.peek_flash()
+   []
 
 .. index::
    single: preventing cross-site request forgery attacks
@@ -305,7 +316,7 @@ Preventing Cross-Site Request Forgery Attacks
 ---------------------------------------------
 
 `Cross-site request forgery
-<http://en.wikipedia.org/wiki/Cross-site_request_forgery>`_ attacks are a
+<https://en.wikipedia.org/wiki/Cross-site_request_forgery>`_ attacks are a
 phenomenon whereby a user who is logged in to your website might inadvertantly
 load a URL because it is linked from, or embedded in, an attacker's website.
 If the URL is one that may modify or delete data, the consequences can be dire.
@@ -367,6 +378,21 @@ Or include it as a header in a jQuery AJAX request:
 The handler for the URL that receives the request should then require that the
 correct CSRF token is supplied.
 
+.. index::
+   single: session.new_csrf_token
+
+Using the ``session.new_csrf_token`` Method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To explicitly create a new CSRF token, use the ``session.new_csrf_token()``
+method.  This differs only from ``session.get_csrf_token()`` inasmuch as it
+clears any existing CSRF token, creates a new CSRF token, sets the token into
+the session, and returns the token.
+
+.. code-block:: python
+
+   token = request.session.new_csrf_token()
+
 Checking CSRF Tokens Manually
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -376,25 +402,76 @@ will return ``True``, otherwise it will raise ``HTTPBadRequest``. Optionally,
 you can specify ``raises=False`` to have the check return ``False`` instead of
 raising an exception.
 
-By default, it checks for a GET or POST parameter named ``csrf_token`` or a
-header named ``X-CSRF-Token``.
+By default, it checks for a POST parameter named ``csrf_token`` or a header
+named ``X-CSRF-Token``.
 
 .. code-block:: python
 
-    from pyramid.session import check_csrf_token
+   from pyramid.session import check_csrf_token
 
-    def myview(request):
-        # Require CSRF Token
-        check_csrf_token(request)
+   def myview(request):
+       # Require CSRF Token
+       check_csrf_token(request)
 
-        # ...
+       # ...
 
-.. index::
-   single: session.new_csrf_token
+.. _auto_csrf_checking:
+
+Checking CSRF Tokens Automatically
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.7
+
+:app:`Pyramid` supports automatically checking CSRF tokens on requests with an
+unsafe method as defined by RFC2616. Any other request may be checked manually.
+This feature can be turned on globally for an application using the
+:meth:`pyramid.config.Configurator.set_default_csrf_options` directive.
+For example:
+
+.. code-block:: python
+
+   from pyramid.config import Configurator
+
+   config = Configurator()
+   config.set_default_csrf_options(require_csrf=True)
+
+CSRF checking may be explicitly enabled or disabled on a per-view basis using
+the ``require_csrf`` view option. A value of ``True`` or ``False`` will
+override the default set by ``set_default_csrf_options``. For example:
+
+.. code-block:: python
+
+   @view_config(route_name='hello', require_csrf=False)
+   def myview(request):
+       # ...
+
+When CSRF checking is active, the token and header used to find the
+supplied CSRF token will be ``csrf_token`` and ``X-CSRF-Token``, respectively,
+unless otherwise overridden by ``set_default_csrf_options``. The token is
+checked against the value in ``request.POST`` which is the submitted form body.
+If this value is not present, then the header will be checked.
+
+In addition to token based CSRF checks, if the request is using HTTPS then the
+automatic CSRF checking will also check the referrer of the request to ensure
+that it matches one of the trusted origins. By default the only trusted origin
+is the current host, however additional origins may be configured by setting
+``pyramid.csrf_trusted_origins`` to a list of domain names (and ports if they
+are non standard). If a host in the list of domains starts with a ``.`` then
+that will allow all subdomains as well as the domain without the ``.``.
+
+If CSRF checks fail then a :class:`pyramid.exceptions.BadCSRFToken` or
+:class:`pyramid.exceptions.BadCSRFOrigin` exception will be raised. This
+exception may be caught and handled by an :term:`exception view` but, by
+default, will result in a ``400 Bad Request`` response being sent to the
+client.
 
 Checking CSRF Tokens with a View Predicate
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. deprecated:: 1.7
+   Use the ``require_csrf`` option or read :ref:`auto_csrf_checking` instead
+   to have :class:`pyramid.exceptions.BadCSRFToken` exceptions raised.
+
 A convenient way to require a valid CSRF token for a particular view is to
 include ``check_csrf=True`` as a view predicate. See
 :meth:`pyramid.config.Configurator.add_view`.
@@ -410,15 +487,3 @@ include ``check_csrf=True`` as a view predicate. See
    predicate system, when it doesn't find a view, raises ``HTTPNotFound``
    instead of ``HTTPBadRequest``, so ``check_csrf=True`` behavior is different
    from calling :func:`pyramid.session.check_csrf_token`.
-
-Using the ``session.new_csrf_token`` Method
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To explicitly create a new CSRF token, use the ``session.new_csrf_token()``
-method.  This differs only from ``session.get_csrf_token()`` inasmuch as it
-clears any existing CSRF token, creates a new CSRF token, sets the token into
-the session, and returns the token.
-
-.. code-block:: python
-
-   token = request.session.new_csrf_token()
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 485f6b181..3e168eaea 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -6,15 +6,15 @@ Startup
 When you cause a :app:`Pyramid` application to start up in a console window,
 you'll see something much like this show up on the console:
 
-.. code-block:: text
+.. code-block:: bash
 
-  $ pserve development.ini
-  Starting server in PID 16601.
-  serving on 0.0.0.0:6543 view at http://127.0.0.1:6543
+    $ $VENV/bin/pserve development.ini
+    Starting server in PID 16305.
+    serving on http://127.0.0.1:6543
 
 This chapter explains what happens between the time you press the "Return" key
 on your keyboard after typing ``pserve development.ini`` and the time the line
-``serving on 0.0.0.0:6543 ...`` is output to your console.
+``serving on http://127.0.0.1:6543`` is output to your console.
 
 .. index::
    single: startup process
@@ -92,11 +92,11 @@ Here's a high-level time-ordered overview of what happens when you press
    In this case, the ``myproject.__init__:main`` function referred to by the
    entry point URI ``egg:MyProject`` (see :ref:`MyProject_ini` for more
    information about entry point URIs, and how they relate to callables) will
-   receive the key/value pairs ``{'pyramid.reload_templates':'true',
-   'pyramid.debug_authorization':'false', 'pyramid.debug_notfound':'false',
-   'pyramid.debug_routematch':'false', 'pyramid.debug_templates':'true',
-   'pyramid.default_locale_name':'en'}``.  See :ref:`environment_chapter` for
-   the meanings of these keys.
+   receive the key/value pairs ``{pyramid.reload_templates = true,
+   pyramid.debug_authorization = false, pyramid.debug_notfound = false,
+   pyramid.debug_routematch = false, pyramid.default_locale_name = en, and
+   pyramid.includes = pyramid_debugtoolbar}``.  See :ref:`environment_chapter`
+   for the meanings of these keys.
 
 #. The ``main`` function first constructs a
    :class:`~pyramid.config.Configurator` instance, passing the ``settings``
@@ -131,10 +131,9 @@ Here's a high-level time-ordered overview of what happens when you press
 #. ``pserve`` starts the WSGI *server* defined within the ``[server:main]``
    section.  In our case, this is the Waitress server (``use =
    egg:waitress#main``), and it will listen on all interfaces (``host =
-   0.0.0.0``), on port number 6543 (``port = 6543``).  The server code itself
-   is what prints ``serving on 0.0.0.0:6543 view at http://127.0.0.1:6543``.
-   The server serves the application, and the application is running, waiting
-   to receive requests.
+   127.0.0.1``), on port number 6543 (``port = 6543``). The server code itself
+   is what prints ``serving on http://127.0.0.1:6543``. The server serves the
+   application, and the application is running, waiting to receive requests.
 
 .. seealso::
    Logging configuration is described in the :ref:`logging_chapter` chapter.
diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst
index 02ae14aa5..7c847de50 100644
--- a/docs/narr/subrequest.rst
+++ b/docs/narr/subrequest.rst
@@ -17,7 +17,7 @@ application.
 Here's an example application which uses a subrequest:
 
 .. code-block:: python
-  :linenos:
+   :linenos:
 
    from wsgiref.simple_server import make_server
    from pyramid.config import Configurator
@@ -61,8 +61,8 @@ adapter when found and invoked via
 object:
 
 .. code-block:: python
-  :linenos:
-  :emphasize-lines: 11
+   :linenos:
+   :emphasize-lines: 11
 
    from wsgiref.simple_server import make_server
    from pyramid.config import Configurator
@@ -106,8 +106,8 @@ exception, the exception will be raised to the caller of
 :term:`exception view` configured:
 
 .. code-block:: python
-  :linenos:
-  :emphasize-lines: 11-16
+   :linenos:
+   :emphasize-lines: 11-16
 
    from wsgiref.simple_server import make_server
    from pyramid.config import Configurator
@@ -175,8 +175,8 @@ We can cause the subrequest to be run through the tween stack by passing
 :meth:`~pyramid.request.Request.invoke_subrequest`, like this:
 
 .. code-block:: python
-  :linenos:
-  :emphasize-lines: 7
+   :linenos:
+   :emphasize-lines: 7
 
    from wsgiref.simple_server import make_server
    from pyramid.config import Configurator
@@ -279,3 +279,53 @@ within a tween, because tweens already, by definition, have access to a
 function that will cause a subrequest (they are passed a ``handle`` function).
 It's fine to invoke :meth:`~pyramid.request.Request.invoke_subrequest` from
 within an event handler, however.
+
+
+.. index::
+   pair: subrequest; exception view
+
+Invoking an Exception View
+--------------------------
+
+.. versionadded:: 1.7
+
+:app:`Pyramid` apps may define :term:`exception views <exception view>` which
+can handle any raised exceptions that escape from your code while processing
+a request. By default an unhandled exception will be caught by the ``EXCVIEW``
+:term:`tween`, which will then lookup an exception view that can handle the
+exception type, generating an appropriate error response.
+
+In :app:`Pyramid` 1.7 the :meth:`pyramid.request.Request.invoke_exception_view`
+was introduced, allowing a user to invoke an exception view while manually
+handling an exception. This can be useful in a few different circumstances:
+
+- Manually handling an exception losing the current call stack or flow.
+
+- Handling exceptions outside of the context of the ``EXCVIEW`` tween. The
+  tween only covers certain parts of the request processing pipeline (See
+  :ref:`router_chapter`). There are also some corner cases where an exception
+  can be raised that will still bubble up to middleware, and possibly to the
+  web server in which case a generic ``500 Internal Server Error`` will be
+  returned to the client.
+
+Below is an example usage of
+:meth:`pyramid.request.Request.invoke_exception_view`:
+
+.. code-block:: python
+   :linenos:
+
+   def foo(request):
+       try:
+           some_func_that_errors()
+           return response
+       except Exception:
+           response = request.invoke_exception_view()
+           if response is not None:
+               return response
+           else:
+               # there is no exception view for this exception, simply
+               # re-raise and let someone else handle it
+               raise
+
+Please note that in most cases you do not need to write code like this, and you
+may rely on the ``EXCVIEW`` tween to handle this for you.
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 9e3a31845..6b3b5fcce 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -448,7 +448,7 @@ templating languages including the following:
 .. _pyramid_chameleon:
    http://docs.pylonsproject.org/projects/pyramid-chameleon/en/latest/
 
-.. _Jinja2: http://jinja.pocoo.org/docs/
+.. _Jinja2: http://jinja.pocoo.org/docs/dev/
 .. _pyramid_jinja2:
    http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/
 
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index c05ee41ad..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
@@ -348,26 +348,6 @@ code's integration with the rest of :app:`Pyramid`.
 
    See also :ref:`including_configuration`
 
-Let's demonstrate this by showing an integration test for a view.
-
-Given the following view definition, which assumes that your application's
-:term:`package` name is ``myproject``, and within that :term:`package` there
-exists a module ``views``, which in turn contains a :term:`view` function named
-``my_view``:
-
-   .. literalinclude:: MyProject/myproject/views.py
-      :linenos:
-      :lines: 1-6
-      :language: python
-
-You'd then create a ``tests`` module within your ``myproject`` package,
-containing the following test code:
-
-   .. literalinclude:: MyProject/myproject/tests.py
-      :linenos:
-      :pyobject: ViewIntegrationTests
-      :language: python
-
 Writing unit tests that use the :class:`~pyramid.config.Configurator` API to
 set up the right "mock" registrations is often preferred to creating
 integration tests.  Unit tests will run faster (because they do less for each
@@ -385,25 +365,47 @@ 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:
+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``.
 
-   .. literalinclude:: MyProject/setup.py
-      :linenos:
-      :emphasize-lines: 26-28,48
-      :language: python
+.. literalinclude:: MyProject/setup.py
+    :language: python
+    :linenos:
+    :lines: 11-22
+    :lineno-start: 11
+    :emphasize-lines: 8-
+
+Remember to change the dependency.
+
+.. literalinclude:: MyProject/setup.py
+    :language: python
+    :linenos:
+    :lines: 40-44
+    :lineno-start: 40
+    :emphasize-lines: 2-4
+
+As always, whenever you change your dependencies, make sure to run the correct
+``pip install -e`` command.
+
+.. code-block:: bash
+
+    $VENV/bin/pip install -e ".[testing]"
 
-Let us assume your :term:`package` is named ``myproject`` which contains a
-``views`` module, which in turn contains a :term:`view` function ``my_view``
-that returns a HTML body when the root URL is invoked:
+In your ``MyPackage`` project, your :term:`package` is named ``myproject``
+which contains a ``views`` module, which in turn contains a :term:`view`
+function ``my_view`` that returns an HTML body when the root URL is invoked:
 
    .. literalinclude:: MyProject/myproject/views.py
       :linenos:
       :language: python
 
-Then the following example functional test demonstrates invoking the above
+The following example functional test demonstrates invoking the above
 :term:`view`:
 
    .. literalinclude:: MyProject/myproject/tests.py
@@ -414,9 +416,9 @@ Then the following example functional test demonstrates invoking the above
 When this test is run, each test method creates a "real" :term:`WSGI`
 application using the ``main`` function in your ``myproject.__init__`` module,
 using :term:`WebTest` to wrap that WSGI application.  It assigns the result to
-``self.testapp``.  In the test named ``test_root``. The ``TestApp``'s ``GET``
+``self.testapp``.  In the test named ``test_root``, the ``TestApp``'s ``GET``
 method is used to invoke the root URL.  Finally, an assertion is made that the
-returned HTML contains the text ``MyProject``.
+returned HTML contains the text ``Pyramid``.
 
 See the :term:`WebTest` documentation for further information about the methods
 available to a :class:`webtest.app.TestApp` instance.
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index db9b5e090..4e434c3c6 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -75,6 +75,27 @@ changes are noted in the :ref:`changelog`, so it's possible to know that you
 should change older spellings to newer ones to ensure that people reading your
 code can find the APIs you're using in the Pyramid docs.
 
+
+Python support policy
+~~~~~~~~~~~~~~~~~~~~~
+
+At the time of a Pyramid version release, each supports all versions of Python
+through the end of their lifespans. The end-of-life for a given version of
+Python is when security updates are no longer released.
+
+- `Python 3.2 Lifespan <https://www.python.org/dev/peps/pep-0392/#lifespan>`_
+  ends February 2016.
+- `Python 3.3 Lifespan <https://www.python.org/dev/peps/pep-0392/#lifespan>`_
+  ends September 2017.
+- `Python 3.4 Lifespan <https://www.python.org/dev/peps/pep-0429/>`_ TBD.
+- `Python 3.5 Lifespan <https://www.python.org/dev/peps/pep-0478/>`_ TBD.
+- `Python 3.6 Lifespan <https://www.python.org/dev/peps/pep-0494/#id4>`_
+  December 2021.
+
+To determine the Python support for a specific release of Pyramid, view its
+``tox.ini`` file at the root of the repository's version.
+
+
 Consulting the change history
 -----------------------------
 
@@ -106,10 +127,9 @@ 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.
+<https://docs.python.org/2/using/cmdline.html#cmdoption-W>`_ for more
+information.
 
 As your tests run, deprecation warnings will be printed to the console
 explaining the deprecation and providing instructions about how to prevent the
@@ -185,10 +205,10 @@ On UNIX, you can do that via:
 
 On Windows, you need to issue two commands:
 
-.. code-block:: bash
+.. code-block:: doscon
 
-   C:\> set PYTHONWARNINGS=default
-   C:\> Scripts/pserve.exe development.ini
+   c:\> set PYTHONWARNINGS=default
+   c:\> Scripts/pserve.exe development.ini
 
 At this point, it's ensured that deprecation warnings will be printed to the
 console whenever a codepath is hit that generates one.  You can then click
@@ -196,9 +216,10 @@ around in your application interactively to try to generate them, and remediate
 as explained in :ref:`testing_under_new_release`.
 
 See `the PYTHONWARNINGS environment variable documentation
-<http://docs.python.org/using/cmdline.html#envvar-PYTHONWARNINGS>`_ or `the
+<https://docs.python.org/2/using/cmdline.html#envvar-PYTHONWARNINGS>`_ or `the
 Python -W flag documentation
-<http://docs.python.org/using/cmdline.html#cmdoption-W>`_ for more information.
+<https://docs.python.org/2/using/cmdline.html#cmdoption-W>`_ for more
+information.
 
 Upgrading to the very latest Pyramid release
 --------------------------------------------
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index c13558008..7d37c04df 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -271,8 +271,9 @@ pattern like this:
 But this will either cause an error at startup time or it won't match properly.
 You'll want to use a Unicode value as the pattern instead rather than raw
 bytestring escapes.  You can use a high-order Unicode value as the pattern by
-using `Python source file encoding <http://www.python.org/dev/peps/pep-0263/>`_
-plus the "real" character in the Unicode pattern in the source, like so:
+using `Python source file encoding
+<https://www.python.org/dev/peps/pep-0263/>`_ plus the "real" character in the
+Unicode pattern in the source, like so:
 
 .. code-block:: text
 
@@ -556,7 +557,7 @@ Here is an example of a corresponding ``mypackage.views`` module:
 
    @view_config(route_name='idea')
    def idea_view(request):
-       return Response(request.matchdict['id'])
+       return Response(request.matchdict['idea'])
    
    @view_config(route_name='user')
    def user_view(request):
@@ -1194,7 +1195,7 @@ If a predicate is a class, just add ``__text__`` property in a standard manner.
        __text__ = 'my custom class predicate'
 
 If a predicate is a method, you'll need to assign it after method declaration
-(see `PEP 232 <http://www.python.org/dev/peps/pep-0232/>`_).
+(see `PEP 232 <https://www.python.org/dev/peps/pep-0232/>`_).
 
 .. code-block:: python
    :linenos:
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 0bd52b6e2..cd5b8feb0 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -192,6 +192,36 @@ Non-Predicate Arguments
   only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` with
   the first element of ``None``, i.e., ``(None, {'public':True})``.
 
+
+``require_csrf``
+
+  CSRF checks will affect any request method that is not defined as a "safe"
+  method by RFC2616. In pratice this means that GET, HEAD, OPTIONS, and TRACE
+  methods will pass untouched and all others methods will require CSRF. This
+  option is used in combination with the ``pyramid.require_default_csrf``
+  setting to control which request parameters are checked for CSRF tokens.
+
+  This feature requires a configured :term:`session factory`.
+
+  If this option is set to ``True`` then CSRF checks will be enabled for POST
+  requests to this view. The required token will be whatever was specified by
+  the ``pyramid.require_default_csrf`` setting, or will fallback to
+  ``csrf_token``.
+
+  If this option is set to a string then CSRF checks will be enabled and it
+  will be used as the required token regardless of the
+  ``pyramid.require_default_csrf`` setting.
+
+  If this option is set to ``False`` then CSRF checks will be disabled
+  regardless of the ``pyramid.require_default_csrf`` setting.
+
+  In addition, if this option is set to ``True`` or a string then CSRF origin
+  checking will be enabled.
+
+  See :ref:`auto_csrf_checking` for more information.
+
+  .. versionadded:: 1.7
+
 ``wrapper``
   The :term:`view name` of a different :term:`view configuration` which will
   receive the response body of this view as the ``request.wrapped_body``
@@ -433,7 +463,7 @@ configured view.
   check name.
 
   If CSRF checking is performed, the checked value will be the value of
-  ``request.params[check_name]``.  This value will be compared against the
+  ``request.POST[check_name]``.  This value will be compared against the
   value of ``request.session.get_csrf_token()``, and the check will pass if
   these two values are the same.  If the check passes, the associated view will
   be permitted to execute.  If the check fails, the associated view will not be
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index f18cf1dfb..ce1586834 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -27,8 +27,8 @@ functionality to the standard WebOb request, which is documented in the
 :ref:`request_module` API documentation.
 
 WebOb provides objects for HTTP requests and responses.  Specifically it does
-this by wrapping the `WSGI <http://wsgi.org>`_ request environment and response
-status, header list, and app_iter (body) values.
+this by wrapping the `WSGI <http://wsgi.readthedocs.org/en/latest/>`_ request
+environment and response status, header list, and app_iter (body) values.
 
 WebOb request and response objects provide many conveniences for parsing WSGI
 requests and forming WSGI responses.  WebOb is a nice way to represent "raw"
@@ -46,7 +46,7 @@ Request
 ~~~~~~~
 
 The request object is a wrapper around the `WSGI environ dictionary
-<http://www.python.org/dev/peps/pep-0333/#environ-variables>`_.  This
+<https://www.python.org/dev/peps/pep-0333/#environ-variables>`_.  This
 dictionary contains keys for each header, keys that describe the request
 (including the path and query string), a file-like object for the request body,
 and a variety of custom keys.  You can always access the environ with
@@ -269,7 +269,7 @@ to a :app:`Pyramid` application:
 When such a request reaches a view in your application, the
 ``request.json_body`` attribute will be available in the view callable body.
 
-.. code-block:: javascript
+.. code-block:: python
 
     @view_config(renderer='string')
     def aview(request):