Use :meth:, :func:, and :class: appropriately for configuration-related docs.

2 files changed, 128 insertions, 120 deletions

diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 367df2a2d..2d74c8133 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -7,11 +7,11 @@ The majority of the logic in any web application is completely
 application-specific.  For example, the body of a web page served by
 one web application might be a representation of the contents of an
 accounting ledger, while the content of of a web page served by
-another might be a listing of songs.  These applications obviously may
-not serve the same set of customers.  However, both the ledger-serving
-and song-serving applications can be written using :mod:`repoze.bfg`,
-because :mod:`repoze.bfg` is a very general *framework* which can be
-used to create all kinds of web applications.
+another might be a listing of songs.  These applications obviously
+will not serve the same set of customers.  However, both the
+ledger-serving and song-serving applications can be written using
+:mod:`repoze.bfg`, because :mod:`repoze.bfg` is a very general
+*framework* which can be used to create all kinds of web applications.
 
 .. sidebar:: Frameworks vs. Libraries
 
@@ -119,15 +119,15 @@ The above script defines the following set of imports:
 
 :mod:`repoze.bfg` uses the :term:`WebOb` library as the basis for its
 :term:`request` and :term:`response` objects.  The script uses the
-``webob.Response`` class later in the script to create a
+:class:`webob.Response` class later in the script to create a
 :term:`response` object.
 
 Like many other Python web frameworks, :mod:`repoze.bfg` uses the
 :term:`WSGI` protocol to connect an application and a web server
-together.  The ``paste.httpserver`` server is used in this example as
-a WSGI server, purely for convenience, as ``Paste`` is a dependency of
-:mod:`repoze.bfg` itself; :mod:`repoze.bfg` applications can be served
-by any WSGI server.
+together.  The :mod:`paste.httpserver` server is used in this example
+as a WSGI server, purely for convenience, as ``Paste`` is a dependency
+of :mod:`repoze.bfg` itself; :mod:`repoze.bfg` applications can be
+served by any WSGI server.
 
 The script also imports the ``Configurator`` class from the
 ``repoze.bfg.configuration`` module.  This class is used to configure
@@ -151,7 +151,7 @@ one named ``hello_world`` and one named ``goodbye_world``.
        return Response('Goodbye world!')
 
 Both functions accepts a single argument (``request``), and each
-returns an instance of the ``webob.Response`` class.  In the
+returns an instance of the :class:`webob.Response` class.  In the
 ``hello_world`` function, the string ``'Hello world!'`` is passed to
 the ``Response`` constructor as the *body* of the response.  In the
 ``goodbye_world`` function, the string ``'Goodbye world!'`` is passed.
@@ -307,20 +307,21 @@ if this module is imported; the code within the ``if`` block should
 only be run during a direct script execution.
 
 The ``config = Configurator()`` line above creates an instance of the
-``repoze.bfg.configuration.Configurator`` class.  The resulting
+:class:`repoze.bfg.configuration.Configurator` class.  The resulting
 ``config`` object represents an API which the script uses to configure
 this particular :mod:`repoze.bfg` application.
 
 .. note::
 
-   An instance of the ``Configurator`` class is a *wrapper* object
-   which mutates an :term:`application registry` as its methods are
-   called.  An application registry represents the configuration state
-   of a :mod:`repoze.bfg` application.  The ``Configurator`` is not
-   itself an :term:`application registry`, it is a mechanism used to
-   configure an application registry.  The underlying application
-   registry object being configured by a ``Configurator`` is available
-   as its ``registry`` attribute.
+   An instance of the :class:`repoze.bfg.configuration.Configurator`
+   class is a *wrapper* object which mutates an :term:`application
+   registry` as its methods are called.  An application registry
+   represents the configuration state of a :mod:`repoze.bfg`
+   application.  The ``Configurator`` is not itself an
+   :term:`application registry`, it is a mechanism used to configure
+   an application registry.  The underlying application registry
+   object being configured by a ``Configurator`` is available as its
+   ``registry`` attribute.
 
 Beginning Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -330,15 +331,15 @@ Beginning Configuration
 
        config.begin()
 
-The ``begin`` method of a Configurator tells the the system that
-application configuration has begun.  In particular, this causes the
-:term:`application registry` associated with this configurator to
-become the "current" application registry, meaning that code which
-attempts to use the application registry :term:`thread local` will
-obtain the registry associated with the configurator.  This is an
-explicit step because it's sometimes convenient to use a configurator
-without causing the registry associated with the configurator to
-become "current".
+The :meth:`repoze.bfg.configuration.Configurator.begin` method tells
+the the system that application configuration has begun.  In
+particular, this causes the :term:`application registry` associated
+with this configurator to become the "current" application registry,
+meaning that code which attempts to use the application registry
+:term:`thread local` will obtain the registry associated with the
+configurator.  This is an explicit step because it's sometimes
+convenient to use a configurator without causing the registry
+associated with the configurator to become "current".
 
 Adding Configuration
 ~~~~~~~~~~~~~~~~~~~~
