Merge branch 'master' of github.com:Pylons/pyramid

28 files changed, 163 insertions, 169 deletions

diff --git a/docs/narr/MyProject/myproject/__init__.py b/docs/narr/MyProject/myproject/__init__.py
index 31b02cf02..6c512f52f 100644
--- a/docs/narr/MyProject/myproject/__init__.py
+++ b/docs/narr/MyProject/myproject/__init__.py
@@ -1,5 +1,6 @@
 from pyramid.config import Configurator
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
diff --git a/docs/narr/MyProject/myproject/tests.py b/docs/narr/MyProject/myproject/tests.py
index d8b764041..64dcab1d5 100644
--- a/docs/narr/MyProject/myproject/tests.py
+++ b/docs/narr/MyProject/myproject/tests.py
@@ -2,6 +2,7 @@ import unittest
 
 from pyramid import testing
 
+
 class ViewTests(unittest.TestCase):
     def setUp(self):
         self.config = testing.setUp()
diff --git a/docs/narr/MyProject/myproject/views.py b/docs/narr/MyProject/myproject/views.py
index f571a5976..c383c5716 100644
--- a/docs/narr/MyProject/myproject/views.py
+++ b/docs/narr/MyProject/myproject/views.py
@@ -1,5 +1,6 @@
 from pyramid.view import view_config
 
+
 @view_config(route_name='home', renderer='templates/mytemplate.pt')
 def my_view(request):
