code refactoring for showing route->view relationship more correctly; tests and docs for pull request

2 files changed, 101 insertions, 0 deletions

diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 1024dd188..a180003d0 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -1121,6 +1121,10 @@ a developer to understand either of them in detail.  It also means that we
 can allow a developer to combine :term:`URL dispatch` and :term:`traversal`
 in various exceptional cases as documented in :ref:`hybrid_chapter`.
 
+To gain a better understanding of how routes and views are associated in a
+real application, you can use the ``paster pviews`` command, as documented
+in :ref:`displaying_matching_views`.
+
 References
 ----------
 
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 743cc016e..d99e5bed5 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -732,3 +732,100 @@ found will be printed to ``stderr``, and the browser representation of the
 error will include the same information.  See :ref:`environment_chapter` for
 more information about how, and where to set these values.
 
+.. index::
+   pair: matching views; printing
+   single: paster pviews
+
+.. _displaying_matching_views:
+
+Displaying Matching Views for a Given URL
+-----------------------------------------
+
+For a big application with several views, it can be hard to keep the view
+configuration details in your head, even if you defined all the views
+yourself. You can use the ``paster pviews`` command in a terminal window to
+print a summary of matching routes and views for a given URL in your
+application. The ``paster pviews`` command accepts three arguments. The
+first argument to ``pviews`` is the path to your application's ``.ini`` file.
+The second is the ``app`` section name inside the ``.ini`` file which points
+to your application. The third is the URL to test for matching views.
+
+Here is an example for a simple view configuration using :term:`traversal`:
+
+.. code-block:: text
+   :linenos:
+
+   $ ../bin/paster pviews development.ini tutorial /FrontPage
+
+   URL = /FrontPage
+
+       context: <tutorial.models.Page object at 0xa12536c>
+       view name: 
+
+       View:
+       -----
+       tutorial.views.view_page
+       required permission = view
+
+The output always has the requested URL at the top and below that all the
+views that matched with their view configuration details. In this example
+only one view matches, so there is just a single *View* section. For each
+matching view, the full code path to the associated view callable is shown,
+along with any permissions and predicates that are part of that view
+configuration.
+
+A more complex configuration might generate something like this:
+
+.. code-block:: text
+   :linenos:
+
+   $ ../bin/paster pviews development.ini shootout /about
+
+   URL = /about
+
+       context: <shootout.models.RootFactory object at 0xa56668c>
+       view name: about
+
+       Route:
+       ------
+       route name: about
+       route pattern: /about
+       route path: /about
+       subpath: 
+       route predicates (request method = GET)
+
+           View:
+           -----
+           shootout.views.about_view
+           required permission = view
+           view predicates (request_param testing, header X/header)
+
+       Route:
+       ------
+       route name: about_post
+       route pattern: /about
+       route path: /about
+       subpath: 
+       route predicates (request method = POST)
+
+           View:
+           -----
+           shootout.views.about_view_post
+           required permission = view
+           view predicates (request_param test)
+
+           View:
+           -----
+           shootout.views.about_view_post2
+           required permission = view
+           view predicates (request_param test2)
+
+In this case, we are dealing with a :term:`URL dispatch` application. This
+specific URL has two matching routes. The matching route information is
+displayed first, followed by any views that are associated with that route.
+As you can see from the second matching route output, a route can be
+associated with more than one view.
+
+For a URL that doesn't match any views, ``paster pviews`` will simply print
+out a *Not found* message.
+