@@ -349,14 +350,15 @@ Adding Configuration
        config.add_view(hello_world)
        config.add_view(goodbye_world, name='goodbye')
 
-Each of these lines calls the ``add_view`` method of the
-``Configurator`` API.  The ``add_view`` method of a configurator
-registers a :term:`view configuration` within the :term:`application
-registry`.  A :term:`view configuration` represents a :term:`view
-callable` which must be invoked when a set of circumstances related to
-the :term:`request` is true.  This "set of circumstances" is provided
-as one or more keyword arguments to the ``add_view`` method, otherwise
-known as :term:`predicate` arguments.
+Each of these lines calls the
+:meth:`repoze.bfg.configuration.Configurator.add_view` method.  The
+``add_view`` method of a configurator registers a :term:`view
+configuration` within the :term:`application registry`.  A :term:`view
+configuration` represents a :term:`view callable` which must be
+invoked when a set of circumstances related to the :term:`request` is
+true.  This "set of circumstances" is provided as one or more keyword
+arguments to the ``add_view`` method, otherwise known as
+:term:`predicate` arguments.
 
 The line ``config.add_view(hello_world)`` registers the
 ``hello_world`` function as a view callable.  The ``add_view`` method
@@ -386,8 +388,9 @@ invoked.
    it through a relatively-ordered series of URL path matches.  We're
    not really concerned about the finer details of :term:`URL
    dispatch` right now.  It's just useful to use for demonstrative
