add tweens module, add docs for ptweens and tweens to hooks

1 files changed, 73 insertions, 2 deletions

diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 509af7dd3..6f969196f 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -297,8 +297,79 @@ application, nothing will be printed to the console when ``paster proutes``
 is executed.
 
 .. index::
-   single: scripting
-   single: bootstrap
+   pair: tweens; printing
+   single: paster ptweens
+   single: ptweens
+
+.. _displaying_tweens:
+
+Displaying "Tweens"
+-------------------
+
+A user can get a representation of both the implicit :term:`tween` ordering
+(the ordering specified by calls to
+:meth:`pyramid.config.Configurator.add_tween`) and the explicit tween
+ordering (specified by the ``pyramid.tweens`` configuration setting)
+orderings using the ``paster ptweens`` command.  Handler factories which are
+functions or classes will show up as a standard Python dotted name in the
+``paster ptweens`` output.  Tween factories which are *instances* will show
+their module and class name; the Python object id of the instance will be
+appended.
+
+For example, here's the ``paster pwteens`` command run against a system
+configured without any explicit tweens:
+
+.. code-block:: text
+   :linenos:
+
+   [chrism@thinko starter]$ ../bin/paster ptweens development.ini 
+   "pyramid.tweens" config value NOT set (implicitly ordered tweens used)
+
+   Position Name                          
+   -------- ----                          
+   0        pyramid.router.excview_tween_factory
+
+Here's the ``paster pwteens`` command run against a system configured *with*
+explicit tweens defined in its ``development.ini`` file:
+
+.. code-block:: text
+   :linenos:
+
+   [chrism@thinko starter]$ ../bin/paster ptweens development.ini 
+   "pyramid.tweens" config value set (explicitly ordered tweens used)
+
+   Explicit Tween Chain (used)
+
+   Position Name                          
+   -------- ----                          
+   0        pyramid.tweens.excview_tween_factory
+   1        starter.tween_factory1        
+   2        starter.tween_factory2        
+
+   Implicit Tween Chain (not used)
+
+   Position Name                          
+   -------- ----                          
+   0        pyramid.tweens.excview_tween_factory
+
+Here's the application configuration section of the ``development.ini`` used
+by the above ``paster ptweens`` command which reprorts that the explicit
+tween chain is used:
+
+.. code-block:: text
+   :linenos:
+
+   [app:starter]
+   use = egg:starter
+   pyramid.reload_templates = true
+   pyramid.debug_authorization = false
+   pyramid.debug_notfound = false
+   pyramid.debug_routematch = false
+   pyramid.debug_templates = true
+   pyramid.default_locale_name = en
+   pyramid.tweens = pyramid.tweens.excview_tween_factory
+                    starter.tween_factory1
+                    starter.tween_factory2
 
 .. _writing_a_script: