Features

--------

- Added ``debug_routematch`` configuration setting that logs matched routes
  (including the matchdict and predicates).

Documentation
-------------

- Added "Debugging Route Matching" section to the urldispatch narrative
  documentation chapter.

- Added reference to ``BFG_DEBUG_ROUTEMATCH`` envvar and ``debug_routematch``
  config file setting to the Environment narrative docs chapter.

12 files changed, 56 insertions, 10 deletions

diff --git a/docs/narr/MyProject/development.ini b/docs/narr/MyProject/development.ini
index 7a48b5bc5..48fc81b8c 100644
--- a/docs/narr/MyProject/development.ini
+++ b/docs/narr/MyProject/development.ini
@@ -3,7 +3,7 @@ use = egg:MyProject
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
-debug_matched = false
+debug_routematch = false
 debug_templates = true
 default_locale_name = en
 
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 44e75542c..08fa7af44 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -97,6 +97,21 @@ when this value is true.  See also :ref:`debug_notfound_section`.
 |                                 |                             |
 +---------------------------------+-----------------------------+
 
+Debugging Route Matching
+------------------------
+
+Print debugging messages related to :term:`url dispatch` route matching when
+this value is true.  See also :ref:`debug_routematch_section`.
+
++---------------------------------+-----------------------------+
+| Environment Variable Name       | Config File Setting Name    |
++=================================+=============================+
+| ``BFG_DEBUG_ROUTEMATCH``        |  ``debug_routematch``       |
+|                                 |                             |
+|                                 |                             |
+|                                 |                             |
++---------------------------------+-----------------------------+
+
 Debugging All
 -------------
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index c84a5ca06..f0ace76ba 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -1268,6 +1268,37 @@ not very ambitious.
 .. note:: See :ref:`security_chapter` for more information about
    :app:`Pyramid` security and ACLs.
 
+.. _debug_routematch_section:
+
+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
+route matching, use the ``BFG_DEBUG_ROUTEMATCH`` environment variable or the
+``debug_routematch`` configuration file setting (set either to ``true``).
+Details of the route matching decision for a particular request to the
+:app:`Pyramid` application will be printed to the ``stderr`` of the console
+which you started the application from.  For example:
+
+.. code-block:: text
+   :linenos:
+
+    [chrism@thinko pylonsbasic]$ BFG_DEBUG_ROUTEMATCH=true \
+                                 bin/paster serve development.ini 
+    Starting server in PID 13586.
+    serving on 0.0.0.0:6543 view at http://127.0.0.1:6543
+    2010-12-16 14:45:19,956 no route matched for url \
+                                        http://localhost:6543/wontmatch
+    2010-12-16 14:45:20,010 no route matched for url \
+                                http://localhost:6543/favicon.ico
+    2010-12-16 14:41:52,084 route matched for url \
+                                http://localhost:6543/static/logo.png; \
+                                route_name: 'static/', ....
+
+See :ref:`environment_chapter` for more information about how, and where to
+set these values.
+
 References
 ----------
 
diff --git a/docs/tutorials/wiki/src/authorization/development.ini b/docs/tutorials/wiki/src/authorization/development.ini
index d09da86eb..a102b721b 100644
--- a/docs/tutorials/wiki/src/authorization/development.ini
+++ b/docs/tutorials/wiki/src/authorization/development.ini
@@ -3,7 +3,7 @@ use = egg:tutorial
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
-debug_matched = false
+debug_routematch = false
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [pipeline:main]
diff --git a/docs/tutorials/wiki/src/basiclayout/development.ini b/docs/tutorials/wiki/src/basiclayout/development.ini
index 4fb6f25f8..fdae922e9 100644
--- a/docs/tutorials/wiki/src/basiclayout/development.ini
+++ b/docs/tutorials/wiki/src/basiclayout/development.ini
@@ -3,7 +3,7 @@ use = egg:tutorial
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
-debug_matched = false
+debug_routematch = false
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [pipeline:main]
diff --git a/docs/tutorials/wiki/src/models/development.ini b/docs/tutorials/wiki/src/models/development.ini
index 4fb6f25f8..fdae922e9 100644
--- a/docs/tutorials/wiki/src/models/development.ini
+++ b/docs/tutorials/wiki/src/models/development.ini
@@ -3,7 +3,7 @@ use = egg:tutorial
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
-debug_matched = false
+debug_routematch = false
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [pipeline:main]
diff --git a/docs/tutorials/wiki/src/viewdecorators/development.ini b/docs/tutorials/wiki/src/viewdecorators/development.ini
index d09da86eb..a102b721b 100644
--- a/docs/tutorials/wiki/src/viewdecorators/development.ini
+++ b/docs/tutorials/wiki/src/viewdecorators/development.ini
@@ -3,7 +3,7 @@ use = egg:tutorial
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
-debug_matched = false
+debug_routematch = false
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [pipeline:main]
diff --git a/docs/tutorials/wiki/src/views/development.ini b/docs/tutorials/wiki/src/views/development.ini
index d09da86eb..a102b721b 100644
--- a/docs/tutorials/wiki/src/views/development.ini
+++ b/docs/tutorials/wiki/src/views/development.ini
@@ -3,7 +3,7 @@ use = egg:tutorial
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
-debug_matched = false
+debug_routematch = false
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [pipeline:main]
diff --git a/docs/tutorials/wiki2/src/authorization/development.ini b/docs/tutorials/wiki2/src/authorization/development.ini
index 10595b4f5..b0cfd12a7 100644
--- a/docs/tutorials/wiki2/src/authorization/development.ini
+++ b/docs/tutorials/wiki2/src/authorization/development.ini
@@ -3,7 +3,7 @@ use = egg:tutorial
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
-debug_matched = false
+debug_routematch = false
 debug_templates = true
 default_locale_name = en
 sqlalchemy.url = sqlite:///%(here)s/tutorial.db
diff --git a/docs/tutorials/wiki2/src/basiclayout/development.ini b/docs/tutorials/wiki2/src/basiclayout/development.ini
index 10595b4f5..b0cfd12a7 100644
--- a/docs/tutorials/wiki2/src/basiclayout/development.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/development.ini
@@ -3,7 +3,7 @@ use = egg:tutorial
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
-debug_matched = false
+debug_routematch = false
 debug_templates = true
 default_locale_name = en
 sqlalchemy.url = sqlite:///%(here)s/tutorial.db
diff --git a/docs/tutorials/wiki2/src/models/development.ini b/docs/tutorials/wiki2/src/models/development.ini
index 10595b4f5..b0cfd12a7 100644
--- a/docs/tutorials/wiki2/src/models/development.ini
+++ b/docs/tutorials/wiki2/src/models/development.ini
@@ -3,7 +3,7 @@ use = egg:tutorial
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
-debug_matched = false
+debug_routematch = false
 debug_templates = true
 default_locale_name = en
 sqlalchemy.url = sqlite:///%(here)s/tutorial.db
diff --git a/docs/tutorials/wiki2/src/views/development.ini b/docs/tutorials/wiki2/src/views/development.ini
index 10595b4f5..b0cfd12a7 100644
--- a/docs/tutorials/wiki2/src/views/development.ini
+++ b/docs/tutorials/wiki2/src/views/development.ini
@@ -3,7 +3,7 @@ use = egg:tutorial
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
-debug_matched = false
+debug_routematch = false
 debug_templates = true
 default_locale_name = en
 sqlalchemy.url = sqlite:///%(here)s/tutorial.db