-   purposes: the ordering of calls to ``Configurator.add_view`` is
-   never very important.  We can register ``goodbye_world`` first and
+   purposes: the ordering of calls to
+   :meth:`repoze.bfg.configuration.Configurator.add_view`` is never
+   very important.  We can register ``goodbye_world`` first and
    ``hello_world`` second; :mod:`repoze.bfg` will still give us the
    most specific callable when a request is dispatched to it.
 
@@ -447,13 +450,14 @@ Ending Configuration
 
        config.end()
 
-The ``end`` method of a Configurator tells the the system that
-application configuration has ended.  It is the inverse of
-``config.begin``.  In particular, this causes the :term:`application
-registry` associated with this configurator to no longer be the
-"current" application registry, meaning that code which attempts to
-use the application registry :term:`thread local` will no longer
-obtain the registry associated with the configurator.
+The :meth:`repoze.bfg.configuration.Configurator.end` method tells the
+the system that application configuration has ended.  It is the
+inverse of :meth:`repoze.bfg.configuration.Configurator.begin`.  In
+particular, this causes the :term:`application registry` associated
+with this configurator to no longer be the "current" application
+registry, meaning that code which attempts to use the application
+registry :term:`thread local` will no longer obtain the registry
+associated with the configurator.
 
 WSGI Application Creation
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -464,16 +468,17 @@ WSGI Application Creation
        app = config.make_wsgi_app()
 
 After configuring views and ending configuration, the script creates a
-WSGI *application* via the ``config.make_wsgi_app`` method.  A call to
-``make_wsgi_app`` implies that all configuration is finished (meaning
-all method calls to the configurator which set up views, and various
-other configuration settings have been performed).  The
+WSGI *application* via the
+:meth:`repoze.bfg.configuration.Configurator.make_wsgi_app` method.  A
+call to ``make_wsgi_app`` implies that all configuration is finished
+(meaning all method calls to the configurator which set up views, and
+various other configuration settings have been performed).  The
 ``make_wsgi_app`` method returns a :term:`WSGI` application object
 that can be used by any WSGI server to present an application to a
 requestor.
 
 The :mod:`repoze.bfg` application object, in particular, is an
-instance of the ``repoze.bfg.router.Router`` class.  It has a
+instance of the :class:`repoze.bfg.router.Router` class.  It has a
 reference to the :term:`application registry` which resulted from
 method calls to the configurator used to configure it.  The Router
 consults the registry to obey the policy choices made by a single
@@ -494,12 +499,13 @@ WSGI Application Serving
        serve(app)
 
 Finally, we actually serve the application to requestors by starting
-up a WSGI server.  We happen to use the ``paste.httpserver.serve``
+up a WSGI server.  We happen to use the :func:`paste.httpserver.serve`
 WSGI server runner, using the default TCP port of 8080, and we pass it
-the ``app`` object (an instance of ``repoze.bfg.router.Router``) as
-the application we wish to serve.  This causes the server to start
-listening on the TCP port.  It will serve requests forever, or at
-least until we stop it by killing the process which runs it.
+the ``app`` object (an instance of the
+:class:`repoze.bfg.router.Router` class) as the application we wish to
+serve.  This causes the server to start listening on the TCP port.  It
+will serve requests forever, or at least until we stop it by killing
+the process which runs it.
 
 Conclusion
 ~~~~~~~~~~
@@ -601,11 +607,11 @@ within the ``if __name__ == '__main__'`` section of ``helloworld.py``:
        app = config.make_wsgi_app()
        simple_server.make_server('', 8080, app).serve_forever()
 
-In our "declarative" code, we've added a call to the ``load_zcml``
-method of the ``Configurator`` with the value ``configure.zcml``, and
-we've removed the lines which read ``config.add_view(hello_world)``
-and ``config.add_view(goodbye_world, name='goodbye')``, so that it now
-reads as:
+In our "declarative" code, we've added a call to the
+:meth:`repoze.bfg.configuration.Configurator.load_zcml` method with
+the value ``configure.zcml``, and we've removed the lines which read
+``config.add_view(hello_world)`` and ``config.add_view(goodbye_world,
+name='goodbye')``, so that it now reads as:
 
 .. code-block:: python
    :linenos:
@@ -679,16 +685,16 @@ The ``configure.zcml`` ZCML file contains this bit of XML within the
 
 This singleton (self-closing) tag instructs ZCML to load a ZCML file
 from the Python package with the :term:`dotted Python name`
-``repoze.bfg.includes``, as specified by its ``package`` attribute.
+:mod:`repoze.bfg.includes`, as specified by its ``package`` attribute.
 This particular ``<include>`` declaration is required because it
 actually allows subsequent declaration tags (such as ``<view>``, which
 we'll see shortly) to be recognized.  The ``<include>`` tag
 effectively just includes another ZCML file; this causes its
 declarations to be executed.  In this case, we want to load the
 declarations from the file named ``configure.zcml`` within the
-``repoze.bfg.includes`` Python package.  We know we want to load the
-``configure.zcml`` from this package because ``configure.zcml`` is the
-default value for another attribute of the ``<include>`` tag named
+:mod:`repoze.bfg.includes` Python package.  We know we want to load
+the ``configure.zcml`` from this package because ``configure.zcml`` is
+the default value for another attribute of the ``<include>`` tag named
 ``file``.  We could have spelled the include tag more verbosely, but
 equivalently as:
 
@@ -700,13 +706,13 @@ equivalently as:
 
 The ``<include>`` tag that includes the ZCML statements implied by the
 ``configure.zcml`` file from the Python package named
-``repoze.bfg.includes`` is basically required to come before any other
-named declaration in an application's ``configure.zcml``.  If it is
-not included, subsequent declaration tags will fail to be recognized,
-and the configuration system will generate a traceback.  However, the
-``<include package="repoze.bfg.includes"/>`` tag needs to exist only
-in a "top-level" ZCML file, it needn't also exist in ZCML files
-*included by* a top-level ZCML file.
+:mod:`repoze.bfg.includes` is basically required to come before any
+other named declaration in an application's ``configure.zcml``.  If it
+is not included, subsequent declaration tags will fail to be
+recognized, and the configuration system will generate a traceback.
+However, the ``<include package="repoze.bfg.includes"/>`` tag needs to
+exist only in a "top-level" ZCML file, it needn't also exist in ZCML
+files *included by* a top-level ZCML file.
 
 The ``<view>`` Tag
 ~~~~~~~~~~~~~~~~~~
@@ -751,16 +757,16 @@ configurations imperatively, we saw this code:
        config.add_view(goodbye_world, name='goodbye')
 
 Each ``<view>`` declaration tag encountered in a ZCML file effectively
-invokes the ``add_view`` method of the ``Configurator`` object on the
-behalf of the developer.  Various attributes can be specified on the
-``<view>`` tag which influence the :term:`view configuration` it
-creates.
+invokes the :meth:`repoze.bfg.configuration.Configurator.add_view`
+method on the behalf of the developer.  Various attributes can be
+specified on the ``<view>`` tag which influence the :term:`view
+configuration` it creates.
 
-Since the relative ordering of calls to ``Configuration.add_view``
-doesn't matter (see the sidebar above entitled *View Dispatch and
-Ordering*), the relative order of ``<view>`` tags in ZCML doesn't
-matter either.  The following ZCML orderings are completely
-equivalent:
+Since the relative ordering of calls to
+:meth:`repoze.bfg.configuration.Configurator.add_view` doesn't matter
+(see the sidebar above entitled *View Dispatch and Ordering*), the
+relative order of ``<view>`` tags in ZCML doesn't matter either.  The
+following ZCML orderings are completely equivalent:
 
 .. topic:: Hello Before Goodbye
 
@@ -793,8 +799,8 @@ equivalent:
 The ``<view>`` tag is an example of a :mod:`repoze.bfg` declaration
 tag.  Other such tags include ``<route>``, ``<scan>``, ``<notfound>``,
 ``<forbidden>``, and others.  Each of these tags is effectively a
-"macro" which calls methods on the ``Configurator`` object on your
-behalf.
+"macro" which calls methods on the
+:class:`repoze.bfg.configuration.Configurator` object on your behalf.
 
 ZCML Conflict Detection
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -823,9 +829,9 @@ start.  For example, the following ZCML file has two conflicting
     </configure>
 
 If you try to use this ZCML file as the source of ZCML for an
-application, a ``ConfigurationError`` will be raised when you attempt
-to start the application with information about which tags might have
-conflicted.
+application, a :data:`repoze.bfg.exceptions.ConfigurationError` will
+be raised when you attempt to start the application with information
+about which tags might have conflicted.
 
 .. _word_on_xml_namespaces:
 
@@ -880,19 +886,20 @@ Conclusions
 
 .. sidebar::  Which Configuration Mode Should I Use?
 
-  We recommend declarative configuration (ZMCL), because it's the more
-  traditional form of configuration used by Zope-based systems, it can
-  be overridden and extended by third party deployers, and there are
-  more examples for it "in the wild".  However, imperative mode
-  configuration can be simpler to understand.
+  We recommend declarative configuration (:term:`ZCML`), because it's
+  the more traditional form of configuration used by Zope-based
+  systems, it can be overridden and extended by third party deployers,
+  and there are more examples for it "in the wild".  However,
+  imperative mode configuration can be simpler to understand.
 
 :mod:`repoze.bfg` allows an application to perform configuration tasks
 either imperatively or declaratively.  You can choose the mode that
 best fits your brain as necessary.
 
-For more information about the API of the ``Configurator`` object, see
-:ref:`configuration_module`.  The equivalent ZCML declaration tags are
-introduced in narrative documentation chapters as necessary.
+For more information about the API of a ``Configurator`` object, see
+:class:`repoze.bfg.configuration.Configurator` .  The equivalent ZCML
+declaration tags are introduced in narrative documentation chapters as
+necessary.
 
 For more information about :term:`traversal`, see
 :ref:`traversal_chapter`.
diff --git a/repoze/bfg/configuration.py b/repoze/bfg/configuration.py
index e96c26853..8eff2e14d 100644
--- a/repoze/bfg/configuration.py
+++ b/repoze/bfg/configuration.py
@@ -76,7 +76,7 @@ class Configurator(object):
     ``authorization_policy``, ``renderers`` and ``debug_logger``.
 
     If the ``registry`` argument is passed as a non-``None`` value, it
-    must be an instance of the :mod:`repoze.bfg.registry.Registry`
+    must be an instance of the :class:`repoze.bfg.registry.Registry`
     class representing the registry to configure.  If ``registry`` is
     ``None``, the configurator will create a ``Registry`` instance
     itself; it will also perform some default configuration that would
@@ -99,7 +99,7 @@ class Configurator(object):
     If the ``settings`` argument is passed, it should be a Python
     dictionary representing the deployment settings for this
     application.  These are later retrievable using the
-    ``repoze.bfg.settings.get_settings`` API.
+    :func:`repoze.bfg.settings.get_settings` API.
 
     If the ``root_factory`` argument is passed, it should be an object
     representing the default :term:`root factory` for your
@@ -284,7 +284,7 @@ class Configurator(object):
         This pushes a dictionary containing the registry implied by
         this configurator and the :term:`request` implied by
         ``request`` on to the :term:`thread local` stack consulted by
-        various ``repoze.bfg.threadlocal`` API functions."""
+        various :mod`repoze.bfg.threadlocal` API functions."""
         self.manager.push({'registry':self.registry, 'request':request})
 
     def end(self):
@@ -316,7 +316,7 @@ class Configurator(object):
         """ Add additional settings (beyond the ones passed in as
         ``settings`` to the constructor of this object) to the
         dictionarylike object returned from
-        ``repoze.bfg.settings.get_settings()``.  The ``settings``
+        :func:`repoze.bfg.settings.get_settings`.  The ``settings``
         argument should be a dictionarylike object or ``None``.
         Arbitrary ``kw`` arguments can be passed in to augment the
         settings dict."""
@@ -331,8 +331,8 @@ class Configurator(object):
     def make_wsgi_app(self):
         """ Returns a :mod:`repoze.bfg` WSGI application representing
         the current configuration state and sends a
-        ``repoze.bfg.interfaces.WSGIApplicationCreatedEvent`` event to
-        all listeners."""
+        :class:`repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`
+        event to all listeners."""
         # manager in arglist for testing dep injection only
         from repoze.bfg.router import Router # avoid circdep
         app = Router(self.registry)
@@ -473,7 +473,7 @@ class Configurator(object):
 
         name
 
-          The :term:`view name`.  Read the :ref:`traversal_chapter` to
+          The :term:`view name`.  Read :ref:`traversal_chapter` to
           understand the concept of a view name.
 
         for
@@ -538,7 +538,7 @@ class Configurator(object):
           This value should be a reference to a Python class or
           :term:`interface` that a parent object in the
           :term:`lineage` must provide in order for this view to be
-          found and called.  Your models must be"location-aware" to
+          found and called.  Your models must be "location-aware" to
           use this feature.  See :ref:`location_aware` for more
           information about location-awareness.
 
@@ -987,8 +987,8 @@ class Configurator(object):
     def scan(self, package=None, _info=u''):
         """ Scan a Python package and any of its subpackages for
         objects marked with :term:`configuration decoration` such as
-        ``@bfg_view``.  Any decorated object found will influence the
-        current configuration state.
+        :class:`repoze.bfg.view.bfg_view`.  Any decorated object found
+        will influence the current configuration state.
 
         The ``package`` argument should be a reference to a Python
         package or module object.  If ``package`` is ``None``, the
@@ -1159,10 +1159,11 @@ class Configurator(object):
         access.  If ``permissive`` is false, a nonpermissive
         authorization policy is registered; this policy denies all
         access.  This function is most useful when testing code that
-        uses the ``repoze.bfg.security`` APIs named
-        ``has_permission``, ``authenticated_userid``,
-        ``effective_principals`` and
-        ``principals_allowed_by_permission``.
+        uses the APIs named
+        :func:`repoze.bfg.security.has_permission`,
+        :func:`repoze.bfg.security.authenticated_userid`,
+        :func:`repoze.bfg.security.effective_principals` and
+        `:func:`repoze.bfg.security.principals_allowed_by_permission`.
         """
         from repoze.bfg.testing import DummySecurityPolicy
         policy = DummySecurityPolicy(userid, groupids, permissive)
@@ -1172,15 +1173,15 @@ class Configurator(object):
     def testing_models(self, models):
         """Unit/integration testing helper: registers a dictionary of
         models that can be resolved via
