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

23 files changed, 377 insertions, 78 deletions

diff --git a/docs/Makefile b/docs/Makefile
index c98fdc65e..12dc88bf8 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -63,8 +63,13 @@ latex:
 	cp _static/latex-note.png _build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in _build/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
+	@echo "Run \`make latexpdf' to build a PDF file from them."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C _build/latex all-pdf
+	@echo "pdflatex finished; the PDF file is in _build/latex."
 
 changes:
 	mkdir -p _build/changes _build/doctrees
diff --git a/docs/_themes b/docs/_themes
-Subproject f59f7bfce5259f50fbb67b9040c03ecb080130b
+Subproject 8673c4a14f192c15f1949dc9862821e60f31604
diff --git a/docs/api/config.rst b/docs/api/config.rst
index 39d504348..1f65be9f1 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -135,3 +135,4 @@
    will only exist for the lifetime of the actual applications for which they
    are being used.
 
+.. autoclass:: not_
diff --git a/docs/api/registry.rst b/docs/api/registry.rst
index db348495c..7736cf075 100644
--- a/docs/api/registry.rst
+++ b/docs/api/registry.rst
@@ -29,6 +29,15 @@
      This attribute is often accessed as ``request.registry.introspector`` in
      a typical Pyramid application.
 
+   .. method:: notify(*events)
+
+     Fire one or more events. All event subscribers to the event(s)
+     will be notified. The subscribers will be called synchronously.
+     This method is often accessed as ``request.registry.notify``
+     in Pyramid applications to fire custom events. See
+     :ref:`custom_events` for more information.
+
+
 .. class:: Introspectable
 
    .. versionadded:: 1.3
diff --git a/docs/api/request.rst b/docs/api/request.rst
index b1f5918d7..a90cb1ac0 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -156,7 +156,7 @@
    .. attribute:: matched_route
 
       If a :term:`route` has matched during this request, this attribute will
-      be an obect representing the route matched by the URL pattern
+      be an object representing the route matched by the URL pattern
       associated with the route.  If a route has not matched during this
       request, the value of this attribute will be ``None``. See
       :ref:`matched_route`.
@@ -238,7 +238,7 @@
    .. attribute::  response_*
 
       In Pyramid 1.0, you could set attributes on a
