- The ``add_route`` method of the Configurator now accepts a ``static``

  argument.  If this argument is ``True``, the added route will never be
  considered for matching when a request is handled.  Instead, it will only
  be useful for URL generation via ``route_url`` and ``route_path``.  See the
  section entitled "Static Routes" in the URL Dispatch narrative chapter for
  more information.

1 files changed, 29 insertions, 0 deletions

diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index a180003d0..5df1eb3af 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -832,6 +832,35 @@ See the :func:`~pyramid.url.route_url` API documentation for more
 information.
 
 .. index::
+   single: static routes
+
+.. _static_route_narr:
+
+Static Routes
+-------------
+
+Routes may be added with a ``static`` keyword argument.  For example:
+
+.. code-block:: python
+   :linenos:
+
+   config = Configurator()
+   config.add_route('page', '/page/{action}', static=True)
+
+Routes added with a ``True`` ``static`` keyword argument will never be
+considered for matching at request time.  Static routes are useful for URL
+generation purposes only.  As a result, it is usually nonsensical to provide
+other non-``name`` and non-``pattern`` arguments to
+:meth:`~pyramid.config.Configurator.add_route` when ``static`` is passed as
+``True``, as none of the other arguments will ever be employed.  A single
+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.
+
+.. index::
    single: redirecting to slash-appended routes
 
 .. _redirecting_to_slash_appended_routes: