22 files changed, 175 insertions, 131 deletions
diff --git a/docs/api/config.rst b/docs/api/config.rst
index e6a67830e..39d504348 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -108,9 +108,7 @@
         :class:`pyramid.registry.Introspectable` class (used during
         directives to provide introspection to actions).
 
-        .. note::
-
-           This attribute is new as of :app:`Pyramid` 1.3.
+        .. versionadded:: 1.3
 
      .. attribute:: introspector
 
@@ -118,9 +116,7 @@
         instance implementing the :class:`pyramid.interfaces.IIntrospector`
         interface.
 
-        .. note::
-
-           This attribute is new as of :app:`Pyramid` 1.3.
+        .. versionadded:: 1.3
 
      .. attribute:: registry
 
diff --git a/docs/api/registry.rst b/docs/api/registry.rst
index a7879d3d5..db348495c 100644
--- a/docs/api/registry.rst
+++ b/docs/api/registry.rst
@@ -16,6 +16,8 @@
 
    .. attribute:: introspector
 
+     .. versionadded:: 1.3
+
      When a registry is set up (or created) by a :term:`Configurator`, the
      registry will be decorated with an instance named ``introspector``
      implementing the :class:`pyramid.interfaces.IIntrospector` interface.
@@ -27,28 +29,23 @@
      This attribute is often accessed as ``request.registry.introspector`` in
      a typical Pyramid application.
 
-     This attribute is new as of :app:`Pyramid` 1.3.
-
 .. class:: Introspectable
 
+   .. versionadded:: 1.3
+
    The default implementation of the interface
    :class:`pyramid.interfaces.IIntrospectable` used by framework exenders.
    An instance of this class is created when
    :attr:`pyramid.config.Configurator.introspectable` is called.
 
-   This class is new as of :app:`Pyramid` 1.3.
-
 .. autoclass:: Deferred
 
-   This class is new as of :app:`Pyramid` 1.4.
+   .. versionadded:: 1.4
 
 .. autofunction:: undefer
 
-   This function is new as of :app:`Pyramid` 1.4.
+   .. versionadded:: 1.4
 
 .. autoclass:: predvalseq
 
-   This class is new as of :app:`Pyramid` 1.4.
-
-
-
+   .. versionadded:: 1.4
diff --git a/docs/api/request.rst b/docs/api/request.rst
index e4034c635..7b843f86e 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -163,9 +163,7 @@
 
    .. method:: invoke_subrequest(request, use_tweens=False)
 
-      .. warning:: 
-
-         This API was added in Pyramid 1.4a1.
+      .. versionadded:: 1.4a1
 
       Obtain a response object from the Pyramid application based on
       information in the ``request`` object provided.  The ``request`` object
@@ -247,7 +245,7 @@
       influence response values from a view that uses a renderer (such as the
       status code, a header, the content type, etc) you would set these
       attributes.  See :ref:`response_prefixed_attrs` for further discussion.
-      As of Pyramid 1.1, assignment to ``response_*`` attrs are deprecated.
+      As of Pyramid 1.1, assignment to ``response_*`` attrs is deprecated.
       Assigning to one is still supported but will cause a deprecation
       warning to be emitted, and eventually the feature will be removed.  For
       new code, instead of assigning ``response_*`` attributes to the
diff --git a/docs/designdefense.rst b/docs/designdefense.rst
index f51ef10a9..69a921498 100644
--- a/docs/designdefense.rst
+++ b/docs/designdefense.rst
@@ -919,7 +919,7 @@ creating a more Zope3-like environment without much effort.
 Pyramid Uses its Own HTTP Exception Class Hierarchy Rather Than ``webob.exc``
 -----------------------------------------------------------------------------
 
-.. note:: This defense is new as of Pyramid 1.1.
+.. versionadded:: 1.1
 
 The HTTP exception classes defined in :mod:`pyramid.httpexceptions` are very
 much like the ones defined in ``webob.exc``
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 0036d045b..9220e6b5f 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1015,8 +1015,7 @@ Glossary
 
    Green Unicorn
       Aka ``gunicorn``, a fast :term:`WSGI` server that runs on UNIX under
