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

7 files changed, 107 insertions, 5 deletions

diff --git a/docs/index.rst b/docs/index.rst
index be03448c9..cb632d5b2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -83,6 +83,7 @@ Narrative documentation in chapter form explaining how to use
    narr/vhosting
    narr/testing
    narr/resources
+   narr/hellotraversal
    narr/muchadoabouttraversal
    narr/traversal
    narr/security
@@ -152,7 +153,8 @@ application.  Check this application out via:
 
 `virginia <https://github.com/Pylons/virginia>`_ is a very simple dynamic
 file rendering application.  It is willing to render structured text
-documents, HTML documents, and images from a filesystem directory.  An
+documents, HTML documents, and images from a filesystem directory.
+It's also a good example of :term:`traversal`. An
 earlier version of this application runs the `repoze.org
 <http://repoze.org>`_ website.  Check this application out via:
 
diff --git a/docs/narr/hellotraversal.py b/docs/narr/hellotraversal.py
new file mode 100644
index 000000000..1ef7525e6
--- /dev/null
+++ b/docs/narr/hellotraversal.py
@@ -0,0 +1,22 @@
+from wsgiref.simple_server import make_server
+from pyramid.config import Configurator
+from pyramid.response import Response
+
+class Resource(dict):
+    pass
+
+def get_root(request):
+    return Resource({'a': Resource({'b': Resource({'c': Resource()})})})
+
+def hello_world_of_resources(context, request):
+    output = "Here's a resource and its children: %s" % context
+    return Response(output)
+
+if __name__ == '__main__':
+    config = Configurator(root_factory=get_root)
+    config.add_view(hello_world_of_resources, context=Resource)
+    app = config.make_wsgi_app()
+    server = make_server('0.0.0.0', 8080, app)
+    server.serve_forever()
+
+
diff --git a/docs/narr/hellotraversal.rst b/docs/narr/hellotraversal.rst
new file mode 100644
index 000000000..142c24f54
--- /dev/null
+++ b/docs/narr/hellotraversal.rst
@@ -0,0 +1,69 @@
+.. _hello_traversal_chapter:
+
+Hello Traversal World
+======================
+
+
+.. index::
+   single: traversal quick example
+
+Traversal is an alternative to URL dispatch which allows Pyramid
+applications to map URLs to code.
+
+If code speaks louder than words, maybe this will help. Here is a
+single-file Pyramid application that uses traversal:
+
+.. literalinclude:: hellotraversal.py
+   :linenos:
+
+You may notice that this application is intentionally very similar to
+the "hello world" app from :doc:`firstapp`.
+
+On lines 5-6, we create a trivial :term:`resource` class that's just a
+dictionary subclass.
+
+On lines 8-9, we hard-code a :term:`resource tree` in our :term:`root
+factory` function.
+
+On lines 11-13 we define a single :term:`view callable` that can
+display a single instance of our Resource class, passed as the
+``context`` argument.
+
+The rest of the file sets up and serves our pyramid WSGI app.  Line 18
+is where our view gets configured for use whenever the traversal ends
+with an instance of our Resource class.
+
+Interestingly, there are no URLs explicitly configured in this
+application. Instead, the URL space is defined entirely by the keys in
+the resource tree.
+
+Example requests
+----------------
+
+If this example is running on http://localhost:8080, and the user
+browses to http://localhost:8080/a/b, Pyramid will call
+``get_root(request)`` to get the root resource, then traverse the tree
+from there by key; starting from the root, it will find the child with
+key ``"a"``, then its child with key ``"b"``; then use that as the
+``context`` argument for calling ``hello_world_of_resources``.
+
+Or, if the user browses to http://localhost:8080/ , Pyramid will
+stop at the root - the outermost Resource instance, in this case - and
+use that as the ``context`` argument to the same view.
+
+Or, if the user browses to a key that doesn't exist in this resource
+tree, like http://localhost:8080/xyz or
+http://localhost:8080/a/b/c/d, the traversal will end by raising a
+KeyError, and Pyramid will turn that into a 404 HTTP response.
+
+A more complicated application could have many types of resources,
+with different view callables defined for each type, and even multiple
+views for each type.
+
+See Also
+---------
+
+Full technical details may be found in :doc:`traversal`.
+
+For more about *why* you might use traversal, see :doc:`muchadoabouttraversal`.
+
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 7c6ad00f3..92955aafd 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -597,7 +597,7 @@ content management systems and document management systems.  Traversal also lend
 systems that require very granular security ("Bob can edit *this* document"
 as opposed to "Bob can edit documents").
 
-Example: :ref:`much_ado_about_traversal_chapter`.
+Example: :ref:`hello_traversal_chapter` and :ref:`much_ado_about_traversal_chapter`.
 
 Tweens
 ~~~~~~
diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst
index 4a249ed0d..40d498391 100644
--- a/docs/narr/muchadoabouttraversal.rst
+++ b/docs/narr/muchadoabouttraversal.rst
@@ -4,6 +4,8 @@
 Much Ado About Traversal
 ========================
 
+(Or, why you should care about it)
+
 .. note::
 
    This chapter was adapted, with permission, from a blog post by `Rob
@@ -15,7 +17,7 @@ Traversal is an alternative to :term:`URL dispatch` which allows
 
 .. note::
    
-   Ex-Zope users whom are already familiar with traversal and view lookup
+   Ex-Zope users who are already familiar with traversal and view lookup
    conceptually may want to skip directly to the :ref:`traversal_chapter`
    chapter, which discusses technical details.  This chapter is mostly aimed
    at people who have previous :term:`Pylons` experience or experience in
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index ef875c8f0..8c5d950c1 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -3,6 +3,13 @@
 Traversal
 =========
 
+This chapter explains the technical details of how traversal works in
+Pyramid.
+
+For a quick example, see :doc:`hellotraversal`.
+
+For more about *why* you might use traversal, see :doc:`muchadoabouttraversal`.
+
 A :term:`traversal` uses the URL (Universal Resource Locator) to find a
 :term:`resource` located in a :term:`resource tree`, which is a set of
 nested dictionary-like objects.  Traversal is done by using each segment
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index d1188eaec..763c0e131 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -280,8 +280,8 @@ configured view.
   *This is an advanced feature, not often used by "civilians"*.
 
 ``request_method``
-  This value can be one of the strings ``GET``, ``POST``, ``PUT``,
-  ``DELETE``, or ``HEAD`` representing an HTTP ``REQUEST_METHOD``.  A view
+  This value can be a string (typically ``"GET"``, ``"POST"``, ``"PUT"``,
+  ``"DELETE"``, or ``"HEAD"``) representing an HTTP ``REQUEST_METHOD``.  A view
   declaration with this argument ensures that the view will only be called
   when the request's ``method`` attribute (aka the ``REQUEST_METHOD`` of the
   WSGI environment) string matches the supplied value.