doc: Minor tweaks to middleware docs and RTD template

Misc. tweaks to the docs in preparation for 0.2.0rc1, including:
    * Edit middleware docs for clarity and correctness
    * Use Warning or Tip headers instead of Note, where appropriate
    * Update sphinx config regarding author and copyright

doc/api/hooks.rst

@@ -3,7 +3,7 @@
 Hooks
 =====
 
-Falcon supports both **before** and **after** hooks. You install a hook simply by
+Falcon supports *before* and *after* hooks. You install a hook simply by
 applying one of the decorators below, either to an individual responder or
 to an entire resource.
 
@@ -39,12 +39,10 @@ decorate the resource class:
         def on_get(self, req, resp):
             pass
 
-Falcon middleware components can also be used to insert logic before and
-after requests. Unlike hooks, however, middleware components are
-triggered **globally** for all requests. This feature is
-documented in the
-:ref:`API class <api>` reference and the
-:ref:`Quickstart <quickstart-more-features>` example code.
+Falcon :ref:`middleware components <middleware>` can also be used to insert
+logic before and after requests. However, unlike hooks,
+:ref:`middleware components <middleware>` are triggered **globally** for all
+requests.
 
 .. automodule:: falcon
     :members: before, after

doc/api/middleware.rst

@@ -1,14 +1,18 @@
 .. _middleware:
 
-Middleware
-==========
+Middleware Components
+=====================
 
-Middleware components execute both before and after the framework
-routes the request.  Middleware is registered by passing components
-to the :ref:`API class <api>` initializer.
+Middleware components provide a way to execute logic before the
+framework routes each request, after each request is routed but before
+the target responder is called, or just before the response is returned
+for each request. Components are registered with the `middleware` kwarg when instantiating
+Falcon's :ref:`API class <api>`.
 
-The middleware interface is defined as follows:
+.. Note::
+    Unlike hooks, middleware methods apply globally to the entire API.
 
+Falcon's middleware interface is defined as follows:
 
 .. code:: python
 
@@ -47,9 +51,10 @@ The middleware interface is defined as follows:
                     for the request.
             """
 
-Because middleware can execute before routing has occurred, if a
-component modifies ``req.uri`` in its *process_request* method,
-the framework will use the modified value to route the request.
+.. Tip::
+    Because *process_request* executes before routing has occurred, if a
+    component modifies ``req.uri`` in its *process_request* method,
+    the framework will use the modified value to route the request.
 
 Each component's *process_request*, *process_resource*, and
 *process_response* methods are executed hierarchically, as a stack.

doc/conf.py

@@ -55,7 +55,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Falcon'
-copyright = u'2015, Kurt Griffiths and Rackspace Hosting'
+copyright = u'2015, Rackspace Hosting et al. (as noted in the source code)'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -221,7 +221,7 @@ latex_elements = {
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
   ('index', 'Falcon.tex', u'Falcon Documentation',
-   u'Kurt Griffiths', 'manual'),
+   u'Kurt Griffiths et al.', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -251,7 +251,7 @@ latex_documents = [
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'falcon', u'Falcon Documentation',
-     [u'Kurt Griffiths'], 1)
+     [u'Kurt Griffiths et al.'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -265,7 +265,7 @@ man_pages = [
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'Falcon', u'Falcon Documentation',
-   u'Kurt Griffiths', 'Falcon', 'One line description of project.',
+   u'Kurt Griffiths et al.', 'Falcon', 'One line description of project.',
    'Miscellaneous'),
 ]
 

falcon/api.py

@@ -29,7 +29,7 @@ class API(object):
 
     Each API instance provides a callable WSGI interface and a routing engine.
 
-    Note:
+    Warning:
         Global hooks (configured using the `before` and `after` kwargs) are
         deprecated in favor of middleware, and may be removed in a future
         version of the framework.
@@ -311,7 +311,7 @@ class API(object):
                     Named groups are converted to kwargs and passed to
                     the sink as such.
 
-                Note:
+                Warning:
                     If the prefix overlaps a registered route template,
                     the route will take precedence and mask the sink
                     (see also `add_route`).
@@ -341,7 +341,7 @@ class API(object):
                 ``exception.handle``, where ``exception`` is the error
                 type specified above, and ``handle`` is a static method
                 (i.e., decorated with @staticmethod) that accepts
-                the same params just described. For example:
+                the same params just described. For example::
 
                     class CustomException(CustomBaseException):