From a1e1a925e72ddfc7961dba2f2c8c0cc077e2137d Mon Sep 17 00:00:00 2001 From: Kurt Griffiths Date: Tue, 3 Feb 2015 22:38:12 -0600 Subject: [PATCH] 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 | 12 +++++------- doc/api/middleware.rst | 23 ++++++++++++++--------- doc/conf.py | 8 ++++---- falcon/api.py | 6 +++--- 4 files changed, 26 insertions(+), 23 deletions(-) diff --git a/doc/api/hooks.rst b/doc/api/hooks.rst index 2c45fbd..16284c6 100644 --- a/doc/api/hooks.rst +++ b/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 ` reference and the -:ref:`Quickstart ` example code. +Falcon :ref:`middleware components ` can also be used to insert +logic before and after requests. However, unlike hooks, +:ref:`middleware components ` are triggered **globally** for all +requests. .. automodule:: falcon :members: before, after diff --git a/doc/api/middleware.rst b/doc/api/middleware.rst index f9ef698..abdc64c 100644 --- a/doc/api/middleware.rst +++ b/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 ` 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 `. -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. diff --git a/doc/conf.py b/doc/conf.py index 6e175aa..a16e093 100644 --- a/doc/conf.py +++ b/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'), ] diff --git a/falcon/api.py b/falcon/api.py index 98a1300..627149d 100644 --- a/falcon/api.py +++ b/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):