-      :class:`pyramid.request.Request` which influenced the behavor of
+      :class:`pyramid.request.Request` which influenced the behavior of
       *rendered* responses (views which use a :term:`renderer` and which
       don't directly return a response).  These attributes began with
       ``response_``, such as ``response_headerlist``. If you needed to
diff --git a/docs/authorintro.rst b/docs/authorintro.rst
index f1a9d1484..b3cd68494 100644
--- a/docs/authorintro.rst
+++ b/docs/authorintro.rst
@@ -73,7 +73,7 @@ This book is divided into three major parts:
   concepts in terms of the sample.  You should read the tutorials if
   you want a guided tour of :app:`Pyramid`.
 
-:ref:`api_reference`
+:ref:`api_documentation`
 
   Comprehensive reference material for every public API exposed by
   :app:`Pyramid`.  The API documentation is organized
diff --git a/docs/conf.py b/docs/conf.py
index 84b01a791..e50c0c60a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -19,6 +19,8 @@ import warnings
 
 warnings.simplefilter('ignore', DeprecationWarning)
 
+import pkg_resources
+
 # skip raw nodes
 from sphinx.writers.text import TextTranslator
 from sphinx.writers.latex import LaTeXTranslator
@@ -93,7 +95,7 @@ copyright = '2008-%s, Agendaless Consulting' % thisyear
 # other places throughout the built documents.
 #
 # The short X.Y version.
-version = '1.4'
+version = pkg_resources.get_distribution('pyramid').version
 
 # The full version, including alpha/beta/rc tags.
 release = version
diff --git a/docs/foreword.rst b/docs/foreword.rst
index aa8d7c77b..cc8271bdf 100644
--- a/docs/foreword.rst
+++ b/docs/foreword.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Foreword
 ========
 
diff --git a/docs/index.rst b/docs/index.rst
index 3c3adb9a6..8fd210ed7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,6 +37,7 @@ What's New
 .. toctree::
    :maxdepth: 1
 
+   whatsnew-1.5
    whatsnew-1.4
    whatsnew-1.3
    whatsnew-1.2
@@ -55,7 +56,7 @@ Getting Started
 
 .. _html_narrative_documentation:
 
-Narrative documentation
+Narrative Documentation
 =======================
 
 Narrative documentation in chapter form explaining how to use
@@ -120,7 +121,7 @@ platforms.
    tutorials/modwsgi/index.rst
 
 API Documentation
-==================
+=================
 
 Comprehensive reference material for every public API exposed by :app:`Pyramid`:
 
@@ -225,13 +226,8 @@ Index and Glossary
 * :ref:`genindex`
 * :ref:`search`
 
-
-.. add glossary, foreword, and latexindex in a hidden toc to avoid warnings
-
 .. toctree::
    :hidden:
 
    glossary
-   foreword.rst
-   latexindex.rst
 
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 6bb875f73..e2ba108ee 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -1,13 +1,15 @@
+:orphan:
+
 .. _latexindex:
 
-@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-The :app:`Pyramid` Web Application Framework
-@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+=================================================
+The Pyramid Web Application Development Framework
+=================================================
 
 .. frontmatter::
 
 Front Matter
-@@@@@@@@@@@@
+============
 
 .. toctree::
    :maxdepth: 1
@@ -21,15 +23,15 @@ Front Matter
 .. _narrative_documentation:
 
 Narrative Documentation
-@@@@@@@@@@@@@@@@@@@@@@@
+=======================
 
 .. toctree::
    :maxdepth: 1
 
    narr/introduction
    narr/install
-   narr/configuration
    narr/firstapp
+   narr/configuration
    narr/project
    narr/startup
    narr/router
@@ -50,6 +52,7 @@ Narrative Documentation
    narr/vhosting
    narr/testing
    narr/resources
+   narr/hellotraversal
    narr/muchadoabouttraversal
    narr/traversal
    narr/security
@@ -60,58 +63,39 @@ Narrative Documentation
    narr/extending
    narr/advconfig
    narr/extconfig
+   narr/scaffolding
+   narr/upgrading
    narr/threadlocals
    narr/zca
 
 .. _tutorials:
 
 Tutorials
-@@@@@@@@@
+=========
 
 .. toctree::
    :maxdepth: 1
 
-   tutorials/wiki/index.rst
    tutorials/wiki2/index.rst
+   tutorials/wiki/index.rst
    tutorials/bfg/index.rst
    tutorials/modwsgi/index.rst
 
-.. _api_reference:
+.. _api_documentation:
 
-API Reference
-@@@@@@@@@@@@@
+API Documentation
+=================
 
 .. toctree::
    :maxdepth: 1
+   :glob:
 
-   api/authorization
-   api/authentication
-   api/config
-   api/events
-   api/exceptions
-   api/httpexceptions
-   api/i18n
-   api/interfaces
-   api/location
-   api/paster
-   api/registry
-   api/renderers
-   api/request
-   api/response
-   api/scripting
-   api/security
-   api/settings
-   api/testing
-   api/threadlocal
-   api/traversal
-   api/url
-   api/view
-   api/wsgi
+   api/*
 
 .. backmatter::
 
 Glossary and Index
-@@@@@@@@@@@@@@@@@@
+==================
 
 .. toctree::
   :maxdepth: 1
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index e1347f3ca..17e5227fa 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -474,6 +474,30 @@ input of the ``prequest`` process is used as the ``POST`` body::
 
    $ $VENV/bin/prequest -mPOST development.ini / < somefile
 
+Showing All Installed Distributions and their Versions
+------------------------------------------------------
+
+.. versionadded:: 1.5
+
+You can use the ``pdistreport`` command to show the Pyramid version in use, the
+Python version in use, and all installed versions of Python distributions in
+your Python environment::
+
+   $ $VENV/bin/pdistreport
+   Pyramid version: 1.5dev 
+   Platform Linux-3.2.0-51-generic-x86_64-with-debian-wheezy-sid 
+   Packages: 
+     authapp 0.0 
+       /home/chrism/projects/foo/src/authapp 
+     beautifulsoup4 4.1.3 
+       /home/chrism/projects/foo/lib/python2.7/site-packages/beautifulsoup4-4.1.3-py2.7.egg
+   ... more output ...
+
+``pdistreport`` takes no options.  Its output is useful to paste into a
+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
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index 929208083..11af89ca6 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -53,7 +53,7 @@ method (see also :term:`Configurator`):
 
   from subscribers import mysubscriber
 
-  # "config" below is assumed to be an instance of a 
+  # "config" below is assumed to be an instance of a
   # pyramid.config.Configurator object
 
   config.add_subscriber(mysubscriber, NewRequest)
@@ -77,7 +77,7 @@ type via the :func:`pyramid.events.subscriber` function.
 
   @subscriber(NewRequest)
   def mysubscriber(event):
-	  event.request.foo = 1
+      event.request.foo = 1
 
 When the :func:`~pyramid.events.subscriber` decorator is used a
 :term:`scan` must be performed against the package containing the
@@ -113,7 +113,7 @@ your application like so:
    :linenos:
 
    def handle_new_request(event):
-       print 'request', event.request   
+       print 'request', event.request
 
    def handle_new_response(event):
        print 'response', event.response
@@ -150,3 +150,86 @@ application, because the interface defined at
 :class:`pyramid.interfaces.INewResponse` says it must
 (:class:`pyramid.events.NewResponse` objects also have a ``request``).
 
+.. _custom_events:
+
+Creating Your Own Events
+------------------------
+
+In addition to using the events that the Pyramid framework creates,
+you can create your own events for use in your application. This can
+be useful to decouple parts of your application.
+
+For example, suppose your application has to do many things when a new
+document is created. Rather than putting all this logic in the view
+that creates the document, you can create the document in your view
+and then fire a custom event. Subscribers to the custom event can take
+other actions, such as indexing the document, sending email, or
+sending a message to a remote system.
+
+An event is simply an object. There are no required attributes or
+method for your custom events. In general, your events should keep
+track of the information that subscribers will need. Here are some
+example custom event classes:
+
+.. code-block:: python
+   :linenos:
+
+    class DocCreated(object):
+        def __init__(self, doc, request):
+            self.doc = doc
+            self.request = request
+
+    class UserEvent(object):
+        def __init__(self, user):
+            self.user = user
+
+    class UserLoggedIn(UserEvent):
+        pass
+
+Some Pyramid applications choose to define custom events classes in an
+``events`` module.
+
+You can subscribe to custom events in the same way that you subscribe
+to Pyramid events -- either imperatively or with a decorator. You can
+also use custom events with :ref:`subscriber predicates
+<subscriber_predicates>`. Here's an example of subscribing to a custom
+event with a decorator:
+
+.. code-block:: python
+   :linenos:
+
+    from pyramid.events import subscriber
+    from .events import DocCreated
+    from .index import index_doc
+
+    @subscriber(DocCreated)
+    def index_doc(event):
+        # index the document using our application's index_doc function
+        index_doc(event.doc, event.request)
+
+The above example assumes that the application defines a
+``DocCreated`` event class and an ``index_doc`` function.
+
+To fire your custom events use the
+:meth:`pyramid.registry.Registry.notify` method, which is most often
+accessed as ``request.registry.notify``. For example:
+
+.. code-block:: python
+   :linenos:
+
+    from .events import DocCreated
+
+    def new_doc_view(request):
+        doc = MyDoc()
+        event = DocCreated(doc, request)
+        request.registry.notify(event)
+        return {'document': doc}
+
+This example view will notify all subscribers to the custom
+``DocCreated`` event.
+
+Note that when you fire an event, all subscribers are run
+synchronously so it's generally not a good idea
+to create event handlers that may take a long time to run. Although
+event handlers could be used as a central place to spawn tasks on your
+own message queues.
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 74765f8e2..2964686d3 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -808,7 +808,7 @@ If this setting is supplied within the :app:`Pyramid` application
    default_locale_name = settings['pyramid.default_locale_name']
 
 .. index::
-   single: detecting langauges
+   single: detecting languages
 
 "Detecting" Available Languages
 -------------------------------
@@ -984,7 +984,7 @@ requires no additional coding or configuration.
 
 The default locale negotiator implementation named
 :class:`~pyramid.i18n.default_locale_negotiator` uses the following
-set of steps to dermine the locale name.
+set of steps to determine the locale name.
 
 - First, the negotiator looks for the ``_LOCALE_`` attribute of the
   request object (possibly set directly by view code or by a listener
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 48164d323..032f4be6b 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -217,6 +217,8 @@ that the Pyramid core doesn't.  Add-on packages already exist which let you
 easily 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
+
 
 Class-based and function-based views
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -857,7 +859,7 @@ It's our goal that no Pyramid question go unanswered.  Whether you ask a
 question on IRC, on the Pylons-discuss maillist, or on StackOverflow, you're
 likely to get a reasonably prompt response.  We don't tolerate "support
 trolls" or other people who seem to get their rocks off by berating fellow
-users in our various offical support channels.  We try to keep it well-lit
+users in our various official support channels.  We try to keep it well-lit
 and new-user-friendly.
 
 Example: Visit irc\://freenode.net#pyramid (the ``#pyramid`` channel on
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 8cf67e104..ec5d706aa 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -1007,12 +1007,12 @@ Pyramid application based on the data in the file.
 application.  As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be
 invoked at all to run a :app:`Pyramid` application.  The use of ``pserve`` to
 run a :app:`Pyramid` application is purely conventional based on the output
-of its scaffolding.  But we strongly recommend using while developing your
-application, because many other convenience introspection commands (such as
-``pviews``, ``prequest``, ``proutes`` and others) are also implemented in
-terms of configuration availability of this ``.ini`` file format.  It also
-configures Pyramid logging and provides the ``--reload`` switch for
-convenient restarting of the server when code changes.
+of its scaffolding.  But we strongly recommend using ``pserve`` while
+developing your application, because many other convenience introspection
+commands (such as ``pviews``, ``prequest``, ``proutes`` and others) are also
+implemented in terms of configuration availability of this ``.ini`` file
+format.  It also configures Pyramid logging and provides the ``--reload``
+switch for convenient restarting of the server when code changes.
 
 .. _alternate_wsgi_server:
 
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 20a9eda31..a2811dbae 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -198,7 +198,7 @@ representing the JSON serialization of the return value:
 
 .. code-block:: python
 
-   '{"content": "Hello!"}'
+   {"content": "Hello!"}
 
 The return value needn't be a dictionary, but the return value must contain
 values serializable by the configured serializer (by default ``json.dumps``).
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 7ec280c8a..82440060c 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -148,6 +148,7 @@ Some gotchas:
 .. index::
    single: pyramid_beaker
    single: Beaker
+   single: pyramid_redis_sessions
    single: session factory (alternates)
 
 .. _using_alternate_session_factories:
@@ -155,11 +156,17 @@ Some gotchas:
 Using Alternate Session Factories
 ---------------------------------
 
-At the time of this writing, exactly one alternate session factory
-implementation exists, named ``pyramid_beaker``. This is a session factory
-that uses the `Beaker <http://beaker.groovie.org/>`_ library as a backend.
-Beaker has support for file-based sessions, database based sessions, and
-encrypted cookie-based sessions.  See `the pyramid_beaker documentation
+At the time of this writing, exactly two alternate session factories
+exist.
+
+The first is named ``pyramid_redis_sessions``.  It can be downloaded from PyPI.
+It uses Redis as a backend.  It is the recommended persistent session solution
+at the time of this writing.
+
+The second is named ``pyramid_beaker``. This is a session factory that uses the
+`Beaker <http://beaker.groovie.org/>`_ library as a backend.  Beaker has
+support for file-based sessions, database based sessions, and encrypted
+cookie-based sessions.  See `the pyramid_beaker documentation
 <http://docs.pylonsproject.org/projects/pyramid_beaker/en/latest/>`_ for more
 information about ``pyramid_beaker``.
 
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index d4cf20b93..af5ad6c5c 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -723,7 +723,7 @@ This template doesn't use any advanced features of Mako, only the
 Using A Mako def name Within a Renderer Name
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sommetime you'd like to render a ``def`` inside of a Mako template instead of
+Sometimes you'd like to render a ``def`` inside of a Mako template instead of
 the full Mako template. To render a def inside a Mako template, given a
 :term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can
 configure the template as a :term:`renderer` like so:
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 2eb6ece13..a60c5ba56 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -289,7 +289,7 @@ system uses this algorithm to find a :term:`context` resource and a
     return resource "C".
 
 #.  Traversal ends when a) the entire path is exhausted or b) when any
-    resouce raises a :exc:`KeyError` from its ``__getitem__`` or c) when any
+    resource raises a :exc:`KeyError` from its ``__getitem__`` or c) when any
     non-final path element traversal does not have a ``__getitem__`` method
     (resulting in a :exc:`AttributeError`) or d) when any path element is
     prefixed with the set of characters ``@@`` (indicating that the characters
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 18cb3e4db..310c160c0 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -865,7 +865,7 @@ Debugging Route Matching
 ------------------------
 
 It's useful to be able to take a peek under the hood when requests that enter
-your application arent matching your routes as you expect them to.  To debug
+your application aren't matching your routes as you expect them to.  To debug
 route matching, use the ``PYRAMID_DEBUG_ROUTEMATCH`` environment variable or the
 ``pyramid.debug_routematch`` configuration file setting (set either to ``true``).
 Details of the route matching decision for a particular request to the
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 241ce62b5..6a064c209 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -290,9 +290,9 @@ configured view.
   of the ``REQUEST_METHOD`` of the :term:`WSGI` environment.
 
 ``request_param``
-  This value can be any string or a sequence of strings.  A view declaration 
-  with this argument ensures that the view will only be called when the 
-  :term:`request` has a key in the ``request.params`` dictionary (an HTTP 
+  This value can be any string or a sequence of strings.  A view declaration
+  with this argument ensures that the view will only be called when the
+  :term:`request` has a key in the ``request.params`` dictionary (an HTTP
   ``GET`` or ``POST`` variable) that has a name which matches the
   supplied value.
 
@@ -306,8 +306,6 @@ configured view.
   consideration of keys and values in the ``request.params`` dictionary.
 
 ``match_param``
-  .. versionadded:: 1.2
-
   This param may be either a single string of the format "key=value" or a
   dict of key/value pairs.
 
@@ -324,6 +322,8 @@ configured view.
   If ``match_param`` is not supplied, the view will be invoked without
   consideration of the keys and values in ``request.matchdict``.
 
+  .. versionadded:: 1.2
+
 ``containment``
   This value should be a reference to a Python class or :term:`interface`
   that a parent object in the context resource's :term:`lineage` must provide
@@ -505,7 +505,7 @@ configuration stanza:
 .. code-block:: python
    :linenos:
 
-   config.add_view('mypackage.views.my_view', route_name='ok', 
+   config.add_view('mypackage.views.my_view', route_name='ok',
                    request_method='POST', permission='read')
 
 All arguments to ``view_config`` may be omitted.  For example:
@@ -557,6 +557,35 @@ form of :term:`declarative configuration`, while
 :meth:`pyramid.config.Configurator.add_view` is a form of :term:`imperative
 configuration`.  However, they both do the same thing.
 
+Inverting Predicate Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can invert the meaning of any predicate value by wrapping it in a call to
+:class:`pyramid.config.not_`.
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.config import not_
+
+   config.add_view(
+       'mypackage.views.my_view',
+       route_name='ok',
+       request_method=not_('POST')
+       )
+
+The above example will ensure that the view is called if the request method
+is *not* ``POST``, at least if no other view is more specific.
+
+This technique of wrapping a predicate value in ``not_`` can be used anywhere
+predicate values are accepted:
+
+- :meth:`pyramid.config.Configurator.add_view`
+
+- :meth:`pyramid.view.view_config`
+
+.. versionadded:: 1.5
+
 .. index::
    single: view_config placement
 
@@ -802,7 +831,7 @@ of this:
        config.add_view(
            RESTView, route_name='rest', attr='delete', request_method='DELETE')
 
-To reduce the amount of repetion in the ``config.add_view`` statements, we
+To reduce the amount of repetition in the ``config.add_view`` statements, we
 can move the ``route_name='rest'`` argument to a ``@view_default`` class
 decorator on the RESTView class:
 
diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
index 5cba8dd3e..cc63017df 100644
--- a/docs/whatsnew-1.1.rst
+++ b/docs/whatsnew-1.1.rst
@@ -13,7 +13,7 @@ Terminology Changes
 The term "template" used by the Pyramid documentation used to refer to both
 "paster templates" and "rendered templates" (templates created by a rendering
 engine.  i.e. Mako, Chameleon, Jinja, etc.).  "Paster templates" will now be
-refered to as "scaffolds", whereas the name for "rendered templates" will
+referred to as "scaffolds", whereas the name for "rendered templates" will
 remain as "templates."
 
 Major Feature Additions
@@ -397,7 +397,7 @@ Deprecations and Behavior Differences
    shell you use to invoke ``paster serve`` to see these warnings, e.g. on
    UNIX, ``PYTHONWARNINGS=all $VENV/bin/paster serve development.ini``.
    Python 2.5 and 2.6 show deprecation warnings by default,
-   so this is unecessary there.
+   so this is unnecessary there.
    All deprecation warnings are emitted to the console.
 
 - The :class:`pyramid.view.static` class has been deprecated in favor of the
diff --git a/docs/whatsnew-1.5.rst b/docs/whatsnew-1.5.rst
new file mode 100644
index 000000000..b987fa77f
--- /dev/null
+++ b/docs/whatsnew-1.5.rst
@@ -0,0 +1,155 @@
+What's New In Pyramid 1.5
+=========================
+
+This article explains the new features in :app:`Pyramid` version 1.5 as
+compared to its predecessor, :app:`Pyramid` 1.4.  It also documents backwards
+incompatibilities between the two versions and deprecations added to
+:app:`Pyramid` 1.5, as well as software dependency changes and notable
+documentation additions.
+
+Feature Additions
+-----------------
+
+The feature additions in Pyramid 1.5 follow.
+
+- Add ``pdistreport`` script, which prints the Python version in use, the
+  Pyramid version in use, and the version number and location of all Python
+  distributions currently installed.
+
+- Add the ability to invert the result of any view, route, or subscriber
+  predicate value using the ``not_`` class.  For example:
+
+  .. code-block:: python
+
+     from pyramid.config import not_
+
+     @view_config(route_name='myroute', request_method=not_('POST'))
+     def myview(request): ...
+
+  The above example will ensure that the view is called if the request method
+  is not POST, at least if no other view is more specific.
+
+  The :class:`pyramid.config.not_` class can be used against any value that is
+  a predicate value passed in any of these contexts:
+
+  - :meth:`pyramid.config.Configurator.add_view`
+
+  - :meth:`pyramid.config.Configurator.add_route`
+
+  - :meth:`pyramid.config.Configurator.add_subscriber`
+
+  - :meth:`pyramid.view.view_config`
+
+  - :meth:`pyramid.events.subscriber`
+
+- View lookup will now search for valid views based on the inheritance
+  hierarchy of the context. It tries to find views based on the most specific
+  context first, and upon predicate failure, will move up the inheritance chain
+  to test views found by the super-type of the context.  In the past, only the
+  most specific type containing views would be checked and if no matching view
+  could be found then a PredicateMismatch would be raised. Now predicate
+  mismatches don't hide valid views registered on super-types. Here's an
+  example that now works:
+
+  .. code-block:: python
+
+     class IResource(Interface):
+
+         ...
+
+     @view_config(context=IResource)
+     def get(context, request):
+
+         ...
+
+     @view_config(context=IResource, request_method='POST')
+     def post(context, request):
+
+         ...
+
+     @view_config(context=IResource, request_method='DELETE')
+     def delete(context, request):
+
+         ...
+
+     @implementor(IResource)
+     class MyResource:
+
+         ...
+
+     @view_config(context=MyResource, request_method='POST')
+     def override_post(context, request):
+
+         ...
+
+  Previously the override_post view registration would hide the get
+  and delete views in the context of MyResource -- leading to a
+  predicate mismatch error when trying to use GET or DELETE
+  methods. Now the views are found and no predicate mismatch is
+  raised.
+  See https://github.com/Pylons/pyramid/pull/786 and
+  https://github.com/Pylons/pyramid/pull/1004 and
+  https://github.com/Pylons/pyramid/pull/1046
+
+- ``scripts/prequest.py`` (aka the ``prequest`` console script): added support
+  for submitting ``PUT`` and ``PATCH`` requests.  See
+  https://github.com/Pylons/pyramid/pull/1033.  add support for submitting
+  ``OPTIONS`` and ``PROPFIND`` requests, and allow users to specify basic
+  authentication credentials in the request via a ``--login`` argument to the
+  script.  See https://github.com/Pylons/pyramid/pull/1039.
+
+- :class:`pyramid.authorization.ACLAuthorizationPolicy` supports ``__acl__`` as
+  a callable. This removes the ambiguity between the potential
+  ``AttributeError`` that would be raised on the ``context`` when the property
+  was not defined and the ``AttributeError`` that could be raised from any
+  user-defined code within a dynamic property. It is recommended to define a
+  dynamic ACL as a callable to avoid this ambiguity. See
+  https://github.com/Pylons/pyramid/issues/735.
+
+- Allow a protocol-relative URL (e.g. ``//example.com/images``) to be passed to
+  :meth:`pyramid.config.Configurator.add_static_view`. This allows
+  externally-hosted static URLs to be generated based on the current protocol.
+
+- The :class:`pyramid.authentication.AuthTktAuthenticationPolicy` has a new
+  ``parent_domain`` option to set the authentication cookie as a wildcard
+  cookie on the parent domain. This is useful if you have multiple sites
+  sharing the same domain.  It also now supports IPv6 addresses when using
+  the ``include_ip=True`` option. This is possibly incompatible with
+  alternative ``auth_tkt`` implementations, as the specification does not
+  define how to properly handle IPv6. See
+  https://github.com/Pylons/pyramid/issues/831.
+
+- Make it possible to use variable arguments via
+  :func:`pyramid.paster.get_appsettings`. This also allowed the generated
+  ``initialize_db`` script from the ``alchemy`` scaffold to grow support for
+  options in the form ``a=1 b=2`` so you can fill in values in a parameterized
+  ``.ini`` file, e.g.  ``initialize_myapp_db etc/development.ini a=1 b=2``.  See
+  https://github.com/Pylons/pyramid/pull/911
+
+- The ``request.session.check_csrf_token()`` method and the ``check_csrf`` view
+  predicate now take into account the value of the HTTP header named
+  ``X-CSRF-Token`` (as well as the ``csrf_token`` form parameter, which they
+  always did).  The header is tried when the form parameter does not exist.
+
+Backwards Incompatibilities
+---------------------------
+
+This release has no known backwards incompatibilities with Pyramid 1.4.X.
+
+Deprecations
+------------
+
+This release has no new deprecations as compared to Pyramid 1.4.X.
+
+
+Documentation Enhancements
+--------------------------
+
+Many documentation enhancements have been added, but we did not track them as
+they were added.
+
+Dependency Changes
+------------------
+
+No dependency changes from Pyramid 1.4.X were made in Pyramid 1.5.
+