6 files changed, 136 insertions, 35 deletions
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index b6e3dd163..a2143b3c5 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -145,7 +145,7 @@ the view which generates it can be overridden as necessary.
 
 The :term:`forbidden view` callable is a view callable like any other.  The
 :term:`view configuration` which causes it to be a "forbidden" view consists
-of using the meth:`pyramid.config.Configurator.add_forbidden_view` API or the
+of using the :meth:`pyramid.config.Configurator.add_forbidden_view` API or the
 :class:`pyramid.view.forbidden_view_config` decorator.
 
 For example, you can add a forbidden view by using the
@@ -171,7 +171,7 @@ as a forbidden view:
 
    from pyramid.view import forbidden_view_config
 
-   forbidden_view_config()
+   @forbidden_view_config()
    def forbidden(request):
        return Response('forbidden')
 
@@ -625,7 +625,7 @@ converts the arbitrary return value into something that implements
 :class:`~pyramid.interfaces.IResponse`.
 
 For example, if you'd like to allow view callables to return bare string
-objects (without requiring a a :term:`renderer` to convert a string to a
+objects (without requiring a :term:`renderer` to convert a string to a
 response object), you can register an adapter which converts the string to a
 Response:
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 57073900f..d18d93605 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -447,7 +447,7 @@ first column instead, for example like this:
    pyramid.includes =
        #pyramid_debugtoolbar
 
-When you attempt to restart the application with a section like the abvoe
+When you attempt to restart the application with a section like the above
 you'll receive an error that ends something like this, and the application
 will not start:
 
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 76035cbdf..02063a112 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -177,8 +177,10 @@ using the API of the ``request.response`` attribute.  See
 .. index::
    pair: renderer; JSON
 
-``json``: JSON Renderer
-~~~~~~~~~~~~~~~~~~~~~~~
+.. _json_renderer:
+
+JSON Renderer
+~~~~~~~~~~~~~
 
 The ``json`` renderer renders view callable results to :term:`JSON`.  It
 passes the return value through the ``json.dumps`` standard library function,
@@ -207,7 +209,13 @@ representing the JSON serialization of the return value:
    '{"content": "Hello!"}'
 
 The return value needn't be a dictionary, but the return value must contain
-values serializable by :func:`json.dumps`.
+values serializable by ``json.dumps``.
+
+.. note::
+
+   Extra arguments can be passed to ``json.dumps`` by overriding the default
+   ``json`` renderer. See :class:`pyramid.renderers.JSON` and
+   :ref:`adding_and_overriding_renderers` for more information.
 
 You can configure a view to use the JSON renderer by naming ``json`` as the
 ``renderer`` argument of a view configuration, e.g. by using
@@ -217,22 +225,83 @@ You can configure a view to use the JSON renderer by naming ``json`` as the
    :linenos:
 
    config.add_view('myproject.views.hello_world',
-                    name='hello',
-                    context='myproject.resources.Hello',
-                    renderer='json')
-
+                   name='hello',
+                   context='myproject.resources.Hello',
+                   renderer='json')
 
 Views which use the JSON renderer can vary non-body response attributes by
 using the api of the ``request.response`` attribute.  See
 :ref:`request_response_attr`.
 
+.. _json_serializing_custom_objects:
+
+Serializing Custom Objects
+++++++++++++++++++++++++++
+
+Custom objects can be made easily JSON-serializable in Pyramid by defining a
+``__json__`` method on the object's class. This method should return values
+natively serializable by ``json.dumps`` (such as ints, lists, dictionaries,
+strings, and so forth).
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import view_config
+
+   class MyObject(object):
+       def __init__(self, x):
+           self.x = x
+
+       def __json__(self):
+           return {'x':self.x}
+
+   @view_config(renderer='json')
+   def objects(request):
+       return [MyObject(1), MyObject(2)]
+
+   # the JSON value returned by ``objects`` will be:
+   #    [{"x": 1}, {"x": 2}]
+
+If you aren't the author of the objects being serialized, it won't be
+possible (or at least not reasonable) to add a custom ``__json__`` method to
+to their classes in order to influence serialization.  If the object passed
+to the renderer is not a serializable type, and has no ``__json__`` method,
+usually a :exc:`TypeError` will be raised during serialization.  You can
+change this behavior by creating a JSON renderer with a "default" function
+which tries to "sniff" at the object, and returns a valid serialization (a
+string) or raises a TypeError if it can't determine what to do with the
+object.  A short example follows:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.renderers import JSON
+
+   def default(obj):
+       if isinstance(obj, datetime.datetime):
+           return obj.isoformat()
+       raise TypeError('%r is not serializable % (obj,))
+
+   json_renderer = JSON(default=default)
+
+   # then during configuration ....
+   config = Configurator()
+   config.add_renderer('json', json_renderer)
+
+See :class:`pyramid.renderers.JSON` and
+:ref:`adding_and_overriding_renderers` for more information.
+
+.. note::
+
+   Serializing custom objects is a feature new in Pyramid 1.4.
+
 .. index::
    pair: renderer; JSONP
 
 .. _jsonp_renderer:
 
 JSONP Renderer
---------------
+~~~~~~~~~~~~~~
 
 .. note:: This feature is new in Pyramid 1.1.
 
@@ -297,6 +366,10 @@ The string ``callback=?`` above in the the ``url`` param to the JQuery
 a JSONP request; the ``callback`` parameter will be automatically filled
 in for you and used.
 
+The same custom-object serialization scheme defined used for a "normal" JSON
+renderer in :ref:`json_serializing_custom_objects` can be used when passing
+values to a JSONP renderer too.
+
 .. index::
    pair: renderer; chameleon
 
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 8e28835af..f5c741f52 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -42,8 +42,8 @@ Here's a high-level time-ordered overview of what happens when you press
    ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file.  This
    section represents the configuration of a :term:`WSGI` application that
    will be served.  If you're using a simple application (e.g.
-   ``[app:main]``), the application :term:`entry point` or :term:`dotted
-   Python name` will be named on the ``use=`` line within the section's
+   ``[app:main]``), the application's ``paste.app_factory`` :term:`entry
+   point` will be named on the ``use=`` line within the section's
    configuration.  If, instead of a simple application, you're using a WSGI
    :term:`pipeline` (e.g. a ``[pipeline:main]`` section), the application
    named on the "last" element will refer to your :app:`Pyramid` application.
@@ -59,11 +59,11 @@ Here's a high-level time-ordered overview of what happens when you press
    system for this application.  See :ref:`logging_config` for more
    information.
 
-#. The application's *constructor* named by the entry point reference or
-   dotted Python name on the ``use=`` line of the section representing your
-   :app:`Pyramid` application is passed the key/value parameters mentioned
-   within the section in which it's defined.  The constructor is meant to
-   return a :term:`router` instance, which is a :term:`WSGI` application.
+#. The application's *constructor* named by the entry point reference on the
+   ``use=`` line of the section representing your :app:`Pyramid` application
+   is passed the key/value parameters mentioned within the section in which
+   it's defined.  The constructor is meant to return a :term:`router`
+   instance, which is a :term:`WSGI` application.
 
    For :app:`Pyramid` applications, the constructor will be a function named
    ``main`` in the ``__init__.py`` file within the :term:`package` in which
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index ed700f7b4..9db0b1c4d 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -253,16 +253,26 @@ System Values Used During Rendering
 
 When a template is rendered using
 :func:`~pyramid.renderers.render_to_response` or
-:func:`~pyramid.renderers.render`, the renderer representing the
-template will be provided with a number of *system* values.  These
-values are provided in a dictionary to the renderer and include:
-
-``context``
-  The current :app:`Pyramid` context if ``request`` was provided as
-  a keyword argument, or ``None``.
+:func:`~pyramid.renderers.render`, or a ``renderer=`` argument to view
+configuration (see :ref:`templates_used_as_renderers`), the renderer
+representing the template will be provided with a number of *system* values.
+These values are provided to the template:
 
 ``request``
-  The request provided as a keyword argument.
+  The value provided as the ``request`` keyword argument to
+  ``render_to_response`` or ``render`` *or* the request object passed to the
+  view when the ``renderer=`` argument to view configuration is being used to
+  render the template.
+
+``req``
+  An alias for ``request``.
+
+``context``
+  The current :app:`Pyramid` :term:`context` if ``request`` was provided as a
+  keyword argument to ``render_to_response`` or ``render``, or ``None`` if
+  the ``request`` keyword argument was not provided.  This value will always
+  be provided if the template is rendered as the result of a ``renderer=``
+  argument to view configuration being used.
 
 ``renderer_name``
   The renderer name used to perform the rendering,
@@ -270,17 +280,24 @@ values are provided in a dictionary to the renderer and include:
 
 ``renderer_info`` 
   An object implementing the :class:`pyramid.interfaces.IRendererInfo`
-  interface.  Basically, an object with the following attributes:
-  ``name``, ``package`` and ``type``.
+  interface.  Basically, an object with the following attributes: ``name``,
+  ``package`` and ``type``.
+
+``view``
+  The view callable object that was used to render this template.  If the
+  view callable is a method of a class-based view, this will be an instance
+  of the class that the method was defined on.  If the view callable is a
+  function or instance, it will be that function or instance.  Note that this
+  value will only be automatically present when a template is rendered as a
+  result of a ``renderer=`` argument; it will be ``None`` when the
+  ``render_to_response`` or ``render`` APIs are used.
 
-You can define more values which will be passed to every template
-executed as a result of rendering by defining :term:`renderer
-globals`.
+You can define more values which will be passed to every template executed as
+a result of rendering by defining :term:`renderer globals`.
 
 What any particular renderer does with these system values is up to the
-renderer itself, but most template renderers, including Chameleon and
-Mako renderers, make these names available as top-level template
-variables.
+renderer itself, but most template renderers, including Chameleon and Mako
+renderers, make these names available as top-level template variables.
 
 .. index::
    pair: renderer; templates
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index c3bbbd50e..f6ee9a8d5 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -572,6 +572,17 @@ No matter which view calling convention is used, the view code always has
 access to the context via ``request.context``.
 
 .. index::
+   single: Passing in configuration variables
+
+.. _passing_in_config_variables:
+
+Passing Configuration Variables to a View
+-----------------------------------------
+
+For information on passing a variable from the configuration .ini files to a
+view, see :ref:`deployment_settings`.
+
+.. index::
    single: Pylons-style controller dispatch
 
 Pylons-1.0-Style "Controller" Dispatch