API docs audit.

9 files changed, 127 insertions, 154 deletions

diff --git a/docs/api/chameleon_text.rst b/docs/api/chameleon_text.rst
new file mode 100644
index 000000000..f56caeda9
--- /dev/null
+++ b/docs/api/chameleon_text.rst
@@ -0,0 +1,30 @@
+.. _chameleon_text_module:
+
+:mod:`repoze.bfg.chameleon_text`
+----------------------------------
+
+.. automodule:: repoze.bfg.chameleon_text
+
+  .. autofunction:: get_template
+
+  .. autofunction:: render_template
+
+  .. autofunction:: render_template_to_response
+
+These APIs will will work against template files which contain simple
+``${Genshi}`` - style replacement markers.
+
+The API of :mod:`repoze.bfg.chameleon_text` is identical to that of
+:mod:`repoze.bfg.chameleon_zpt`; only its import location is
+different.  If you need to import an API functions from this module as
+well as the :mod:`repoze.bfg.chameleon_zpt` module within the same
+view file, use the ``as`` feature of the Python import statement,
+e.g.:
+
+.. code-block:: python
+
+  from repoze.chameleon_zpt import render_template as zpt_render
+  from repoze.chameleon_text import render_template as text_render
+
+
+
diff --git a/docs/api/chameleon_zpt.rst b/docs/api/chameleon_zpt.rst
new file mode 100644
index 000000000..cd5f0ac65
--- /dev/null
+++ b/docs/api/chameleon_zpt.rst
@@ -0,0 +1,27 @@
+.. _chameleon_zpt_module:
+
+:mod:`repoze.bfg.chameleon_zpt`
+-------------------------------
+
+.. automodule:: repoze.bfg.chameleon_zpt
+
+  .. autofunction:: get_template
+
+  .. autofunction:: render_template
+
+  .. autofunction:: render_template_to_response
+
+These APIs will work against files which supply template text which
+matches the :term:`ZPT` specification.
+
+The API of :mod:`repoze.bfg.chameleon_zpt` is identical to that of
+:mod:`repoze.bfg.chameleon_text`; only its import location is
+different.  If you need to import an API functions from this module as
+well as the :mod:`repoze.bfg.chameleon_text` module within the same
+view file, use the ``as`` feature of the Python import statement,
+e.g.:
+
+.. code-block:: python
+
+  from repoze.chameleon_zpt import render_template as zpt_render
+  from repoze.chameleon_text import render_template as text_render
diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst
deleted file mode 100644
index e174966a4..000000000
--- a/docs/api/interfaces.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-.. _interfaces_module:
-
-:mod:`repoze.bfg.interfaces`
-============================
-
-Request-related interfaces
----------------------------
-
-.. automodule:: repoze.bfg.interfaces
-
-  .. autoclass:: IRequest
-
-  .. autoclass:: IGETRequest
-
-  .. autoclass:: IPOSTRequest
-
-  .. autoclass:: IPUTRequest
-
-  .. autoclass:: IDELETERequest
-
-  .. autoclass:: IHEADRequest
-
diff --git a/docs/api/router.rst b/docs/api/router.rst
index 84d51f73a..11e5b6b35 100644
--- a/docs/api/router.rst
+++ b/docs/api/router.rst
@@ -5,6 +5,4 @@
 
 .. automodule:: repoze.bfg.router
 
-.. autoclass:: Router
-
-.. autofunction:: repoze.bfg.router.make_app
+.. autofunction:: repoze.bfg.router.make_app(root_factory, package=None, filename='configure.zcml')
diff --git a/docs/api/template.rst b/docs/api/template.rst
deleted file mode 100644
index 763dc9dfe..000000000
--- a/docs/api/template.rst
+++ /dev/null
@@ -1,57 +0,0 @@
-.. _template_module:
-
-:mod:`repoze.bfg` Built-in Templating Facilties
-===============================================
-
-Two templating facilities are provided by :mod:`repoze.bfg` "out of
-the box": :term:`ZPT` -style and text templating.
-
-ZPT-style and text templates are in :mod:`repoze.bfg` are supported by
-the :term:`Chameleon` (nee :term:`z3c.pt`) templating engine, which
-contains an alternate implementation of the ZPT language
-specification.
-
-Below is API documentation for each of those facilities.  Each
-facility is similar to the other, but to use a particular facility,
-you must import the API function from a specific module.  For
-instance, to render a ZPT-style template to a response, you would
-import the ``render_template_to_response`` function from
-``repoze.bfg.chameleon_zpt`` while you would import
-``render_template_to_response`` from ``repoze.bfg.chameleon_text`` in
-order to render a text-style template to a response.  While these
-functions have the same name, each will only operate on template files
-that match the style in which the template file itself is written.  If
-you need to import API functions from two templating facilities within
-the same module, use the ``as`` feature of the Python import
-statement, e.g.:
-
-.. code-block:: python
-
-  from repoze.chameleon_zpt import render_template as zpt_render
-  from repoze.chameleon_text import render_template as text_render
-
-:mod:`repoze.bfg.chameleon_zpt`
--------------------------------
-
-.. automodule:: repoze.bfg.chameleon_zpt
-
-  .. autofunction:: get_template
-
-  .. autofunction:: render_template
-
-  .. autofunction:: render_template_to_response
-
-.. note:: For backwards compatibility purposes, these functions may
-          also be imported from ``repoze.bfg.template``.
-
-:mod:`repoze.bfg.chameleon_text`
-----------------------------------
-
-.. automodule:: repoze.bfg.chameleon_text
-
-  .. autofunction:: get_template
-
-  .. autofunction:: render_template
-
-  .. autofunction:: render_template_to_response
-
diff --git a/docs/index.rst b/docs/index.rst
index 4669fc4f8..4f90a5ec8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -54,15 +54,15 @@ Per-module :mod:`repoze.bfg` API documentation.
 .. toctree::
    :maxdepth: 2
 
+   api/chameleon_text
+   api/chameleon_zpt
    api/events
-   api/interfaces
    api/location
    api/paster
    api/router
    api/scripting
    api/security
    api/settings
-   api/template
    api/testing
    api/traversal
    api/url
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index ca3ecf3d6..544c80744 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -7,9 +7,9 @@ An *event* is an object broadcast by the :mod:`repoze.bfg` framework
 at particularly interesting points during the lifetime of an
 application.  You don't need to use, know about, or care about events
 in order to create most :mod:`repoze.bfg` applications, but they can
-be useful when you want to do slightly advanced operations, such as
-"skinning" a site slightly differently based on, for example, the
-hostname used to reach the site.
+be useful when you want to perform slightly advanced operations.  For
+example, subscribing to an event can allow you to "skin" a site
+slightly differently based on the hostname used to reach the site.
 
 Events in :mod:`repoze.bfg` are always broadcast by the framework.
 However, they only become useful when you register a *subscriber*.  A
@@ -43,9 +43,10 @@ lives in a ``subscribers.py`` module within your application:
 The above example means "every time the :mod:`repoze.bfg` framework
 emits an event object that supplies an ``INewRequest`` interface, call
 the ``mysubscriber`` function with the event object.  As you can see,
-subscriptions are made to *interfaces*.  The event object sent to a
-subscriber will always have an interface.  You can use the interface
-itself to determine what attributes of the event are available.
+a subscription is made in terms of an :term:`interface`.  The event
+object sent to a subscriber will always have possess an interface.
+The interface itself provides documentation of what attributes of the
+event are available.
 
 For example, if you create event listener functions in a
 ``subscribers.py`` file in your application like so:
@@ -78,15 +79,16 @@ file:
 
 This causes the functions as to be registered as event subscribers
 within the :term:`application registry` .  Under this configuration,
-when the application is run, every new request and every response will
-be printed to the console.  We know that ``INewRequest`` events have a
-``request`` attribute, which is a :term:`WebOb` request, because the
-interface defined at ``repoze.bfg.interfaces.INewRequest`` says it
-must.  Likewise, we know that ``INewResponse`` events have a
-``response`` attribute, which is a response object constructed by your
-application, because the interface defined at
-``repoze.bfg.interfaces.INewResponse`` says it must.  These particular
-interfaces, along with others, are documented in the
+when the application is run, each time a new request or response is
+detected, a message will be printed to the console.
+
+We know that ``INewRequest`` events have a ``request`` attribute,
+which is a :term:`WebOb` request, because the interface defined at
+``repoze.bfg.interfaces.INewRequest`` says it must.  Likewise, we know
+that ``INewResponse`` events have a ``response`` attribute, which is a
+response object constructed by your application, because the interface
+defined at ``repoze.bfg.interfaces.INewResponse`` says it must.  These
+particular interfaces, along with others, are documented in the
 :ref:`events_module` API chapter.
 
 .. note::
@@ -95,11 +97,12 @@ interfaces, along with others, are documented in the
    components.  The ``INewResponse`` event exists purely for symmetry
    with ``INewRequest``, really.
 
-The *subscriber* ZCML element takes two values: ``for``, which is the
-interface the subscriber is registered for (which limits the events
-that the subscriber will receive to those specified by the interface),
-and ``handler`` which is a Python dotted-name path to the subscriber
-function.
+The *subscriber* ZCML element takes two attributes: ``for``, and
+``handler``.  The value of ``for`` is the interface the subscriber is
+registered for.  Registering a subscriber for a specific interface
+limits the event types that the subscriber will receive to those
+specified by the interface. The value of ``handler`` is a Python
+dotted-name path to the subscriber function.
 
 The return value of a subscriber function is ignored.
 
@@ -109,12 +112,12 @@ Using An Event to Vary the Request Type
 ---------------------------------------
 
 The most common usage of the ``INewRequestEvent`` is to attach an
-:term:`interface` to the request to be able to differentiate, for
-example, a request issued by a browser from a request issued by a JSON
-client.  This differentiation makes it possible to register different
-views against different ``request_type`` interfaces; for instance,
-depending on the presence of a request header, you might return JSON
-data.
+:term:`interface` to a request after introspecting the request data in
+some way.  For example, you might want to be able to differentiate a
+request issued by a browser from a request issued by a JSON client.
+This differentiation makes it possible to register different views
+against different ``request_type`` interfaces; for instance, depending
+on the presence of a request header, you might return JSON data.
 
 To do this, you should subscribe an function to the ``INewRequest``
 event type, and you should use the ``zope.interface.alsoProvides`` API
@@ -137,14 +140,14 @@ object provided by the event.  Here's an example.
        if 'application/json' in accept:
            alsoProvides(request, IJSONRequest)
 
-Then in your view registration ZCML, if you subscribe
-``categorize_request`` for the ``repoze.bfg.interfaces.INewRequest``
-type, you can use the ``request_type`` attribute to point at different
-view functions depending upon the interface implemented by the
-request.  For example, if the above subscriber function was
-registered, the three view registrations below could be used to point
-at separate view functions using separate request type interfaces for
-the same model object.
+If you subscribe ``categorize_request`` for the
+``repoze.bfg.interfaces.INewRequest`` type, the ``IJSONRequest``
+interface will be attached to each request object that has ``accept``
+headers which match ``application/json``.
+
+Thereafter, you can use the ``request_type`` attribute of a
+term:`view` ZCML statement or a ``@bfg_view`` decorator to refer to
+this ``IJSONRequest`` interface.  For example:
 
 .. code-block:: xml
    :linenos:
@@ -157,7 +160,6 @@ the same model object.
    <!-- html default view -->
    <view
       for=".models.MyModel"
-      request_type="repoze.bfg.interfaces.IRequest"
       view=".views.html_view"/>
 
    <!-- JSON default view -->
@@ -167,30 +169,33 @@ the same model object.
       view=".views.json_view"/>
 
 The interface ``repoze.bfg.interfaces.IRequest`` is automatically
-implemented by every :mod:`repoze.bfg` request, so all requests will
-implement that type, and views registered against models which do not
-supply a ``request_type`` will be considered to be registered for this
-``IRequest`` as a default.
+implemented by every :mod:`repoze.bfg` request.  Views which do not
+supply a ``request_type`` attribute will be considered to be
+registered for ``repoze.bfg.interfaces.IRequest`` as a default.  But
+in the example above, ``.views.json_view`` will be called when a
+request supplies our ``IJSONRequest`` interface, because it is a more
+specific interface.
 
 Of course, you are not limited to using the ``Accept`` header to
