From 58c01ff8863971f81db59d437d49fd9e97b59e5c Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@plope.com>
Date: Sat, 3 Dec 2011 19:37:38 -0500
Subject: flesh out categories more

---
 docs/narr/introspector.rst | 80 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 69 insertions(+), 11 deletions(-)

(limited to 'docs/narr/introspector.rst')

diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index 8adfde7d1..ac0859164 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -15,6 +15,10 @@ feature is useful for debug toolbars, command-line scripts which show some
 aspect of configuration, and for runtime reporting of startup-time
 configuration settings.
 
+.. warning::
+
+   Introspection is new in Pyramid 1.3.
+
 Using the Introspector
 ----------------------
 
@@ -86,6 +90,12 @@ The important attributes shared by all introspectables are the following:
   often be a singular version of the category name but it can be an arbitrary
   value.
 
+``action_info``
+
+  An object describing the directive call site which caused this
+  introspectable to be registered; contains attributes described in
+  :class:`pyramid.interfaces.IActionInfo`.
+
 Besides having the attributes described above, an introspectable is a
 dictionary-like object.  An introspectable can be queried for data values via
 its ``__getitem__``, ``get``, ``keys``, ``values``, or ``items`` methods.
@@ -107,7 +117,7 @@ introspectables in categories not described here.
 ``subscribers``
 
   Each introspectable in the ``subscribers`` category represents a call to
-  :meth:`pryamid.config.Configurator.add_subscriber` (or the decorator
+  :meth:`pyramid.config.Configurator.add_subscriber` (or the decorator
   equivalent); each will have the following data.
 
   ``subscriber``
@@ -138,8 +148,6 @@ introspectables in categories not described here.
 
 ``root factories``
 
-  XXX ``default root factory`` category?
-
   Each introspectable in the ``root factories`` category represents a call to
   :meth:`pyramid.config.Configurator.set_root_factory` (or the Configurator
   constructor equivalent) *or* a ``factory`` argument passed to
@@ -435,8 +443,6 @@ introspectables in categories not described here.
 
 ``view mapper``
 
-  XXX default view mapper category?
-
   Each introspectable in the ``permissions`` category represents a call to
   :meth:`pyramid.config.Configurator.add_view` that has an explicit
   ``mapper`` argument to *or* a call to
@@ -450,17 +456,69 @@ introspectables in categories not described here.
 
 ``asset overrides``
 
-  XXX
+  Each introspectable in the ``asset overrides`` category represents a call
+  to :meth:`pyramid.config.Configurator.override_asset`; each will have the
+  following data.
+
+  ``to_override``
+
+    The ``to_override`` argument (an asset spec) passed to
+    ``override_asset``.
+
+  ``override_with``
+
+    The ``override_with`` argument (an asset spec) passed to
+    ``override_asset``.
 
 ``translation directories``
 
-  XXX
+  Each introspectable in the ``asset overrides`` category represents an
+  individual element in a ``specs`` argument passed to to
+  :meth:`pyramid.config.Configurator.add_translation_dirs`; each will have
+  the following data.
+
+  ``directory``
+
+    The absolute path of the translation directory.
+
+  ``spec``
+
+    The asset specification passed to ``add_translation_dirs``.
+
+``tweens``
+
+  Each introspectable in the ``tweens`` category represents a call to
+  :meth:`pyramid.config.Configurator.add_tween`; each will have the following
+  data.
+
+  ``name``
+
+    The dotted name to the tween factory as a string (passed as
+    the ``tween_factory`` argument to ``add_tween``).
+
+  ``factory``
+
+    The (resolved) tween factory object.
+
+  ``type``
+
+    ``implict`` or ``explicit`` as a string.
+
+  ``under``
+
+     The ``under`` argument passed to ``add_tween`` (a string).
+
+  ``over``
+
+     The ``over`` argument passed to ``add_tween`` (a string).
 
-``tweens (implicit)``
+Toolbar Introspection
+---------------------
 
-  XXX
+The Pyramid debug toolbar (part of the ``pyramid_debugtoolbar`` package)
+provides a canned view of all registered introspectables and their
+relationships.  It looks something like this:
 
-``tweens (explicit)``
+.. image:: tb_introspector.png
 
-  XXX
 
-- 
cgit v1.2.3