-      Python 2.5+ (although at the time of this writing does not support
-      Python 3).  See http://gunicorn.org/ for detailed information.
+      Python 2.6+ or Python 3.1+.  See http://gunicorn.org/ for detailed information.
 
    predicate factory
       A callable which is used by a third party during the registration of a
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 8d6b9d984..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
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 875bc9006..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
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/hooks.rst b/docs/narr/hooks.rst
index b5efc0df1..43bf48289 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -257,6 +257,95 @@ already constructed a :term:`configurator` it can also be registered via the
    config.set_request_factory(MyRequest)
 
 .. index::
+   single: request method
+
+.. _adding_request_method:
+
+Adding Methods or Properties to Request Object
+----------------------------------------------
+
+.. 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 extensible, especially if you want to build composable features
+(e.g., Pyramid add-ons and plugins).
+
+A lazy property can be registered to the request object via the
+:meth:`pyramid.config.Configurator.add_request_method` API. This allows you
+to specify a callable that will be available on the request object, but will not
+actually execute the function until accessed.
+
+.. warning:: This will silently override methods and properties from
+   :term:`request factory` that have the same name.
+
+.. code-block:: python
+   :linenos:
+
+   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)
+
+In the above example, ``total`` is added as a method. However, ``prop`` is 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.
+
+   >>> request.total(1, 2, 3)
+   6
+   >>> request.prop
+   getting the property
+   the property
+   >>> request.prop
+   the property
+
+To not cache the result of ``request.prop``, set ``property=True`` instead of
+``reify=True``.
+
+Here is an example of passing a class to ``Configurator.add_request_method``:
+
+.. code-block:: python
+   :linenos:
+
+   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)
+
+We attach and cache an object named ``extra`` to the ``request`` object.
+
+   >>> request.extra.total(1, 2, 3)
+   6
+   >>> request.extra.prop
+   getting the property
+   the property
+   >>> request.extra.prop
+   the property
+
+.. index::
    single: before render event
    single: adding renderer globals
 
@@ -336,9 +425,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 +724,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 +1025,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
@@ -1241,10 +1330,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/install.rst b/docs/narr/install.rst
index 224a62db7..85dfd5bf4 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
@@ -88,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
@@ -166,9 +164,7 @@ distribute is not yet installed:
    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
@@ -207,7 +203,7 @@ Installing Distribute On Python 3
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``setuptools`` doesn't work under Python 3.  Instead, you can use
-``distribute``, which is a fork of setuptools that does work on Python 3.  To
+``distribute``, which is a fork of setuptools.  To
 install it, first download `distribute_setup.py
 <http://python-distribute.org/distribute_setup.py>`_ then invoke it using the
 Python interpreter into which you want to install setuptools.
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index c4f2ea512..3540ee5c4 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -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/project.rst b/docs/narr/project.rst
index fb62f4bd2..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/``.
 
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 5379a4a99..34b9ad00c 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!"}'
 
@@ -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
@@ -571,8 +565,6 @@ 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.
-
 In previous releases of Pyramid (1.0 and before), the ``request.response``
 attribute did not exist.  Instead, Pyramid required users to set special
 ``response_`` -prefixed attributes of the request to influence response
@@ -619,7 +611,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 +680,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 +714,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 +756,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 +767,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 +779,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')
 
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/templates.rst b/docs/narr/templates.rst
index 1cec26fbc..6a1fbf916 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -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/urldispatch.rst b/docs/narr/urldispatch.rst
index ec97bf3b2..749a2d49a 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -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
@@ -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 f00dae451..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
@@ -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
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 4f30bb7fa..860c380f3 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -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
diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
index 03abedbd8..f9d4775ad 100644
--- a/docs/tutorials/wiki/basiclayout.rst
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -165,7 +165,7 @@ opposed to the tutorial :term:`package` directory) looks like this:
 .. literalinclude:: src/basiclayout/development.ini
    :language: ini
 
-Note the existence of an ``[app:main]`` section which specifies our WSGI
+Note the existence of a ``[app:main]`` section which specifies our WSGI
 application.  Our ZODB database settings are specified as the
 ``zodbconn.uri`` setting within this section.  This value, and the other
 values within this section are passed as ``**settings`` to the ``main``