add more index markers

24 files changed, 242 insertions, 16 deletions

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index 3bd9c2a4e..8040a465f 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -14,7 +14,7 @@ you to ignore relative configuration statement ordering in some
 circumstances.
 
 .. index::
-   single: imperative configuration
+   pair: configuration; conflict detection
 
 .. _conflict_detection:
 
@@ -299,6 +299,9 @@ These are the methods of the configurator which provide conflict detection:
 provides conflict detection, because it's implemented in terms of the
 conflict-aware ``add_route`` and ``add_view`` methods.
 
+.. index::
+   pair: configuration; including from external sources
+
 .. _including_configuration:
 
 Including Configuration from External Sources
@@ -397,6 +400,10 @@ constraints: the routes they imply require relative ordering.  Such ordering
 constraints are not absolved by two-phase configuration.  Routes are still
 added in configuration execution order.
 
+.. index::
+   single: add_directive
+   pair: configurator; adding directives
+
 .. _add_directive:
 
 Adding Methods to the Configurator via ``add_directive``
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index f35f6dd7d..e609a3eab 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -35,6 +35,9 @@ static assets.  For example, there's a ``static`` directory which contains
 ``.css``, ``.js``, and ``.gif`` files.  These asset files are delivered when
 a user visits an application URL.
 
+.. index::
+   single: asset specifications
+
 .. _asset_specifications:
 
 Understanding Asset Specifications
@@ -85,6 +88,7 @@ individual documentation.
 
 .. index::
    single: add_static_view
+   pair: assets; serving
 
 .. _static_assets_section:
 
@@ -186,6 +190,7 @@ discussed in more detail later in this chapter.
 .. index::
    single: generating static asset urls
    single: static asset urls
+   pair:   assets; generating urls
 
 .. _generating_static_asset_urls:
 
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index b52faed20..a6ba99e17 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -183,6 +183,9 @@ hash after the filename:
 
 Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
 
+.. index::
+   pair: pshell; extending
+
 .. _extending_pshell:
 
 Extending the Shell
@@ -229,6 +232,9 @@ When this INI file is loaded, the extra variables ``m``, ``session`` and
       t            transaction
     >>>
 
+.. index::
+   single: IPython
+
 IPython
 ~~~~~~~
 
@@ -289,6 +295,10 @@ callable could be found.  If no routes are configured within your
 application, nothing will be printed to the console when ``paster proutes``
 is executed.
 
+.. index::
+   single: scripting
+   single: bootstrap
+
 .. _writing_a_script:
 
 Writing a Script
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 7f8e3953d..53234cba1 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -8,9 +8,12 @@
    single: debug_all
    single: reload_all
    single: debug settings
+   single: debug_routematch
+   single: prevent_http_cache
    single: reload settings
    single: default_locale_name
    single: environment variables
+   single: Mako environment settings
    single: ini file settings
    single: PasteDeploy settings
 
@@ -419,6 +422,9 @@ around in overridden asset directories. ``reload_assets`` makes the system
 *very slow* when templates are in use.  Never set ``reload_assets`` to
 ``True`` on a production system.
 
+.. index::
+   par: settings; adding custom
+
 .. _adding_a_custom_setting:
 
 Adding A Custom Setting
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index 87487b444..42711784b 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -1,3 +1,6 @@
+.. index::
+   single: hello world program
+
 .. _firstapp_chapter:
 
 Creating Your First :app:`Pyramid` Application
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index a156426ae..2a6414e1f 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -218,7 +218,7 @@ Another (deprecated) mechanism which allows event subscribers more control
 when adding renderer global values exists in :ref:`adding_renderer_globals`.
 
 .. index::
-   single: renderer globals
+   single: adding renderer globals
 
 .. _adding_renderer_globals:
 
@@ -528,6 +528,7 @@ The default context URL generator is available for perusal as the class
 
 .. index::
    single: IResponse
+   single: special view responses
 
 .. _using_iresponse:
 
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index a0a6a108c..ab1bf20bb 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -79,6 +79,9 @@ Typically, an application that uses traversal exclusively won't perform any
 calls to :meth:`pyramid.config.Configurator.add_route` in its startup
 code.
 
+.. index::
+   single: hybrid applications
+
 Hybrid Applications
 -------------------
 
@@ -177,6 +180,9 @@ match is straightforward.  When a route is matched:
    root factory were explained previously within
    :ref:`the_resource_tree`.
 
+.. index::
+   pair: hybrid applications; *traverse route pattern
+
 .. _using_traverse_in_a_route_pattern:
 
 Using ``*traverse`` In a Route Pattern
@@ -400,6 +406,9 @@ Traversal will begin at the root object implied by this route (either
 the global root, or the object returned by the ``factory`` associated
 with this route).
 
+.. index::
+   pair: hybrid applications; global views
+
 Making Global Views Match
 +++++++++++++++++++++++++
 
@@ -420,6 +429,7 @@ attribute.
    config.add_view('myproject.views.bazbuz', name='bazbuz')
 
 .. index::
+   pair: hybrid applications; *subpath
    single: route subpath
    single: subpath (route)
 
@@ -454,6 +464,9 @@ commonly in route declarations that look like this:
 :class:`pyramid.static.static_view`.  This effectively tells the static
 helper to traverse everything in the subpath as a filename.
 
+.. index::
+   pair: hybrid applications; corner cases
+
 Corner Cases
 ------------
 
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index c21a19b5b..924fb047a 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -353,6 +353,9 @@ The message catalog ``.pot`` template will end up in:
 
 ``myapplication/locale/myapplication.pot``.
 
+.. index::
+   single: translation domains
+
 Translation Domains
 +++++++++++++++++++
 
@@ -494,6 +497,8 @@ translations will be available to :app:`Pyramid`.
 .. index::
    single: localizer
    single: get_localizer
+   single: translation
+   single: pluralization
 
 Using a Localizer
 -----------------
@@ -744,6 +749,9 @@ this support out of the box and may need special code to do an
 equivalent.  For those, you can always use the more manual translation
 facility described in :ref:`performing_a_translation`.
 
+.. index::
+   single: Mako i18n
+
 Mako Pyramid I18N Support
 -------------------------
 
@@ -798,6 +806,9 @@ If this setting is supplied within the :app:`Pyramid` application
    settings = get_current_registry().settings
    default_locale_name = settings['default_locale_name']
 
+.. index::
+   single: detecting langauges
+
 "Detecting" Available Languages
 -------------------------------
 
@@ -857,6 +868,9 @@ languages" configuration scheme as necessary.
    pair: locale; negotiator
    single: translation directory
 
+.. index::
+   pair: activating; translation
+
 .. _activating_translation:
 
 Activating Translation
@@ -869,6 +883,9 @@ To turn translation on, you must:
 
 - ensure that your application sets the :term:`locale name` correctly.
 
+.. index::
+   pair: translation directory; adding
+
 .. _adding_a_translation_directory:
 
 Adding a Translation Directory
@@ -906,6 +923,9 @@ will be merged into translations from a message catalog added earlier
 if both translation directories contain translations for the same
 locale and :term:`translation domain`.
 
+.. index::
+   pair: setting; locale
+
 Setting the Locale
 ~~~~~~~~~~~~~~~~~~
 
@@ -936,6 +956,9 @@ things before any translations need to be performed:
    function into that application as required.  See
    :ref:`custom_locale_negotiator`.
 
+.. index::
+   single: locale negotiator
+
 .. _locale_negotiators:
 
 Locale Negotiators
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 5b9e22182..71988469a 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -34,6 +34,9 @@ you can either install Python using your operating system's package
 manager *or* you can install Python from source fairly easily on any
 UNIX system that has development tools.
 
+.. index::
+   pair: install; Python (from package, UNIX)
+
 Package Manager Method
 ++++++++++++++++++++++
 
@@ -52,6 +55,9 @@ command:
 Once these steps are performed, the Python interpreter will usually be
 invokable via ``python2.6`` from a shell prompt.
 
+.. index::
+   pair: install; Python (from source, UNIX)
+
 Source Compile Method
 +++++++++++++++++++++
 
@@ -95,6 +101,9 @@ Once these steps are performed, the Python interpreter will be
 invokable via ``$HOME/opt/Python-2.6.4/bin/python`` from a shell
 prompt.
 
+.. index::
+   pair: install; Python (from package, Windows)
+
 If You Don't Yet Have A Python Interpreter (Windows)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -180,7 +189,7 @@ the script.  To remediate this, you may need to do:
    $ sudo python ez_setup.py
 
 .. index::
-   single: virtualenv
+   pair: install; virtualenv
 
 Installing the ``virtualenv`` Package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -204,6 +213,7 @@ to install it as your system's administrative user.  For example:
 
 .. index::
    single: virtualenv
+   pair: Python; virtual environment
 
 Creating the Virtual Python Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -312,6 +322,9 @@ Installing :app:`Pyramid` on Google App Engine
 :ref:`appengine_tutorial` documents the steps required to install a
 :app:`Pyramid` application on Google App Engine.
 
+.. index::
+   single: installing on Jython
+
 Installing :app:`Pyramid` on Jython
 --------------------------------------
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index d26f1b8bf..6cc5a87e5 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -67,8 +67,7 @@ Openness
   open source license <http://repoze.org/license.html>`_.
 
 .. index::
-   single: Pylons
-   single: repoze namespace package
+   single: Pylons Project
 
 What Is The Pylons Project?
 ---------------------------
diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst
index a4709ef18..6ad33c1ce 100644
--- a/docs/narr/muchadoabouttraversal.rst
+++ b/docs/narr/muchadoabouttraversal.rst
@@ -39,6 +39,9 @@ web developer so you know when you might want to use them.  :term:`Traversal`
 is actually a straightforward metaphor easily comprehended by anyone who's
 ever used a run-of-the-mill file system with folders and files.
 
+.. index::
+   single: URL dispatch
+
 URL Dispatch
 ------------
 
@@ -100,12 +103,12 @@ from this process to the client as the final result.  The server
 configuration specified which files would trigger some dynamic code, with the
 default case being to just serve the static file.
 
+.. index::
+   single: traversal
+
 Traversal (aka Resource Location)
 ---------------------------------
 
-.. index::
-   single: traversal overview
-
 Believe it or not, if you understand how serving files from a file system
 works, you understand traversal.  And if you understand that a server might do
 something different based on what type of file a given request specifies,
@@ -141,6 +144,9 @@ generated anywhere along the way, :app:`Pyramid` will return 404.  (This
 isn't precisely true, as you'll see when we learn about view lookup below,
 but the basic idea holds.)
 
+.. index::
+   single: resource
+
 What Is a "Resource"?
 ---------------------
 
@@ -194,6 +200,9 @@ system.  Traversal is in fact a superset of file system lookup.
 .. note:: See the chapter entitled :ref:`resources_chapter` for a more
    technical overview of resources.
 
+.. index::
+   single: view lookup
+
 View Lookup
 -----------
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 4b08d09f6..cdf57729d 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -249,7 +249,6 @@ create`` -generated project.  Within a project generated by the
    single: paster serve
    single: reload
    single: startup
-   single: mod_wsgi
 
 Running The Project Application
 -------------------------------
@@ -295,6 +294,10 @@ For more detailed information about the startup process, see
 configuration file settings that influence startup and runtime behavior, see
 :ref:`environment_chapter`.
 
+.. index::
+   single: mod_wsgi
+   single: WSGI
+
 Viewing the Application
 -----------------------
 
@@ -533,6 +536,9 @@ implementations.
    to your application's ``main`` function as ``global_config`` (see
    the reference to the ``main`` function in :ref:`init_py`).
 
+.. index::
+   single: production.ini
+
 ``production.ini``
 ~~~~~~~~~~~~~~~~~~~
 
@@ -658,6 +664,9 @@ who want to use your application.
    setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this
    behavior to work properly.
 
+.. index::
+   single: setup.cfg
+
 ``setup.cfg``
 ~~~~~~~~~~~~~
 
@@ -753,6 +762,9 @@ also informs Python that the directory which contains it is a *package*.
    Line 12 returns a :term:`WSGI` application to the caller of the function
    (Paste).
 
+.. index::
+   single: views.py
+
 ``views.py``
 ~~~~~~~~~~~~
 
@@ -823,6 +835,9 @@ about which sort of data storage you'll want to use, so the sample
 application uses an instance of :class:`myproject.resources.Root` to
 represent the root.
 
+.. index::
+   single: static directory
+
 ``static``
 ~~~~~~~~~~
 
@@ -863,6 +878,9 @@ example.
 See :ref:`testing_chapter` for more information about writing :app:`Pyramid`
 unit tests.
 
+.. index::
+   pair: modifying; package structure
+
 .. _modifying_package_structure:
 
 Modifying Package Structure
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index f329a7af9..572d5855e 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -228,6 +228,9 @@ Views which use the JSON renderer can vary non-body response attributes by
 using the api of the ``request.response`` attribute.  See
 :ref:`request_response_attr`.
 
+.. index::
+   pair: renderer; JSONP
+
 .. _jsonp_renderer:
 
 JSONP Renderer
@@ -522,9 +525,6 @@ people with older code bases.
   returning various values in the ``response_headerlist``, this is purely a
   convenience.
 
-.. index::
-   single: renderer (adding)
-
 .. _adding_and_overriding_renderers:
 
 Adding and Changing Renderers
@@ -550,6 +550,9 @@ The first argument is the renderer name.  The second argument is a reference
 to an implementation of a :term:`renderer factory` or a :term:`dotted Python
 name` referring to such an object.
 
+.. index::
+   pair: renderer; adding
+
 .. _adding_a_renderer:
 
 Adding a New Renderer
@@ -676,6 +679,9 @@ ending with ``.jinja2`` in its ``renderer`` value.  The ``name`` passed
 to the ``MyJinja2Renderer`` constructor will be the full value that was
 set as ``renderer=`` in the view configuration.
 
+.. index::
+   pair: renderer; changing
+
 Changing an Existing Renderer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -715,6 +721,9 @@ the ``name`` attribute to the renderer tag:
 
    config.add_renderer(None, 'mypackage.json_renderer_factory')
 
+.. index::
+   pair: renderer; overriding at runtime
+
 Overriding A Renderer At Runtime
 --------------------------------
 
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index fa8ccc549..0e0d00020 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -286,6 +286,9 @@ The shortcut method of the :term:`request` named
 For more information about generating resource URLs, see the documentation
 for :func:`pyramid.url.resource_url`.
 
+.. index::
+   pair: resource URL generation; overriding
+
 .. _overriding_resource_url_generation:
 
 Overriding Resource URL Generation
@@ -333,6 +336,9 @@ qualified, should end in a slash, and should not contain any query string or
 anchor elements (only path elements) to work best with
 :func:`~pyramid.url.resource_url`.
 
+.. index::
+   single: resource path generation
+
 Generating the Path To a Resource
 ---------------------------------
 
@@ -368,6 +374,9 @@ The resource passed in must be :term:`location`-aware.
 The presence or absence of a :term:`virtual root` has no impact on the
 behavior of :func:`~pyramid.traversal.resource_path`.
 
+.. index::
+   pair: resource; finding by path
+
 Finding a Resource by Path
 --------------------------
 
@@ -404,6 +413,9 @@ tree does not exist), a :exc:`KeyError` will be raised.
 See the :func:`pyramid.traversal.find_resource` documentation for more
 information about resolving a path to a resource.
 
+.. index::
+   pair: resource; lineage
+
 Obtaining the Lineage of a Resource
 -----------------------------------
 
@@ -471,6 +483,9 @@ parent (or one of its parent's parents, etc.) is an ancestor.
 
 See :func:`pyramid.location.inside` for more information.
 
+.. index::
+   pair: resource; finding root
+
 Finding the Root Resource
 -------------------------
 
@@ -617,6 +632,9 @@ directly provided by an instance instead of overwriting them like
 For more information about how resource interfaces can be used by view
 configuration, see :ref:`using_resource_interfaces`.
 
+.. index::
+   pair: resource; finding by interface or class
+
 Finding a Resource With a Class or Interface in Lineage
 -------------------------------------------------------
 
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
index 0812f7ec7..d08261b17 100644
--- a/docs/narr/router.rst
+++ b/docs/narr/router.rst
@@ -2,6 +2,7 @@
    single: request processing
    single: request
    single: router
+   single: request lifecycle
 
 .. _router_chapter:
 
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 322e905f6..65f3d7cf0 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -168,6 +168,9 @@ normal application operations, the requesting user will need to possess the
 to invoke the ``blog_entry_add_view`` view.  If he does not, the
 :term:`Forbidden view` will be invoked.
 
+.. index::
+   pair: permission; default
+
 .. _setting_a_default_permission:
 
 Setting a Default Permission
@@ -212,6 +215,7 @@ When a default permission is registered:
 .. index::
    single: ACL
    single: access control list
+   pair: resource; ACL
 
 .. _assigning_acls:
 
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 365ee395b..6ff9e3dea 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -15,6 +15,9 @@ implementations :app:`Pyramid` provides out of the box, how to store and
 retrieve data from sessions, and two session-specific features: flash
 messages, and cross-site request forgery attack prevention.
 
+.. index::
+   single: session factory (default)
+
 .. _using_the_default_session_factory:
 
 Using The Default Session Factory
@@ -65,6 +68,9 @@ application by using the ``session_factory`` argument to the
    the server) for anything but the most basic of applications where "session
    security doesn't matter".
 
+.. index::
+   single: session object
+
 Using a Session Object
 ----------------------
 
@@ -137,6 +143,7 @@ Some gotchas:
 .. index::
    single: pyramid_beaker
    single: Beaker
+   single: session factory (alternates)
 
 .. _using_alternate_session_factories:
 
@@ -153,7 +160,7 @@ based sessions, and encrypted cookie-based sessions.  See
 ``pyramid_beaker``.
 
 .. index::
-   single: session factory
+   single: session factory (custom)
 
 Creating Your Own Session Factory
 ---------------------------------
@@ -184,6 +191,9 @@ log messages for single-time display without having direct access to an HTML
 template. The user interface consists of a number of methods of the
 :term:`session` object.
 
+.. index::
+   single: session.flash
+
 Using the ``session.flash`` Method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -222,6 +232,9 @@ The ``allow_duplicate`` argument defaults to ``True``.  If this is
 ``False``, and you attempt to add a message value which is already
 present in the queue, it will not be added.
 
+.. index::
+   single: session.pop_flash
+
 Using the ``session.pop_flash`` Method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -255,6 +268,9 @@ been popped.
    >>> request.session.pop_flash()
    []
 
+.. index::
+   single: session.peek_flash
+
 Using the ``session.peek_flash`` Method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -298,6 +314,9 @@ post.  To use CSRF token support, you must enable a :term:`session factory`
 as described in :ref:`using_the_default_session_factory` or
 :ref:`using_alternate_session_factories`.
 
+.. index::
+   single: session.get_csrf_token
+
 Using the ``session.get_csrf_token`` Method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -330,6 +349,9 @@ input field named ``csrf_token``:
    if token != request.POST['csrf_token']:
        raise ValueError('CSRF token did not match')
 
+.. index::
+   single: session.new_csrf_token
+
 Using the ``session.new_csrf_token`` Method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 788896de9..8661c8f6a 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -140,6 +140,10 @@ Here's a high-level time-ordered overview of what happens when you press
    The server serves the application, and the application is running, waiting
    to receive requests.
 
+.. index::
+   pair: settings; deployment
+   single: custom settings
+
 .. _deployment_settings:
 
 Deployment Settings
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 150b173e3..7c575b9bf 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -241,6 +241,9 @@ of :func:`~pyramid.renderers.render` (a string):
    single: renderer (template)
 
 
+.. index::
+   pair: renderer; system values
+
 .. _renderer_system_values:
 
 System Values Used During Rendering
@@ -277,6 +280,9 @@ renderer itself, but most template renderers, including Chameleon and
 Mako renderers, make these names available as top-level template
 variables.
 
+.. index::
+   pair: renderer; templates
+
 .. _templates_used_as_renderers:
 
 Templates Used as Renderers via Configuration
@@ -426,7 +432,7 @@ See also :ref:`built_in_renderers` for more general information about
 renderers, including Chameleon ZPT renderers.
 
 .. index::
-   single: sample template
+   single: ZPT template (sample)
 
 A Sample ZPT Template
 ~~~~~~~~~~~~~~~~~~~~~
@@ -596,6 +602,9 @@ Note that I always name my Chameleon ZPT template files with a ``.pt``
 extension and my Chameleon text template files with a ``.txt``
 extension so that these ``svn:ignore`` patterns work.
 
+.. index::
+   pair: debugging; templates
+
 .. _debug_templates_section:
 
 Nicer Exceptions in Chameleon Templates
@@ -724,6 +733,9 @@ in the ``templates`` subdirectory of the ``mypackage`` Python package.  See
 ``mako.directories`` setting and other Mako-related settings that can be
 placed into the application's ``ini`` file.
 
+.. index::
+   single: Mako template (sample)
+
 A Sample Mako Template
 ~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index b0a7009e3..a25f47690 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -50,6 +50,9 @@ a context object).  But ironically, using URL dispatch (instead of
 terms of "resources" entirely, because it allows you to directly map a
 :term:`view callable` to a route.
 
+.. index::
+   single: route configuration
+
 Route Configuration
 -------------------
 
@@ -381,6 +384,9 @@ a separate :term:`ACL`, as documented in
 combine URL dispatch with :term:`traversal` as documented within
 :ref:`hybrid_chapter`.
 
+.. index::
+   single: route configuration arguments
+
 Route Configuration Arguments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -402,6 +408,9 @@ neither predicates nor view configuration information.
    names a ``view`` and these arguments have been deprecated as of
    :app:`Pyramid` 1.1.
 
+.. index::
+   single: route predicates (custom)
+
 .. _custom_route_predicates:
 
 Custom Route Predicates
@@ -534,6 +543,9 @@ that the year match argument is '2010' if and only if the route name is
 See also :class:`pyramid.interfaces.IRoute` for more API documentation about
 route objects.
 
+.. index::
+   single: route matching
+
 Route Matching
 --------------
 
@@ -745,6 +757,9 @@ representing a :term:`SQLAlchemy` model.
    single: matching the root URL
    single: root url (matching)
 
+.. index::
+   pair: matching; root URL
+
 Matching the Root URL
 ---------------------
 
@@ -914,6 +929,9 @@ The ``notfound_view`` supplied must adhere to the two-argument view callable
 calling convention of ``(context, request)`` (``context`` will be the
 exception object).
 
+.. index::
+   single: cleaning up after request
+
 .. _cleaning_up_after_a_request:
 
 Cleaning Up After a Request
@@ -997,6 +1015,9 @@ our sample ``Article`` factory class is not very ambitious.
 .. note:: See :ref:`security_chapter` for more information about
    :app:`Pyramid` security and ACLs.
 
+.. index::
+   pair: debugging; route matching
+
 .. _debug_routematch_section:
 
 Debugging Route Matching
@@ -1032,6 +1053,9 @@ You can also use the ``paster proutes`` command to see a display of all the
 routes configured in your application; for more information, see
 :ref:`displaying_application_routes`.
 
+.. index::
+   pair: route; view callable lookup details
+
 Route View Callable Registration and Lookup Details
 ---------------------------------------------------
 
diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst
index d3ff260e3..5679cc2e2 100644
--- a/docs/narr/vhosting.rst
+++ b/docs/narr/vhosting.rst
@@ -14,6 +14,9 @@ URL space that it does not "naturally" inhabit.
 a URL "prefix", as well as serving a *portion* of a :term:`traversal`
 based application under a root URL.
 
+.. index::
+   single: hosting an app under a prefix
+
 Hosting an Application Under a URL Prefix
 -----------------------------------------
 
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 54d3fc4ff..94b80a3f2 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -20,6 +20,10 @@ In earlier chapters, you have been exposed to a few simple view configuration
 declarations without much explanation. In this chapter we will explore the
 subject in detail.
 
+.. index::
+   pair: resource; mapping to view callable
+   pair: URL pattern; mapping to view callable
+
 Mapping a Resource or URL Pattern to a View Callable
 ----------------------------------------------------
 
@@ -41,6 +45,9 @@ View configuration is performed in one of two ways:
 - by using the :meth:`pyramid.config.Configurator.add_view` method as per
   :ref:`mapping_views_using_imperative_config_section`.
 
+.. index::
+   single: view configuration parameters
+
 .. _view_configuration_parameters:
 
 View Configuration Parameters
@@ -475,6 +482,9 @@ form of :term:`declarative configuration`, while
 :meth:`pyramid.config.Configurator.add_view` is a form of :term:`imperative
 configuration`.  However, they both do the same thing.
 
+.. index::
+   single: view_config placement
+
 ``@view_config`` Placement
 ++++++++++++++++++++++++++
 
@@ -822,7 +832,10 @@ headers that your application code itself sets.  It will only prevent caching
 headers that would have been set by the Pyramid HTTP caching machinery
 invoked as the result of the ``http_cache`` argument to view configuration.
 
-Debugging View Configuration
+.. index::
+   pair: view configuration; debugging
+
+ebugging View Configuration
 ----------------------------
 
 See :ref:`displaying_matching_views` for information about how to display
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 6acb1d28d..1c9529860 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -35,6 +35,9 @@ This chapter describes how view callables work. In the
 :ref:`view_config_chapter` chapter, there are details about performing
 view configuration, and a detailed explanation of view lookup.
 
+.. index::
+   single: view callables
+
 View Callables
 --------------
 
@@ -586,6 +589,9 @@ callable code itself.
 No matter which view calling convention is used, the view code always has
 access to the context via ``request.context``.
 
+.. index::
+   single: Pylons-style controller dispatch
+
 Pylons-1.0-Style "Controller" Dispatch
 --------------------------------------
 
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index 0d928e532..6e8c39523 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -243,6 +243,9 @@ tuples; all the keys are ordered, and all the values are ordered.
 API documentation for a multidict exists as
 :class:`pyramid.interfaces.IMultiDict`.
 
+.. index::
+   pair: json_body; request
+
 .. _request_json_body:
 
 Dealing With A JSON-Encoded Request Body
@@ -408,7 +411,7 @@ anything, though if you subclass :class:`pyramid.response.Response` and set
 ``default_content_type`` you can override this behavior.
 
 .. index::
-   single: response exceptions
+   single: exception responses
 
 Exception Responses
 +++++++++++++++++++