-        ``repoze.bfg.traversal.find_model``.  This is most useful for
-        testing code that wants to call the
-        ``repoze.bfg.traversal.find_model`` API.  The ``find_model``
-        API is called with a path as one of its arguments.  If the
-        dictionary you register when calling this method contains that
-        path as a string key (e.g. ``/foo/bar`` or ``foo/bar``), the
-        corresponding value will be returned to ``find_model`` (and
-        thus to your code) when ``find_model`` is called with an
-        equivalent path string or tuple."""
+        :func:`repoze.bfg.traversal.find_model`.  This is most useful
+        for testing code that wants to call the
+        :func:`repoze.bfg.traversal.find_model` API.  The
+        ``find_model`` API is called with a path as one of its
+        arguments.  If the dictionary you register when calling this
+        method contains that path as a string key (e.g. ``/foo/bar``
+        or ``foo/bar``), the corresponding value will be returned to
+        ``find_model`` (and thus to your code) when ``find_model`` is
+        called with an equivalent path string or tuple."""
         class DummyTraverserFactory:
             def __init__(self, context):
                 self.context = context
@@ -1204,9 +1205,9 @@ class Configurator(object):
         ``event_iface``, that event will be appended to the list.  You
         can then compare the values in the list to expected event
         notifications.  This method is useful when testing code that
-        wants to call ``registry.notify``,
-        ``zope.component.event.dispatch`` or
-        ``zope.component.event.objectEventNotify``.
+        wants to call :meth:`repoze.bfg.registry.Registry.notify`,
+        :func:`zope.component.event.dispatch` or
+        :func:`zope.component.event.objectEventNotify`.
         """
         L = []
         def subscriber(*event):