-determine which interfaces to attach to a request.  For example, you
-might also choose to use hostname
-(e.g. ``request.environ.get('HTTP_HOST',
+determine which interface to attach to a request within an event
+subscriber.  For example, you might also choose to introspect the
+hostname (e.g. ``request.environ.get('HTTP_HOST',
 request.environ['SERVER_NAME'])``) in order to "skin" your application
 differently based on whether the user should see the "management"
 (e.g. "manage.myapp.com") presentation of the application or the
-"retail" presentation (e.g. "www.myapp.com").  By attaching to the
-request an arbitrary interface after examining the hostname or any
-other information available in the request within an ``INewRequest``
-event subscriber, you can control view lookup precisely.  For example,
-if you wanted to have two slightly different views for requests to two
-different hostnames, you might register one view with a
-``request_type`` of ``.interfaces.IHostnameFoo`` and another with a
-``request_type`` of ``.interfaces.IHostnameBar`` and then arrange for
-an event subscriber to attach ``.interfaces.IHostnameFoo`` to the
-request when the HTTP_HOST is ``foo`` and ``.interfaces.IHostnameBar``
-to the request when the HTTP_HOST is ``bar``.  The appropriate view
-will be called.
+"retail" presentation (e.g. "www.myapp.com").
+
+By attaching to the request an arbitrary interface after examining the
+hostname or any other information available in the request within an
+``INewRequest`` event subscriber, you can control view lookup
+precisely.  For example, if you wanted to have two slightly different
+views for requests to two different hostnames, you might register one
+view with a ``request_type`` of ``.interfaces.IHostnameFoo`` and
+another with a ``request_type`` of ``.interfaces.IHostnameBar`` and
+then arrange for an event subscriber to attach
+``.interfaces.IHostnameFoo`` to the request when the HTTP_HOST is
+``foo`` and ``.interfaces.IHostnameBar`` to the request when the
+HTTP_HOST is ``bar``.  The appropriate view will be called.
 
 You can also form an inheritance hierarchy out of ``request_type``
 interfaces.  When :mod:`repoze.bfg` looks up a view, the most specific
@@ -198,12 +203,3 @@ view for the interface(s) found on the request based on standard
 Python method resolution order through the interface class hierarchy
 will be called.
 
-:mod:`repoze.bfg` also makes available as interfaces standard request
-type interfaces matching HTTP verbs.  When these are specified as a
-``request_type`` for a view, the view will be called only when the
-request has an HTTP verb (aka HTTP method) matching the request type.
-For example, using the string ``repoze.bfg.interfaces.IPOST`` or the
-imported interface definition itself matching that Python dotted name
-as the request_type argument to a view definition is equivalent to
-using the string ``POST``.  See :ref:`interfaces_module` for more
-information about available request types.
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 4b0de4a0e..c50cc9e25 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -615,11 +615,12 @@ in the model, and the HTML given back to the browser.
   This example uses ``render_template_to_response`` which is a
   shortcut function.  If you want more control over the response, use
   the ``render_template`` function, also present in
-  :ref:`template_module`.  You may then create your own :term:`WebOb`
-  Response object, using the result of ``render_template`` as the
-  response's body.  There is also a ``get_template`` API in the same
-  module, which you can use to retrieve the template object without
-  rendering it at all, for additional control.
+  :ref:`chameleon_zpt_module`.  You may then create your own
+  :term:`WebOb` Response object, using the result of
+  ``render_template`` as the response's body.  There is also a
+  ``get_template`` API in the same module, which you can use to
+  retrieve the template object without rendering it at all, for
+  additional control.
 
 .. note::
 
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 316bd3016..a2117622f 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -56,7 +56,7 @@ has a *status code* of ``200 OK`` and a *content-type* of
 ``text-html``.  If you need more control over the status code and
 content-type, either set attributes on the response that this function
 returns or use the ``render_template`` function instead (see
-:ref:`template_module` for the details), which also renders a ZPT
+:ref:`chameleon_zpt_module` for the details), which also renders a ZPT
 template but returns a string instead of a Response.  You can use the
 string manually as a response body.  Here's an example of using
 ``render_template``:
@@ -201,7 +201,7 @@ which renders this template:
 
 The Chameleon text rendering API is a wholesale mirror of the
 Chameleon text ZPT rendering API, it's just imported from another
-place; see :ref:`template_module` for the API description.
+place; see :ref:`chameleon_text_module` for the API description.
 
 Side Effects of Rendering a Chameleon Template
 ----------------------------------------------