-    return {'project':'MyProject'}
+    return {'project': 'MyProject'}
diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py
index b119a954b..f24b6984e 100644
--- a/docs/narr/MyProject/setup.py
+++ b/docs/narr/MyProject/setup.py
@@ -15,10 +15,10 @@ requires = [
 setup(name='MyProject',
       version='0.0',
       description='MyProject',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -32,7 +32,7 @@ setup(name='MyProject',
       install_requires=requires,
       tests_require=requires,
       test_suite="myproject",
-      entry_points = """\
+      entry_points="""\
       [paste.app_factory]
       main = myproject:main
       """,
diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index ad22a82c9..ba43f3ea6 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -417,7 +417,7 @@ added in configuration execution order.
 More Information
 ----------------
 
-For more information, see the article entitled `"A Whirlwind Rour of Advanced
+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>`_
+<http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/configuration/whirlwind_tour.html>`_,
 in the Pyramid Cookbook.
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index e8e915297..7b620548d 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -252,7 +252,7 @@ static assets that live *outside* the :app:`Pyramid` application.  This will
 happen when the :meth:`~pyramid.config.Configurator.add_static_view` API
 associated with the path fed to :meth:`~pyramid.request.Request.static_url`
 is a *URL* instead of a view name.  For example, the ``name`` argument may be
-``http://example.com`` while the the ``path`` given may be
+``http://example.com`` while the ``path`` given may be
 ``mypackage:images``:
 
 .. code-block:: python
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 3bdf8c5cd..8e360216d 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -504,7 +504,8 @@ environment much like the environment produced when a particular
 using the :func:`pyramid.paster.bootstrap` command in the body of your
 script.
 
-.. note:: This feature is new as of :app:`Pyramid` 1.1.
+.. versionadded:: 1.1
+   This feature.
 
 In the simplest case, :func:`pyramid.paster.bootstrap` can be used with a
 single argument, which accepts the :term:`PasteDeploy` ``.ini`` file
@@ -758,7 +759,7 @@ we'll pretend you have a distribution with a package in it named
 
 This script uses the Python ``optparse`` module to allow us to make sense out
 of extra arguments passed to the script.  It uses the
-:func:`pyramid.paster.bootstrap` function to get information about the the
+:func:`pyramid.paster.bootstrap` function to get information about the
 application defined by a config file, and prints the deployment settings
 defined in that config file.
 
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index cd3dab099..6f82baf32 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -101,27 +101,25 @@ for decorations happens when the :meth:`pyramid.config.Configurator.scan`
 method is invoked: scanning implies searching for configuration declarations
 in a package and its subpackages.  For example:
 
-.. topic:: Starting A Scan
-
-   .. code-block:: python
-      :linenos:
-
-      from wsgiref.simple_server import make_server
-      from pyramid.config import Configurator
-      from pyramid.response import Response
-      from pyramid.view import view_config
-     
-      @view_config()
-      def hello(request):
-          return Response('Hello')
-
-      if __name__ == '__main__':
-          from pyramid.config import Configurator
-          config = Configurator()
-          config.scan()
-          app = config.make_wsgi_app()
-          server = make_server('0.0.0.0', 8080, app)
-          server.serve_forever()
+.. code-block:: python
+   :linenos:
+
+   from wsgiref.simple_server import make_server
+   from pyramid.config import Configurator
+   from pyramid.response import Response
+   from pyramid.view import view_config
+
+   @view_config()
+   def hello(request):
+       return Response('Hello')
+
+   if __name__ == '__main__':
+       from pyramid.config import Configurator
+       config = Configurator()
+       config.scan()
+       app = config.make_wsgi_app()
+       server = make_server('0.0.0.0', 8080, app)
+       server.serve_forever()
 
 The scanning machinery imports each module and subpackage in a package or
 module recursively, looking for special attributes attached to objects
@@ -144,7 +142,6 @@ In the example above, the scanner translates the arguments to
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    config.add_view(hello)
 
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 8206e0bcb..281bb6919 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -203,7 +203,7 @@ Using the setting is equivalent to using the
 |                                 |
 +---------------------------------+
 
-The value supplied as ``pyramid.includes`` should be a sequence.  The
+The value assigned to ``pyramid.includes`` should be a sequence.  The
 sequence can take several different forms.
 
 1) It can be a string.
@@ -323,7 +323,7 @@ the behest of an add-on author.
 |                                 |
 +---------------------------------+
 
-The value supplied as ``pyramid.tweens`` should be a sequence.  The
+The value assigned to ``pyramid.tweens`` should be a sequence.  The
 sequence can take several different forms.
 
 1) It can be a string.
@@ -504,12 +504,13 @@ default, this is ``false``.
 Mako Preprocessor
 ~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 1.1
+
 A callable (or a :term:`dotted Python name` which names a callable) which is
 called to preprocess the source before the template is called.  The callable
 will be passed the full template source before it is parsed. The return
 result of the callable will be used as the template source code.
 
-.. note:: This feature is new in Pyramid 1.1.
 
 +-----------------------------+
 | Config File Setting Name    |
diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst
index 5e7fe2753..f33326279 100644
--- a/docs/narr/extconfig.rst
+++ b/docs/narr/extconfig.rst
@@ -227,9 +227,7 @@ augment Pyramid's configuration introspection system.
 Adding Configuration Introspection
 ----------------------------------
 
-.. note::
-
-   The introspection subsystem is new in Pyramid 1.3.
+.. versionadded:: 1.3
 
 Pyramid provides a configuration introspection system that can be used by
 debugging tools to provide visibility into the configuration of a running
@@ -289,7 +287,7 @@ The ``title`` is a human-consumable string that can be used by introspection
 system frontends to show a friendly summary of this introspectable.
 
 The ``type_name`` is a value that can be used to subtype this introspectable
-within its category for for sorting and presentation purposes.  It can be any
+within its category for sorting and presentation purposes.  It can be any
 value.
 
 An introspectable is also dictionary-like.  It can contain any set of
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index c464203f0..dd9281c73 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -84,7 +84,7 @@ function in your application's ``__init__.py``.  For example, rather than:
        config.add_view('myapp.views.view1', name='view1')
        config.add_view('myapp.views.view2', name='view2')
 
-You should do move the calls to ``add_view`` outside of the (non-reusable)
+You should move the calls to ``add_view`` outside of the (non-reusable)
 ``if __name__ == '__main__'`` block, and into a reusable function:
 
 .. code-block:: python
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index ccaa6e9e2..d61d95685 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -40,7 +40,7 @@ On Windows:
 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 simply serve up the text "Hello world!".  If your application is
-running on your local system, using ``http://localhost:8080/hello/world``
+running on your local system, using `<http://localhost:8080/hello/world>`_
 in a browser will show this result.
 
 Each time you visit a URL served by the application in a browser, a logging
@@ -194,13 +194,13 @@ WSGI Application Creation
 After configuring views and ending configuration, the script creates a WSGI
 *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app`
 method.  A call to ``make_wsgi_app`` implies that all configuration is
-finished (meaning all method calls to the configurator which set up views,
-and various other configuration settings have been performed).  The
+finished (meaning all method calls to the configurator, which sets up views
+and various other configuration settings, have been performed).  The
 ``make_wsgi_app`` 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,
-however, you can learn more about it by visiting `wsgi.org
+but you can learn more about it by visiting `wsgi.org
 <http://wsgi.org>`_.
 
 The :app:`Pyramid` application object, in particular, is an instance of a
@@ -228,7 +228,7 @@ listens only on the ``127.0.0.1`` interface, which is problematic if you're
 running the server on a remote system and you wish to access it with a web
 browser from a local system.  We also specify a TCP port number to listen on,
 which is 8080, passing it as the second argument.  The final argument is the
-``app`` object (a :term:`router`), which is the the application we wish to
+``app`` object (a :term:`router`), which is the application we wish to
 serve.  Finally, we call the server's ``serve_forever`` method, which starts
 the main loop in which it will wait for requests from the outside world.
 
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index ea75e5fe4..fc5c0ff23 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -336,9 +336,9 @@ when adding renderer global values exists in :ref:`adding_renderer_globals`.
 Adding Renderer Globals (Deprecated)
 ------------------------------------
 
-.. warning:: this feature is deprecated as of Pyramid 1.1.  A non-deprecated
-   mechanism which allows event subscribers to add renderer global values
-   is documented in :ref:`beforerender_event`.
+.. deprecated:: 1.1
+   An alternative mechanism which allows event subscribers to add renderer
+   global values is documented in :ref:`beforerender_event`.
 
 Whenever :app:`Pyramid` handles a request to perform a rendering (after a
 view with a ``renderer=`` configuration attribute is invoked, or when any of
@@ -635,13 +635,13 @@ See :meth:`pyramid.config.add_resource_url_adapter` for more information.
 Changing How Pyramid Treats View Responses
 ------------------------------------------
 
+.. versionadded:: 1.1
+
 It is possible to control how Pyramid treats the result of calling a view
 callable on a per-type basis by using a hook involving
 :meth:`pyramid.config.Configurator.add_response_adapter` or the
 :class:`~pyramid.response.response_adapter` decorator.
 
-.. note:: This feature is new as of Pyramid 1.1.
-
 Pyramid, in various places, adapts the result of calling a view callable to
 the :class:`~pyramid.interfaces.IResponse` interface to ensure that the
 object returned by the view callable is a "true" response object.  The vast
@@ -936,8 +936,8 @@ For full details, please read the `Venusian documentation
 Registering "Tweens"
 --------------------
 
-.. note:: Tweens are a feature which were added in Pyramid 1.2.  They are
-   not available in any previous version.
+.. versionadded:: 1.2
+   Tweens
 
 A :term:`tween` (a contraction of the word "between") is a bit of code that
 sits between the Pyramid router's main request handling function and the
@@ -1082,7 +1082,7 @@ entirely by the relative ordering of calls to
 :meth:`pyramid.config.Configurator.add_tween`.  However, the caller of
 add_tween can provide an optional hint that can influence the implicit tween
 chain ordering by supplying ``under`` or ``over`` (or both) arguments to
-:meth:`~pyramid.config.Configurator.add_tween`.  These hints are only used
+:meth:`~pyramid.config.Configurator.add_tween`.  These hints are only
 used when an explicit tween ordering is not used. See
 :ref:`explicit_tween_ordering` for a description of how to set an explicit
 tween ordering.
@@ -1241,10 +1241,7 @@ implict and explicit tween chains used by an application.  See
 Adding A Third Party View, Route, or Subscriber Predicate
 ---------------------------------------------------------
 
-.. note::
-
-   Third-party view, route, and subscriber predicates are a feature new as of
-   Pyramid 1.4.
+.. versionadded:: 1.4
 
 .. _view_and_route_predicates:
 
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index ab1bf20bb..1773a6b8c 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -477,7 +477,7 @@ Registering a Default View for a Route That Has a ``view`` Attribute
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. warning:: As of :app:`Pyramid` 1.1 this section is slated to be removed in
-   a later documentation release because the the ability to add views
+   a later documentation release because the ability to add views
    directly to the :term:`route configuration` by passing a ``view`` argument
    to ``add_route`` has been deprecated.
 
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index e261f9a11..511464322 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -301,7 +301,7 @@ You need to add a few boilerplate lines to your application's ``setup.py``
 file in order to properly generate :term:`gettext` files from your
 application.
 
-.. note:: See :ref:`project_narr` to learn about about the
+.. note:: See :ref:`project_narr` to learn about the
   composition of an application's ``setup.py`` file.
 
 In particular, add the ``Babel`` and ``lingua`` distributions to the
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index e8482a289..b092f73bc 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -14,8 +14,8 @@ run :app:`Pyramid`.
 
 .. sidebar:: Python Versions
 
-    As of this writing, :app:`Pyramid` has been tested under Python 2.6.8,
-    Python 2.7.3, Python 3.2.3, and Python 3.3b1.  :app:`Pyramid` does not
+    As of this writing, :app:`Pyramid` has been tested under Python 2.6,
+    Python 2.7, Python 3.2, and Python 3.3.  :app:`Pyramid` does not
     run under any version of Python before 2.6.
 
 :app:`Pyramid` is known to run on all popular UNIX-like systems such as
@@ -40,18 +40,20 @@ UNIX system that has development tools.
 Package Manager Method
 ++++++++++++++++++++++
 
-You can use your system's "package manager" to install Python. Every
-system's package manager is slightly different, but the "flavor" of
+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 an Ubuntu Linux system, to use the system package
-manager to install a Python 2.7 interpreter, use the following
-command:
+For example, on a Debian or Ubuntu system, use the following command:
 
 .. code-block:: text
 
    $ sudo apt-get install python2.7-dev
 
+This command will install both the Python interpreter and its development
+header files.  Note that the headers are required by some (optional) C
+extensions in software depended upon by Pyramid, not by Pyramid itself.
+
 Once these steps are performed, the Python interpreter will usually be
 invokable via ``python2.7`` from a shell prompt.
 
@@ -66,7 +68,8 @@ 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.
+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
@@ -85,17 +88,15 @@ using the following commands:
 
 .. code-block:: text
 
-   [chrism@vitaminf ~]$ cd ~
-   [chrism@vitaminf ~]$ mkdir tmp
-   [chrism@vitaminf ~]$ mkdir opt
-   [chrism@vitaminf ~]$ cd tmp
-   [chrism@vitaminf tmp]$ wget \
-          http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz
-   [chrism@vitaminf tmp]$ tar xvzf Python-2.7.3.tgz
-   [chrism@vitaminf tmp]$ cd Python-2.7.3
-   [chrism@vitaminf Python-2.7.3]$ ./configure \
-           --prefix=$HOME/opt/Python-2.7.3
-   [chrism@vitaminf Python-2.7.3]$ make; make install
+   $ 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
@@ -146,37 +147,24 @@ To set up a virtualenv in which to install :app:`Pyramid`, first ensure that
 ``import setuptools`` within the Python interpreter you'd like to run
 :app:`Pyramid` under.
 
-Here's the output you'll expect if setuptools or distribute is already
-installed:
+The following command will not display anything if setuptools or distribute is
+already installed:
 
 .. code-block:: text
 
-   [chrism@thinko docs]$ python2.7
-   Python 2.7.3 (default, Aug  1 2012, 05:14:39) 
-   [GCC 4.6.3] on linux2
-   Type "help", "copyright", "credits" or "license" for more information.
-   >>> import setuptools
-   >>> 
+   $ python2.7 -c 'import setuptools'
 
-Here's the output you can expect if setuptools or distribute is not already
-installed:
+Running the same command will yield the following output if setuptools or
+distribute is not yet installed:
 
 .. code-block:: text
 
-   [chrism@thinko docs]$ python2.7
-   Python 2.7.3 (default, Aug  1 2012, 05:14:39) 
-   [GCC 4.6.3] on linux2
-   Type "help", "copyright", "credits" or "license" for more information.
-   >>> import setutptools
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
-   ImportError: No module named setutptools
-   >>>
+   ImportError: No module named setuptools
 
 If ``import setuptools`` raises an :exc:`ImportError` as it does above, you
-will need to install setuptools or distribute manually.  Note that above
-we're using a Python 2.7-series interpreter on Mac OS X; your output may
-differ if you're using a later Python version or a different platform.
+will need to install setuptools or distribute manually.
 
 If you are using a "system" Python (one installed by your OS distributor or a
 3rd-party packager such as Fink or MacPorts), you can usually install the
@@ -243,6 +231,20 @@ Once you've got setuptools or distribute 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::
+
+   Python 3.3 includes ``pyvenv`` out of the box, which provides similar
+   functionality to ``virtualenv``.  We however suggest using ``virtualenv``
+   instead, which works well with Python 3.3.  This isn't a recommendation made
+   for technical reasons; it's made because it's not feasible for the authors
+   of this guide to explain setup using multiple virtual environment systems.
+   We are aiming to not need to make the installation documentation
+   Turing-complete.
+
+   If you insist on using ``pyvenv``, you'll need to understand how to install
+   software such as ``distribute`` into the virtual environment manually,
+   which this guide does not cover.
+
 .. code-block:: text
 
    $ easy_install virtualenv
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index b35c61720..3540ee5c4 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -101,7 +101,7 @@ frameworks for small and large applications is just false; a well-designed
 framework should be able to be good at both.  Pyramid strives to be that kind
 of framework.
 
-To this end, Pyramid provides a set of features, that, combined, are unique
+To this end, Pyramid provides a set of features that, combined, are unique
 amongst Python web frameworks.  Lots of other frameworks contain some
 combination of these features; Pyramid of course actually stole many of them
 from those other frameworks.  But Pyramid is the only one that has all of
@@ -475,7 +475,7 @@ per route.  For example, you can create a route with the pattern ``/items``
 and when the route is matched, you can shuffle off the request to one view if
 the request method is GET, another view if the request method is POST, etc.
 A system known as "view predicates" allows for this.  Request method matching
-is the very most basic thing you can do with a view predicate.  You can also
+is the most basic thing you can do with a view predicate.  You can also
 associate views with other request parameters such as the elements in the
 query string, the Accept header, whether the request is an XHR request or
 not, and lots of other things.  This feature allows you to keep your
@@ -749,7 +749,7 @@ that we change Pyramid?  You can extend Pyramid's :term:`Configurator` with
 your own directives.  For example, let's say you find yourself calling
 :meth:`pyramid.config.Configurator.add_view` repetitively.  Usually you can
 take the boring away by using existing shortcuts, but let's say that this is
-a case such a way that no existing shortcut works to take the boring away:
+a case where there is no such shortcut:
 
 .. code-block:: python
    :linenos:
diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index b88f3f0c8..7784e8960 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -130,6 +130,23 @@ introspectables in categories not described here.
     A sequence of interfaces (or classes) that are subscribed to (the
     resolution of the ``ifaces`` argument passed to ``add_subscriber``).
 
+  ``derived_subscriber``
+
+    A wrapper around the subscriber used internally by the system so it can
+    call it with more than one argument if your original subscriber accepts
+    only one.
+
+  ``predicates``
+
+    The predicate objects created as the result of passing predicate arguments
+    to ``add_susbcriber``
+
+  ``derived_predicates``
+
+    Wrappers around the predicate objects created as the result of passing
+    predicate arguments to ``add_susbcriber`` (to be used when predicates take
+    only one value but must be passed more than one).
+
 ``response adapters``
 
   Each introspectable in the ``response adapters`` category represents a call
@@ -479,7 +496,7 @@ introspectables in categories not described here.
 ``translation directories``
 
   Each introspectable in the ``asset overrides`` category represents an
-  individual element in a ``specs`` argument passed to to
+  individual element in a ``specs`` argument passed to
   :meth:`pyramid.config.Configurator.add_translation_dirs`; each will have
   the following data.
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index b08948e43..5a8ea0ecf 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -297,7 +297,7 @@ 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://129.168.1.50:6543/``. However, *other people* on other computers on
+``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/``.
 
@@ -829,25 +829,25 @@ also informs Python that the directory which contains it is a *package*.
 #. Line 1 imports the :term:`Configurator` class from :mod:`pyramid.config`
    that we use later.
 
-#. Lines 3-10 define a function named ``main`` that returns a :app:`Pyramid`
+#. Lines 4-11 define a function named ``main`` that returns a :app:`Pyramid`
    WSGI application.  This function is meant to be called by the
    :term:`PasteDeploy` framework as a result of running ``pserve``.
 
    Within this function, application configuration is performed.
 
-   Line 6 creates an instance of a :term:`Configurator`.
+   Line 7 creates an instance of a :term:`Configurator`.
 
-   Line 7 registers a static view, which will serve up the files from the
+   Line 8 registers a static view, which will serve up the files from the
    ``myproject:static`` :term:`asset specification` (the ``static``
    directory of the ``myproject`` package).
 
-   Line 8 adds a :term:`route` to the configuration.  This route is later
+   Line 9 adds a :term:`route` to the configuration.  This route is later
    used by a view in the ``views`` module.
 
-   Line 9 calls ``config.scan()``, which picks up view registrations declared
+   Line 10 calls ``config.scan()``, which picks up view registrations declared
    elsewhere in the package (in this case, in the ``views.py`` module).
 
-   Line 10 returns a :term:`WSGI` application to the caller of the function
+   Line 11 returns a :term:`WSGI` application to the caller of the function
    (Pyramid's pserve).
 
 .. index::
@@ -865,7 +865,7 @@ and which returns a :term:`response`.
    :language: python
    :linenos:
 
-Lines 3-5 define and register a :term:`view callable` named ``my_view``.  The
+Lines 4-6 define and register a :term:`view callable` named ``my_view``.  The
 function named ``my_view`` is decorated with a ``view_config`` decorator
 (which is processed by the ``config.scan()`` line in our ``__init__.py``).
 The view_config decorator asserts that this view be found when a
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 1158d2225..863932e83 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -63,7 +63,6 @@ the ``renderer`` attribute.  For example, this call to
 with a view callable:
 
 .. code-block:: python
-   :linenos:
 
    config.add_view('myproject.views.my_view', renderer='json')
 
@@ -73,13 +72,13 @@ which renders view return values to a :term:`JSON` response serialization.
 
 Other built-in renderers include renderers which use the :term:`Chameleon`
 templating language to render a dictionary to a response.  Additional
-renderers can be added by developers to the system as necessary (see
-:ref:`adding_and_overriding_renderers`).
+renderers can be added by developers to the system as necessary.
+See :ref:`adding_and_overriding_renderers`.
 
 Views which use a renderer and return a non-Response value can vary non-body
 response attributes (such as headers and the HTTP status code) by attaching a
-property to the ``request.response`` attribute See
-:ref:`request_response_attr`.
+property to the ``request.response`` attribute.
+See :ref:`request_response_attr`.
 
 If the :term:`view callable` associated with a :term:`view configuration`
 returns a Response object directly, any renderer associated with the view
@@ -166,7 +165,6 @@ The body of the response returned by such a view will be a string
 representing the ``str()`` serialization of the return value:
 
 .. code-block:: python
-   :linenos:
 
    {'content': 'Hello!'}
 
@@ -204,7 +202,6 @@ The body of the response returned by such a view will be a string
 representing the JSON serialization of the return value:
 
 .. code-block:: python
-   :linenos:
 
    '{"content": "Hello!"}'
 
@@ -264,7 +261,7 @@ will be the active request object at render time.
    #    [{"x": 1}, {"x": 2}]
 
 If you aren't the author of the objects being serialized, it won't be
-possible (or at least not reasonable) to add a custom ``__json__`` method to
+possible (or at least not reasonable) to add a custom ``__json__`` method
 to their classes in order to influence serialization.  If the object passed
 to the renderer is not a serializable type, and has no ``__json__`` method,
 usually a :exc:`TypeError` will be raised during serialization.  You can
@@ -294,9 +291,8 @@ with the object.
 See :class:`pyramid.renderers.JSON` and
 :ref:`adding_and_overriding_renderers` for more information.
 
-.. note::
-
-   Serializing custom objects is a feature new in Pyramid 1.4.
+.. versionadded:: 1.4
+   Serializing custom objects.
 
 .. index::
    pair: renderer; JSONP
@@ -306,9 +302,7 @@ See :class:`pyramid.renderers.JSON` and
 JSONP Renderer
 ~~~~~~~~~~~~~~
 
-.. note::
-
-   This feature is new in Pyramid 1.1.
+.. versionadded:: 1.1
 
 :class:`pyramid.renderers.JSONP` is a `JSONP
 <http://en.wikipedia.org/wiki/JSONP>`_ renderer factory helper which
@@ -366,7 +360,7 @@ For example (Javascript):
                  '&callback=?';
    jqhxr = $.getJSON(api_url);
 
-The string ``callback=?`` above in the the ``url`` param to the JQuery
+The string ``callback=?`` above in the ``url`` param to the JQuery
 ``getAjax`` function indicates to jQuery that the query should be made as
 a JSONP request; the ``callback`` parameter will be automatically filled
 in for you and used.
@@ -571,7 +565,8 @@ in :ref:`request_module`.  For more information on the API of
 Deprecated Mechanism to Vary Attributes of Rendered Responses
 -------------------------------------------------------------
 
-.. warning:: This section describes behavior deprecated in Pyramid 1.1.
+.. deprecated:: 1.1
+   The behavior described in this entire section.
 
 In previous releases of Pyramid (1.0 and before), the ``request.response``
 attribute did not exist.  Instead, Pyramid required users to set special
@@ -619,7 +614,6 @@ For example, to add a renderer which renders views which have a
 ``renderer`` attribute that is a path that ends in ``.jinja2``:
 
 .. code-block:: python
-   :linenos:
 
    config.add_renderer('.jinja2', 'mypackage.MyJinja2Renderer')
 
@@ -689,12 +683,10 @@ There are essentially two different kinds of renderer factories:
    :term:`package`.
 
 Here's an example of the registration of a simple renderer factory via
-:meth:`~pyramid.config.Configurator.add_renderer`:
+:meth:`~pyramid.config.Configurator.add_renderer`, where ``config``
+is an instance of :meth:`pyramid.config.Configurator`:
 
 .. code-block:: python
-   :linenos:
-
-   # config is an instance of pyramid.config.Configurator
 
    config.add_renderer(name='amf', factory='my.package.MyAMFRenderer')
 
@@ -725,10 +717,8 @@ Here's an example of the registration of a more complicated renderer
 factory, which expects to be passed a filesystem path:
 
 .. code-block:: python
-   :linenos:
 
-   config.add_renderer(name='.jinja2',
-                       factory='my.package.MyJinja2Renderer')
+   config.add_renderer(name='.jinja2', factory='my.package.MyJinja2Renderer')
 
 Adding the above code to your application startup will allow you to use the
 ``my.package.MyJinja2Renderer`` renderer factory implementation in view
@@ -769,7 +759,6 @@ extension for the same kinds of templates.  For example, to associate the
 :meth:`pyramid.config.Configurator.add_renderer` method:
 
 .. code-block:: python
-   :linenos:
 
    config.add_renderer('.zpt', 'pyramid.chameleon_zpt.renderer_factory')
 
@@ -781,7 +770,6 @@ rendered via a Chameleon ZPT page template renderer, use a variation on the
 following in your application's startup code:
 
 .. code-block:: python
-   :linenos:
 
    config.add_renderer('.pt', 'mypackage.pt_renderer')
 
@@ -794,7 +782,6 @@ ones which do not possess a ``renderer`` attribute), pass ``None`` as
 the ``name`` attribute to the renderer tag:
 
 .. code-block:: python
-   :linenos:
 
    config.add_renderer(None, 'mypackage.json_renderer_factory')
 
@@ -823,8 +810,8 @@ sets an ``override_renderer`` attribute on the request itself, which is the
 .. code-block:: python
    :linenos:
 
-   from pyramid.event import subscriber
-   from pyramid.event import NewRequest
+   from pyramid.events import subscriber
+   from pyramid.events import NewRequest
 
    @subscriber(NewRequest)
    def set_xmlrpc_params(event):
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index f7da7838e..fa4affd8a 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -29,7 +29,7 @@ during your :app:`Pyramid` configuration.
 A very basic, insecure sample session factory implementation is
 provided in the :app:`Pyramid` core.  It uses a cookie to store
 session information.  This implementation has the following
-limitation:
+limitations:
 
 - The session information in the cookies used by this implementation
   is *not* encrypted, so it can be viewed by anyone with access to the
diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst
index 89551ab35..b5bc5ec48 100644
--- a/docs/narr/subrequest.rst
+++ b/docs/narr/subrequest.rst
@@ -142,7 +142,7 @@ generated.  We can change this behavior; how to do so is described below in
 our discussion of the ``use_tweens`` argument.
 
 The :meth:`pyramid.request.Request.invoke_subrequest` API accepts two
-arguments: a positional argument ``request`` that must be provided, and and
+arguments: a positional argument ``request`` that must be provided, and
 ``use_tweens`` keyword argument that is optional; it defaults to ``False``.
 
 The ``request`` object passed to the API must be an object that implements
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index ba72ebfbf..6a1fbf916 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -109,7 +109,7 @@ supply the renderer with more correct system values (see
 to compose proper system values is present in the request.  If your
 template relies on the name ``request`` or ``context``, or if you've
 configured special :term:`renderer globals`, make sure to pass
-``request`` as a keyword argument in every call to to a
+``request`` as a keyword argument in every call to a
 ``pyramid.renderers.render_*`` function.
 
 Every view must return a :term:`response` object, except for views
@@ -543,9 +543,7 @@ template as a :term:`renderer` like so:
 The above will render only the ``bar`` macro defined within the ``foo.pt``
 template instead of the entire template.
 
-.. note::
-
-   This feature is new in Pyramid 1.4.
+.. versionadded:: 1.4
 
 .. index::
    single: Chameleon text templates
@@ -743,9 +741,7 @@ configure the template as a :term:`renderer` like so:
 The above will render the ``bar`` def from within the ``foo.mak`` template
 instead of the entire template.
 
-.. note::
-
-   This feature is new in Pyramid 1.4.
+.. versionadded:: 1.4
 
 .. index::
    single: automatic reloading of templates
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index 839f59c35..20487b448 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -206,7 +206,7 @@ information.
 Upgrading to the Very Latest Pyramid Release
 --------------------------------------------
 
-When you upgrade your application to the very most recent Pyramid release,
+When you upgrade your application to the most recent Pyramid release,
 it's advisable to upgrade step-wise through each most recent minor release,
 beginning with the one that you know your application currently runs under,
 and ending on the most recent release.  For example, if your application is
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index ecf3d026a..749a2d49a 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -38,7 +38,7 @@ application.  A route has a *name*, which acts as an identifier to be used
 for URL generation.  The name also allows developers to associate a view
 configuration with the route.  A route also has a *pattern*, meant to match
 against the ``PATH_INFO`` portion of a URL (the portion following the scheme
-and port, e.g. ``/foo/bar`` in the URL ``http://localhost:8080/foo/bar``). It
+and port, e.g. ``/foo/bar`` in the URL `<http://localhost:8080/foo/bar>`_). It
 also optionally has a ``factory`` and a set of :term:`route predicate`
 attributes.
 
@@ -86,8 +86,8 @@ setup code.  However, the above :term:`scan` execution
 ``config.scan('mypackage')`` will pick up all :term:`configuration
 decoration`, including any objects decorated with the
 :class:`pyramid.view.view_config` decorator in the ``mypackage`` Python
-pakage.  For example, if you have a ``views.py`` in your package, a scan will
-pick up any of its configuration decorators, so we can add one there that
+package.  For example, if you have a ``views.py`` in your package, a scan will
+pick up any of its configuration decorators, so we can add one there
 that references ``myroute`` as a ``route_name`` parameter:
 
 .. code-block:: python
@@ -758,11 +758,8 @@ other non-``name`` and non-``pattern`` arguments to
 exception to this rule is use of the ``pregenerator`` argument, which is not
 ignored when ``static`` is ``True``.
 
-.. note::
-
-   the ``static`` argument to
-   :meth:`~pyramid.config.Configurator.add_route` is new as of :app:`Pyramid`
-   1.1.
+.. versionadded:: 1.1
+   the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route`
 
 .. index::
    single: redirecting to slash-appended routes
@@ -860,7 +857,7 @@ exactly the same job:
    request into a ``GET``, losing any ``POST`` data in the original
    request.
 
-See :ref:`view_module` and :ref:`changing_the_notfound_view` for for a more
+See :ref:`view_module` and :ref:`changing_the_notfound_view` for a more
 general description of how to configure a view and/or a not found view.
 
 .. index::
@@ -906,7 +903,7 @@ routes configured in your application; for more information, see
 Using a Route Prefix to Compose Applications
 --------------------------------------------
 
-.. note:: This feature is new as of :app:`Pyramid` 1.2.
+.. versionadded:: 1.2
 
 The :meth:`pyramid.config.Configurator.include` method allows configuration
 statements to be included from separate files.  See
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 6373a8d26..7001cd980 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -306,7 +306,7 @@ configured view.
   consideration of keys and values in the ``request.params`` dictionary.
 
 ``match_param``
-  .. note:: This feature is new as of :app:`Pyramid` 1.2.
+  .. versionadded:: 1.2
 
   This param may be either a single string of the format "key=value" or a
   dict of key/value pairs.
@@ -724,9 +724,7 @@ configuration to take effect.
 ``@view_defaults`` Class Decorator
 ----------------------------------
 
-.. note::
-
-   This feature is new in Pyramid 1.3.
+.. versionadded:: 1.3
 
 If you use a class as a view, you can use the
 :class:`pyramid.view.view_defaults` class decorator on the class to provide
@@ -834,7 +832,7 @@ decorator on the RESTView class:
 .. code-block:: python
    :linenos:
 
-   from pyramid.view import view_config
+   from pyramid.view import view_defaults
    from pyramid.response import Response
    from pyramid.config import Configurator
 
@@ -952,7 +950,7 @@ for more information about how, and where to set these values.
 Influencing HTTP Caching
 ------------------------
 
-.. note:: This feature is new in Pyramid 1.1.
+.. versionadded:: 1.1
 
 When a non-``None`` ``http_cache`` argument is passed to a view
 configuration, Pyramid will set ``Expires`` and ``Cache-Control`` response
@@ -986,7 +984,7 @@ there's a ``should_cache`` GET or POST variable:
 Note that the ``http_cache`` machinery will overwrite or add to caching
 headers you set within the view itself unless you use ``prevent_auto``.
 
-You can also turn of the effect of ``http_cache`` entirely for the duration
+You can also turn off the effect of ``http_cache`` entirely for the duration
 of a Pyramid application lifetime.  To do so, set the
 ``PYRAMID_PREVENT_HTTP_CACHE`` environment variable or the
 ``pyramid.prevent_http_cache`` configuration value setting to a true value.
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 07d018127..860c380f3 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -180,7 +180,7 @@ All classes documented in the :mod:`pyramid.httpexceptions` module documented
 as inheriting from the :class:`pyramid.httpexceptions.HTTPException` are
 :term:`http exception` objects.  Instances of an HTTP exception object may
 either be *returned* or *raised* from within view code.  In either case
-(return or raise) the instance will be used as as the view's response.
+(return or raise) the instance will be used as the view's response.
 
 For example, the :class:`pyramid.httpexceptions.HTTPUnauthorized` exception
 can be raised.  This will cause a response to be generated with a ``401
@@ -227,8 +227,8 @@ equivalent to ``raise HTTPUnauthorized()``.  Documentation which maps each
 HTTP response code to its purpose and its associated HTTP exception object is
 provided within :mod:`pyramid.httpexceptions`.
 
-.. note:: The :func:`~pyramid.httpexceptions.exception_response` function is
-   new as of Pyramid 1.1.
+.. versionadded:: 1.1
+   The :func:`~pyramid.httpexceptions.exception_response` function.
 
 How Pyramid Uses HTTP Exceptions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index a8c11acec..44940f9e6 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -251,7 +251,7 @@ API documentation for a multidict exists as
 Dealing With A JSON-Encoded Request Body
 ++++++++++++++++++++++++++++++++++++++++
 
-.. note:: this feature is new as of Pyramid 1.1.
+.. versionadded:: 1.1
 
 :attr:`pyramid.request.Request.json_body` is a property that returns a
 :term:`JSON` -decoded representation of the request body.  If the request