add pyramid.tweens configuration value docs

2 files changed, 96 insertions, 1 deletions

diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index cb6bc6a5d..cc858a892 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -283,6 +283,89 @@ Is equivalent to using the following statements in your configuration code:
 
 It is fine to use both or either form.
 
+Explicit Tween Configuration
+----------------------------
+
+This value allows you to perform explicit :term:`tween` ordering in your
+configuration.  Tweens are bits of code used by add-on authors to extend
+Pyramid.  They form a chain, and require ordering.
+
+Ideally, you won't need to use the ``pyramid.tweens`` setting at all.  Tweens
+are generally ordered and included "implicitly" when an add-on package which
+registers a tween is "included".  Packages are included when you name a
+``pyramid.includes`` setting in your configuration or when you call
+:meth:`pyramid.config.Configuration.include`.
+
+Authors of included add-ons provide "implicit" tween configuration ordering
+hints to Pyramid when their packages are included.  However, the implicit
+tween ordering is only best-effort.  Pyramid will attempt to provide an
+implicit order of tweens as best it can using hints provided by add-on
+authors, but because it's only best-effort, if very precise tween ordering is
+required, the only surefire way to get it is to use an explicit tween order.
+You may be required to inspect your tween ordering (see
+:ref:`displaying_tweens`) and add a ``pyramid.tweens`` configuration value at
+the behest of an add-on author.
+
++---------------------------------+
+| Config File Setting Name        |
++=================================+
+| ``pyramid.tweens``              |
+|                                 |
+|                                 |
+|                                 |
++---------------------------------+
+
+The value supplied as ``pyramid.tweens`` should be a sequence.  The
+sequence can take several different forms.
+
+1) It can be a string.
+
+   If it is a string, the tween names can be separated by spaces::
+
+      pkg.tween_factory1 pkg.tween_factory2 pkg.tween_factory3
+
+    The tween names can also be separated by carriage returns::
+
+       pkg.tween_factory1
+       pkg.tween_factory2
+       pkg.tween_factory3
+
+2) It can be a Python list, where the values are strings::
+
+   ['pkg.tween_factory1', 'pkg.tween_factory2', 'pkg.tween_factory3']
+
+Each value in the sequence should be a :term:`dotted Python name`.
+
+Paste Configuration vs. Plain-Python Configuration
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Using the following ``pyramid.tweens`` setting in the PasteDeploy ``.ini``
+file in your application:
+
+.. code-block:: ini
+
+  [app:myapp]
+  pyramid.tweens = pyramid_debugtoolbar.toolbar.tween_factory
+                   pyramid.tweens.excview_tween_factory
+                   pyramid_tm.tm_tween_factory
+
+Is equivalent to using the following statements in your configuration code:
+
+.. code-block:: python
+   :linenos:
+
+  from pyramid.config import Configurator
+
+  def main(global_config, **settings):
+      settings['pyramid.tweens'] = [
+              'pyramid_debugtoolbar.toolbar.tween_factory',
+              'pyramid.tweebs.excview_tween_factory',
+              'pyramid_tm.tm_tween_factory',
+               ]
+      config = Configurator(settings=settings)
+
+It is fine to use both or either form.
+
 .. _mako_template_renderer_settings:
 
 Mako Template Render Settings
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index f81385c93..e07dca9bd 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -932,7 +932,8 @@ add_tween can provide an optional hint that can influence the implicit tween
 chain ordering by supplying ``under`` or ``over`` (or both) arguments to
 :meth:`~pyramid.config.Configurator.add_tween`.  These hints are only used
 used when an explicit tween chain is not used (when the ``pyramid.tweens``
-configuration value is not set).
+configuration value is not set).  See :ref:`explicit_tweens` for a
+description of how to set an explicit tweens list.
 
 Allowable values for ``under`` or ``over`` (or both) are:
 
@@ -1026,6 +1027,11 @@ For example:
 Alias names are only useful in relation to ``under`` and ``over`` values.
 They cannot be used in explicit tween chain configuration, or anywhere else.
 
+.. _explicit_tween_ordering:
+
+Explicit Tween Ordering
+~~~~~~~~~~~~~~~~~~~~~~~
+
 Implicit tween ordering is obviously only best-effort.  Pyramid will attempt
 to provide an implicit order of tweens as best it can using hints provided by
 calls to :meth:`~pyramid.config.Configurator.add_tween`, but because it's
@@ -1069,6 +1075,9 @@ handler is implicit, and always "at the bottom".
    ``pyramid.tweens`` configuration setting list explicitly.  If it is not
    present, Pyramid will not perform exception view handling.
 
+Tween Conflicts and Ordering Cycles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Pyramid will prevent the same tween factory from being added to the tween
 chain more than once using configuration conflict detection.  If you wish to
 add the same tween factory more than once in a configuration, you should
@@ -1082,6 +1091,9 @@ If a cycle is detected in implicit tween ordering when ``over`` and ``under``
 are used in any call to "add_tween", an exception will be raised at startup
 time.
 
+Displaying Tween Ordering
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The ``paster ptweens`` command-line utility can be used to report the current
 implict and explicit tween chains used by an application.  See
 :ref:`displaying_tweens`.