Roles.

10 files changed, 182 insertions, 164 deletions

diff --git a/repoze/bfg/interfaces.py b/repoze/bfg/interfaces.py
index 553f6775f..c322de2ff 100644
--- a/repoze/bfg/interfaces.py
+++ b/repoze/bfg/interfaces.py
@@ -4,23 +4,24 @@ from zope.interface import Interface
 # public API interfaces
 
 class IAfterTraversal(Interface):
-    """ An event type that is emitted after repoze.bfg completes
-    traversal but before it calls any view code."""
+    """ An event type that is emitted after :mod:`repoze.bfg`
+    completes traversal but before it calls any view code."""
     request = Attribute('The request object')
 
 class INewRequest(Interface):
-    """ An event type that is emitted whenever repoze.bfg begins to
-    process a new request """
+    """ An event type that is emitted whenever :mod:`repoze.bfg`
+    begins to process a new request"""
     request = Attribute('The request object')
     
 class INewResponse(Interface):
-    """ An event type that is emitted whenever any repoze.bfg view
-    returns a response."""
+    """ An event type that is emitted whenever any :mod:`repoze.bfg`
+    view returns a response."""
     response = Attribute('The response object')
 
 class IWSGIApplicationCreatedEvent(Interface):
-    """ Event issued after the application has been created and
-    configured."""
+    """ Event issued when the
+    :meth:`repoze.bfg.configuration.Configurator.make_wsgi_app` method
+    is called."""
     app = Attribute(u"Published application")
 
 # internal interfaces
diff --git a/repoze/bfg/location.py b/repoze/bfg/location.py
index fd3bd3792..7472129d2 100644
--- a/repoze/bfg/location.py
+++ b/repoze/bfg/location.py
@@ -31,11 +31,12 @@ def inside(model1, model2):
 def lineage(model):
     """
     Return a generator representing the :term:`lineage` of the
-    ``model``.  The generator first returns ``model`` unconditionally.
-    Then, if ``model`` supplies a ``__parent__`` attribute, return the
-    object represented by ``model.__parent__``.  If *that* object has
-    a ``__parent__`` attribute, return that object's parent, and so
-    on, until the object being inspected either has no ``__parent__``
+    :term:`model` object implied by the ``model`` argument.  The
+    generator first returns ``model`` unconditionally.  Then, if
+    ``model`` supplies a ``__parent__`` attribute, return the object
+    represented by ``model.__parent__``.  If *that* object has a
+    ``__parent__`` attribute, return that object's parent, and so on,
+    until the object being inspected either has no ``__parent__``
     attribute or which has a ``__parent__`` attribute of ``None``.
     For example, if the object tree is::
 
diff --git a/repoze/bfg/paster.py b/repoze/bfg/paster.py
index d5b03cf38..967d9b72e 100644
--- a/repoze/bfg/paster.py
+++ b/repoze/bfg/paster.py
@@ -44,7 +44,7 @@ def get_app(config_file, name, loadapp=loadapp):
     return app
 
 class BFGShellCommand(Command):
-    """Open an interactive shell with a repoze.bfg app loaded.
+    """Open an interactive shell with a :mod:`repoze.bfg` app loaded.
 
     This command accepts two positional arguments:
 
diff --git a/repoze/bfg/request.py b/repoze/bfg/request.py
index f3443dfa2..32f98eff7 100644
--- a/repoze/bfg/request.py
+++ b/repoze/bfg/request.py
@@ -7,9 +7,11 @@ from webob import Request as WebobRequest
 from repoze.bfg.interfaces import IRequest
 
 def make_request_ascii(event):
-    """ An function that is useful as a ``INewRequest`` :term:`event`
+    """ An function that is useful as a
+    :class:`repoze.bfg.interfaces.INewRequest` :term:`event`
     :term:`subscriber` that causes the request charset to be ASCII so
-    code written before 0.7.0 can continue to work without a change"""
+    code written before :mod:`repoze.bfg` 0.7.0 can continue to work
+    without a change"""
     request = event.request
     request.charset = None
 
diff --git a/repoze/bfg/scripting.py b/repoze/bfg/scripting.py
index 3e743524a..b6f7ed97f 100644
--- a/repoze/bfg/scripting.py
+++ b/repoze/bfg/scripting.py
@@ -2,13 +2,13 @@ from repoze.bfg.request import Request
 
 def get_root(app, request=None):
     """ Return a tuple composed of ``(root, closer)`` when provided a
-    ``repoze.bfg.router.Router`` instance as the ``app`` argument.
-    The ``root`` returned is the application root object.  The
-    ``closer`` returned is a callable (accepting no arguments) that
-    should be called when your scripting application is finished using
-    the root.  If ``request`` is not None, it is used as the request
-    passed to the :mod:`repoze.bfg` application root factory.  A
-    request is constructed and passed to the root factory if
+    :class:`repoze.bfg.router.Router` instance as the ``app``
+    argument.  The ``root`` returned is the application root object.
+    The ``closer`` returned is a callable (accepting no arguments)
+    that should be called when your scripting application is finished
+    using the root.  If ``request`` is not None, it is used as the
+    request passed to the :mod:`repoze.bfg` application root factory.
+    A request is constructed and passed to the root factory if
     ``request`` is None."""
     registry = app.registry
     if request is None:
diff --git a/repoze/bfg/security.py b/repoze/bfg/security.py
index f7ed8e050..e20561e80 100644
--- a/repoze/bfg/security.py
+++ b/repoze/bfg/security.py
@@ -36,13 +36,15 @@ DENY_ALL = (Deny, Everyone, ALL_PERMISSIONS)
 
 def has_permission(permission, context, request):
     """ Provided a permission (a string or unicode object), a context
-    (a model instance) and a request object, return an instance of
-    ``Allowed`` if the permission is granted in this context to the
-    user implied by the request. Return an instance of ``Denied`` if
-    this permission is not granted in this context to this user.  This
-    function delegates to the current authentication and authorization
-    policies.  Return ``Allowed`` unconditionally if no authentication
-    policy has been configured in this application."""
+    (a :term:`model` instance) and a request object, return an
+    instance of :data:`repoze.bfg.security.Allowed` if the permission
+    is granted in this context to the user implied by the
+    request. Return an instance of :mod:`repoze.bfg.security.Denied`
+    if this permission is not granted in this context to this user.
+    This function delegates to the current authentication and
+    authorization policies.  Return
+    :data:`repoze.bfg.security.Allowed` unconditionally if no
+    authentication policy has been configured in this application."""
     try:
         reg = request.registry
     except AttributeError:
@@ -94,13 +96,13 @@ def principals_allowed_by_permission(context, permission):
     in effect, return a sequence of :term:`principal` ids that possess
     the permission in the ``context``.  If no authorization policy is
     in effect, this will return a sequence with the single value
-    representing ``Everyone`` (the special principal identifier
-    representing all principals).
+    :mod:`repoze.bfg.security.Everyone` (the special principal
+    identifier representing all principals).
 
     .. note:: even if an :term:`authorization policy` is in effect,
        some (exotic) authorization policies may not implement the
        required machinery for this function; those will cause a
-       ``NotImplementedError`` exception to be raised when this
+       :exc:`NotImplementedError` exception to be raised when this
        function is invoked.
     """
     reg = get_current_registry()
@@ -115,7 +117,7 @@ def view_execution_permitted(context, request, name=''):
     view using the effective authentication/authorization policies and
     the ``request``.  Return a boolean result.  If no
     :term:`authorization policy` is in effect, or if the view is not
-    protected by a permission, return True."""
+    protected by a permission, return ``True``."""
     try:
         reg = request.registry
     except AttributeError:
@@ -132,10 +134,10 @@ def remember(request, principal, **kw):
     """ Return a sequence of header tuples (e.g. ``[('Set-Cookie',
     'foo=abc')]``) suitable for 'remembering' a set of credentials
     implied by the data passed as ``principal`` and ``*kw`` using the
-    current authentication policy.  Common usage might look like so
-    within the body of a view function (``response`` is assumed to be
-    an WebOb-style response object computed previously by the view
-    code)::
+    current :term:`authentication policy`.  Common usage might look
+    like so within the body of a view function (``response`` is
+    assumed to be an :term:`WebOb` -style :term:`response` object
+    computed previously by the view code)::
 
       from repoze.bfg.security import remember
       headers = remember(request, 'chrism', password='123', max_age='86400')
@@ -161,8 +163,8 @@ def forget(request):
     'foo=abc')]``) suitable for 'forgetting' the set of credentials
     possessed by the currently authenticated user.  A common usage
     might look like so within the body of a view function
-    (``response`` is assumed to be an WebOb-style response object
-    computed previously by the view code)::
+    (``response`` is assumed to be an :term:`WebOb` -style
+    :term:`response` object computed previously by the view code)::
 
       from repoze.bfg.security import forget
       headers = forget(request)
@@ -202,18 +204,18 @@ class PermitsResult(int):
 
 class Denied(PermitsResult):
     """ An instance of ``Denied`` is returned when a security-related
-    API or other ``repoze.bfg`` code denies an action unlrelated to an
-    ACL check.  It evaluates equal to all boolean false types.  It has
-    an attribute named ``msg`` describing the circumstances for the
-    deny."""
+    API or other :mod:`repoze.bfg` code denies an action unlrelated to
+    an ACL check.  It evaluates equal to all boolean false types.  It
+    has an attribute named ``msg`` describing the circumstances for
+    the deny."""
     boolval = 0
 
 class Allowed(PermitsResult):
     """ An instance of ``Allowed`` is returned when a security-related
-    API or other ``repoze.bfg`` code allows an action unrelated to an
-    ACL check.  It evaluates equal to all boolean true types.  It has
-    an attribute named ``msg`` describing the circumstances for the
-    allow."""
+    API or other :mod:`repoze.bfg` code allows an action unrelated to
+    an ACL check.  It evaluates equal to all boolean true types.  It
+    has an attribute named ``msg`` describing the circumstances for
+    the allow."""
     boolval = 1
 
 class ACLPermitsResult(int):
@@ -256,7 +258,7 @@ class ACLDenied(ACLPermitsResult):
     boolval = 0
 
 class ACLAllowed(ACLPermitsResult):
-    """ An instance of ``ACLDenied`` represents that a security check
+    """ An instance of ``ACLAllowed`` represents that a security check
     made explicitly against ACL was allowed.  It evaluates equal to
     all boolean true types.  It also has attributes which indicate
     which acl, ace, permission, principals, and context were involved
diff --git a/repoze/bfg/settings.py b/repoze/bfg/settings.py
index 500c4503c..069d25e6c 100644
--- a/repoze/bfg/settings.py
+++ b/repoze/bfg/settings.py
@@ -9,7 +9,7 @@ from repoze.bfg.threadlocal import get_current_registry
 class Settings(dict):
     """ Deployment settings.  Update application settings (usually
     from PasteDeploy keywords) with framework-specific key/value pairs
-    (e.g. find 'BFG_DEBUG_AUTHORIZATION' in os.environ and jam into
+    (e.g. find ``BFG_DEBUG_AUTHORIZATION`` in os.environ and jam into
     keyword args)."""
     implements(ISettings)
     # _environ_ is dep inj for testing
@@ -57,11 +57,12 @@ def get_settings():
     """
     Return a 'settings' object for the current application.  A
     'settings' object is a dictionary-like object that contains
-    key/value pairs based on the dictionary passed as the ``options``
-    argument to the ``repoze.bfg.router.make_app`` API.
+    key/value pairs based on the dictionary passed as the ``settings``
+    argument to the :class:`repoze.bfg.configuration.Configurator`
+    constructor or the :func:`repoze.bfg.router.make_app` API.
 
-    For backwards compatibility, dictionary keys can also be looked up
-    as attributes of the settings object.
+    .. note:: For backwards compatibility, dictionary keys can also be
+       looked up as attributes of the settings object.
     """
     reg = get_current_registry()
     return reg.queryUtility(ISettings)
diff --git a/repoze/bfg/traversal.py b/repoze/bfg/traversal.py
index 051a4c34c..8003de598 100644
--- a/repoze/bfg/traversal.py
+++ b/repoze/bfg/traversal.py
@@ -28,16 +28,18 @@ def find_root(model):
 
 def find_model(model, path):
     """ Given a model object and a string or tuple representing a path
-    (such as the return value of ``model_path`` or
-    ``model_path_tuple``), return a context in this application's
-    model graph at the specified path.  The model passed in *must* be
-    :term:`location`-aware.  If the path cannot be resolved (if the
-    respective node in the graph does not exist), a KeyError will be
-    raised.
-
-    This function is the logical inverse of ``model_path`` and
-    ``model_path_tuple``; it can resolve any path string or tuple
-    generated by ``model_path`` or ``model_path_tuple``.
+    (such as the return value of
+    :func:`repoze.bfg.traversal.model_path` or
+    :func:`repoze.bfg.traversal.model_path_tuple`), return a context
+    in this application's model graph at the specified path.  The
+    model passed in *must* be :term:`location`-aware.  If the path
+    cannot be resolved (if the respective node in the graph does not
+    exist), a :exc:`KeyError` will be raised.
+
+    This function is the logical inverse of
+    :func:`repoze.bfg.traversal.model_path` and
+    :func:`repoze.bfg.traversal.model_path_tuple`; it can resolve any
+    path string or tuple generated by either of those functions.
 
     Rules for passing a *string* as the ``path`` argument: if the
     first character in the path string is the with the ``/``
@@ -49,11 +51,11 @@ def find_model(model, path):
     empty string is passed as ``path``, the ``model`` passed in will
     be returned.  Model path strings must be escaped in the following
     manner: each Unicode path segment must be encoded as UTF-8 and as
-    each path segment must escaped via Python's ``urllib.quote``.  For
-    example, ``/path/to%20the/La%20Pe%C3%B1a`` (absolute) or
-    ``to%20the/La%20Pe%C3%B1a`` (relative).  The ``model_path``
-    function generates strings which follow these rules (albeit only
-    absolute ones).
+    each path segment must escaped via Python's :mod:`urllib.quote`.
+    For example, ``/path/to%20the/La%20Pe%C3%B1a`` (absolute) or
+    ``to%20the/La%20Pe%C3%B1a`` (relative).  The
+    :func:`repoze.bfg.traversal.model_path` function generates strings
+    which follow these rules (albeit only absolute ones).
 
     Rules for passing a *tuple* as the ``path`` argument: if the first
     element in the path tuple is the empty string (for example ``('',
@@ -67,7 +69,8 @@ def find_model(model, path):
     URL-quoting or UTF-8-encoding of individual path segments within
     the tuple is required (each segment may be any string or unicode
     object representing a model name).  Model path tuples generated by
-    ``model_path_tuple`` can always be resolved by ``find_model``.
+    :func:`repoze.bfg.traversal.model_path_tuple` can always be
+    resolved by ``find_model``.
     """
     D = traverse(model, path)
     view_name = D['view_name']
@@ -107,12 +110,12 @@ def model_path(model, *elements):
 
     Model path strings returned will be escaped in the following
     manner: each unicode path segment will be encoded as UTF-8 and
-    each path segment will be escaped via Python's ``urllib.quote``.
+    each path segment will be escaped via Python's :mod:`urllib.quote`.
     For example, ``/path/to%20the/La%20Pe%C3%B1a``.
 
-    This function is a logical inverse of ``find_model``: it can be
-    used to generate path references that can later be resolved via
-    ``find_model``.
+    This function is a logical inverse of
+    :mod:`repoze.bfg.traversal.find_model`: it can be used to generate
+    path references that can later be resolved via that function.
 
     The ``model`` passed in *must* be :term:`location`-aware.
 
@@ -124,8 +127,9 @@ def model_path(model, *elements):
               safety checking of model names is performed.  For
               instance, if one of the models in your graph has a
               ``__name__`` which (by error) is a dictionary, the
-              ``model_path`` function will attempt to append it to a
-              string and it will cause a TypeError.
+              :func:`repoze.bfg.traversal.model_path` function will
+              attempt to append it to a string and it will cause a
+              :exc:`TypeError`.
 
     .. note:: The the :term:`root` model *must* have a ``__name__``
               attribute with a value of either ``None`` or the empty
@@ -141,8 +145,8 @@ def model_path(model, *elements):
 def traverse(model, path):
     """Given a model object as ``model`` and a string or tuple
     representing a path as ``path`` (such as the return value of
-    ``repoze.bfg.traversal.model_path`` or
-    ``repoze.bfg.traversal.model_path_tuple`` or the value of
+    :func:`repoze.bfg.traversal.model_path` or
+    :func:`repoze.bfg.traversal.model_path_tuple` or the value of
     ``request.environ['PATH_INFO']``), return a dictionary with the
     keys ``context``, ``root``, ``view_name``, ``subpath``,
     ``traversed``, ``virtual_root``, and ``virtual_root_path``.
@@ -210,9 +214,9 @@ def traverse(model, path):
       to find the ``virtual_root`` object (e.g. if virtual hosting is
       not in effect), the ``traversed`` value will be the empty list.
       If url dispatch was used to find the ``model``, this will be
-      None.
+      ``None``.
 
-    If the path cannot be resolved, a ``KeyError`` will be raised.
+    If the path cannot be resolved, a :exc:`KeyError` will be raised.
 
     Rules for passing a *string* as the ``path`` argument: if the
     first character in the path string is the with the ``/``
@@ -224,11 +228,11 @@ def traverse(model, path):
     empty string is passed as ``path``, the ``model`` passed in will
     be returned.  Model path strings must be escaped in the following
     manner: each Unicode path segment must be encoded as UTF-8 and as
-    each path segment must escaped via Python's ``urllib.quote``.  For
-    example, ``/path/to%20the/La%20Pe%C3%B1a`` (absolute) or
-    ``to%20the/La%20Pe%C3%B1a`` (relative).  The ``model_path``
-    function generates strings which follow these rules (albeit only
-    absolute ones).
+    each path segment must escaped via Python's :mod:`urllib.quote`.
+    For example, ``/path/to%20the/La%20Pe%C3%B1a`` (absolute) or
+    ``to%20the/La%20Pe%C3%B1a`` (relative).  The
+    :func:`repoze.bfg.traversal.model_path` function generates strings
+    which follow these rules (albeit only absolute ones).
 
     Rules for passing a *tuple* as the ``path`` argument: if the first
     element in the path tuple is the empty string (for example ``('',
@@ -241,17 +245,16 @@ def traverse(model, path):
     ``path``, the ``model`` passed in itself will be returned.  No
     URL-quoting or UTF-8-encoding of individual path segments within
     the tuple is required (each segment may be any string or unicode
-    object representing a model name).  Model path tuples generated by
-    ``model_path_tuple`` can always be resolved by ``find_model``.
+    object representing a model name).
 
     Explanation of the conversion of ``path`` segment values to
     Unicode during traversal: Each segment is URL-unquoted, and
     decoded into Unicode. Each segment is assumed to be encoded using
-    the UTF-8 encoding (or a subset, such as ASCII); a ``TypeError``
-    is raised if a segment cannot be decoded.  If a segment name is
-    empty or if it is ``.``, it is ignored.  If a segment name is
-    ``..``, the previous segment is deleted, and the ``..`` is
-    ignored.  As a result of this process, the return values
+    the UTF-8 encoding (or a subset, such as ASCII); a
+    :exc:`TypeError` is raised if a segment cannot be decoded.  If a
+    segment name is empty or if it is ``.``, it is ignored.  If a
+    segment name is ``..``, the previous segment is deleted, and the
+    ``..`` is ignored.  As a result of this process, the return values
     ``view_name``, each element in the ``subpath``, each element in
     ``traversed``, and each element in the ``virtual_root_path`` will
     be Unicode as opposed to a string, and will be URL-decoded.
@@ -292,9 +295,9 @@ def model_path_tuple(model, *elements):
     leading empty string element in a path tuple represents that the
     path is absolute).
 
-    This function is a logical inverse of ``find_model``: it can be
-    used to generate path references that can later be resolved via
-    ``find_model``.
+    This function is a logical inverse of
+    :func:`repoze.bfg.traversal.find_model`: it can be used to
+    generate path references that can later be resolved that function.
 
     The ``model`` passed in *must* be :term:`location`-aware.
 
@@ -364,13 +367,14 @@ def virtual_root(model, request):
 def traversal_path(path):
     """ Given a ``PATH_INFO`` string (slash-separated path segments),
     return a tuple representing that path which can be used to
-    traverse a graph.  The PATH_INFO is split on slashes, creating a
-    list of segments.  Each segment is URL-unquoted, and decoded into
-    Unicode. Each segment is assumed to be encoded using the UTF-8
-    encoding (or a subset, such as ASCII); a TypeError is raised if a
-    segment cannot be decoded.  If a segment name is empty or if it is
-    ``.``, it is ignored.  If a segment name is ``..``, the previous
-    segment is deleted, and the ``..`` is ignored.  Examples:
+    traverse a graph.  The ``PATH_INFO`` is split on slashes, creating
+    a list of segments.  Each segment is URL-unquoted, and decoded
+    into Unicode. Each segment is assumed to be encoded using the
+    UTF-8 encoding (or a subset, such as ASCII); a :exc:`TypeError` is
+    raised if a segment cannot be decoded.  If a segment name is empty
+    or if it is ``.``, it is ignored.  If a segment name is ``..``,
+    the previous segment is deleted, and the ``..`` is ignored.
+    Examples:
 
     ``/``
 
@@ -405,15 +409,17 @@ def traversal_path(path):
         (u'archives', u'<unprintable unicode>')
 
     .. note:: This function does not generate the same type of tuples
-              that ``model_path_tuple`` does.  In particular, the
-              leading empty string is not present in the tuple it
-              returns, unlike tuples returned by ``model_path_tuple``.
-              As a result, tuples generated by ``traversal_path`` are
-              not resolveable by the ``find_model`` API.
+              that :func:`repoze.bfg.traversal.model_path_tuple` does.
+              In particular, the leading empty string is not present
+              in the tuple it returns, unlike tuples returned by
+              :func:`repoze.bfg.traversal.model_path_tuple`.  As a
+              result, tuples generated by ``traversal_path`` are not
+              resolveable by the
+              :func:`repoze.bfg.traversal.find_model` API.
               ``traversal_path`` is a function mostly used by the
               internals of :mod:`repoze.bfg` and by people writing
               their own traversal machinery, as opposed to users
-              writing applications in BFG.
+              writing applications in :mod:`repoze.bfg`.
     """
     path = path.rstrip('/')
     path = path.lstrip('/')
@@ -441,10 +447,10 @@ def quote_path_segment(segment):
     ``segment`` passed in is a unicode object, it is converted to a
     UTF-8 string, then it is URL-quoted using Python's
     ``urllib.quote``.  If the ``segment`` passed in is a string, it is
-    URL-quoted using Python's ``urllib.quote``.  If the segment passed
-    in is not a string or unicode object, an error will be raised.
-    The return value of ``quote_path_segment`` is always a string,
-    never Unicode.
+    URL-quoted using Python's :mod:`urllib.quote`.  If the segment
+    passed in is not a string or unicode object, an error will be
+    raised.  The return value of ``quote_path_segment`` is always a
+    string, never Unicode.
 
     .. note:: The return value for each segment passed to this
               function is cached in a module-scope dictionary for
@@ -476,7 +482,8 @@ def quote_path_segment(segment):
 class ModelGraphTraverser(object):
     """ A model graph traverser that should be used (for speed) when
     every object in the graph supplies a ``__name__`` and
-    ``__parent__`` attribute (ie. every object 'provides ILocation') ."""
+    ``__parent__`` attribute (ie. every object in the graph is
+    :term:`location` aware) ."""
 
     implements(ITraverser)
 
diff --git a/repoze/bfg/url.py b/repoze/bfg/url.py
index 741fab9ce..1d4760842 100644
--- a/repoze/bfg/url.py
+++ b/repoze/bfg/url.py
@@ -24,7 +24,7 @@ def route_url(route_name, request, *elements, **kw):
     after it is generated.
     
     Use keyword arguments to supply values which match any dynamic
-    path elements in the route definition.  Raises a ``KeyError``
+    path elements in the route definition.  Raises a :exc:`KeyError`
     exception if the URL cannot be generated for any reason (not
     enough arguments, for example).
 
@@ -52,21 +52,21 @@ def route_url(route_name, request, *elements, **kw):
 
     If a keyword argument ``_query`` is present, it will used to
     compose a query string that will be tacked on to the end of the
-    URL.  The value of ``_query`` must be a sequence of two-tuples *or*
-    a data structure with an ``.items()`` method that returns a
+    URL.  The value of ``_query`` must be a sequence of two-tuples
+    *or* a data structure with an ``.items()`` method that returns a
     sequence of two-tuples (presumably a dictionary).  This data
     structure will be turned into a query string per the documentation
-    of ``repoze.url.urlencode`` function.  After the query data is
-    turned into a query string, a leading ``?`` is prepended, and the
-    the resulting string is appended to the generated URL.
+    of :func:`repoze.bfg.encode.urlencode` function.  After the query
+    data is turned into a query string, a leading ``?`` is prepended,
+    and the the resulting string is appended to the generated URL.
 
     .. note:: Python data structures that are passed as ``_query``
               which are sequences or dictionaries are turned into a
               string under the same rules as when run through
-              urllib.urlencode with the ``doseq`` argument equal to
-              ``True``.  This means that sequences can be passed as
-              values, and a k=v pair will be placed into the query
-              string for each value.
+              :func:`urllib.urlencode` with the ``doseq`` argument
+              equal to ``True``.  This means that sequences can be
+              passed as values, and a k=v pair will be placed into the
+              query string for each value.
 
     If a keyword argument ``_anchor`` is present, its string
     representation will be used as a named anchor in the generated URL
@@ -84,9 +84,9 @@ def route_url(route_name, request, *elements, **kw):
     element will always follow the query element,
     e.g. ``http://example.com?foo=1#bar``.
 
-    This function raises a ``KeyError`` if the URL cannot be generated
-    due to missing replacement names.  Extra replacement names are
-    ignored.
+    This function raises a :exc:`KeyError` if the URL cannot be
+    generated due to missing replacement names.  Extra replacement
+    names are ignored.
     """
     try:
         reg = request.registry
@@ -123,7 +123,7 @@ def model_url(model, request, *elements, **kw):
     object based on the ``wsgi.url_scheme``, ``HTTP_HOST`` or
     ``SERVER_NAME`` in the ``request``, plus any ``SCRIPT_NAME``.  The
     overall result of this function is always a UTF-8 encoded string
-    (never unicode).
+    (never Unicode).
 
     Examples::
 
@@ -144,9 +144,9 @@ def model_url(model, request, *elements, **kw):
                                    http://example.com/a.html#abc
 
     Any positional arguments passed in as ``elements`` must be strings
-    or unicode objects.  These will be joined by slashes and appended
+    or Unicode objects.  These will be joined by slashes and appended
     to the generated model URL.  Each of the elements passed in is
-    URL-quoted before being appended; if any element is unicode, it
+    URL-quoted before being appended; if any element is Unicode, it
     will converted to a UTF-8 bytestring before being URL-quoted.
 
     .. warning:: if no ``elements`` arguments are specified, the model
@@ -167,10 +167,10 @@ def model_url(model, request, *elements, **kw):
     .. note:: Python data structures that are passed as ``query``
               which are sequences or dictionaries are turned into a
               string under the same rules as when run through
-              urllib.urlencode with the ``doseq`` argument equal to
-              ``True``.  This means that sequences can be passed as
-              values, and a k=v pair will be placed into the query
-              string for each value.
+              :func:`urllib.urlencode` with the ``doseq`` argument
+              equal to ``True``.  This means that sequences can be
+              passed as values, and a k=v pair will be placed into the
+              query string for each value.
 
     If a keyword argument ``anchor`` is present, its string
     representation will be used as a named anchor in the generated URL
@@ -234,8 +234,9 @@ def static_url(path, request, **kw):
     """
     Generates a fully qualified URL for a static :term:`resource`.
     The resource must live within a location defined via the
-    ``add_static_view`` :term:`configuration declaration` or the
-    ``<static>`` ZCML directive (see :ref:`static_resources_section`).
+    :meth:`repoze.bfg.configuration.Configurator.add_static_view`
+    :term:`configuration declaration` or the ``<static>`` ZCML
+    directive (see :ref:`static_resources_section`).
 
     Example::
 
@@ -248,19 +249,19 @@ def static_url(path, request, **kw):
     a URL should be generated for.  The ``path`` may be either a
     relative path (e.g. ``static/foo.css``) or a :term:`resource
     specification` (e.g. ``mypackage:static/foo.css``).  A ``path``
-    may not be an absolute filesystem path (a ValueError will be
-    raised if this function is supplied with an absolute path).
+    may not be an absolute filesystem path (a :exc:`ValueError` will
+    be raised if this function is supplied with an absolute path).
 
     The ``request`` argument should be a :term:`request` object.
 
     The purpose of the ``**kw`` argument is the same as the purpose of
-    the ``route_url`` ``**kw`` argument.  See the documentation for
-    that function to understand the arguments which you can provide to
-    it.  However, typically, you don't need to pass anything as
-    ``*kw`` when generating a static resource URL.
+    the :func:`repoze.bfg.url.route_url` ``**kw`` argument.  See the
+    documentation for that function to understand the arguments which
+    you can provide to it.  However, typically, you don't need to pass
+    anything as ``*kw`` when generating a static resource URL.
 
-    This function raises a ValueError if a static view definition
-    cannot be found which matches the path specification.
+    This function raises a :exc:`ValueError` if a static view
+    definition cannot be found which matches the path specification.
 
     .. note:: This feature is new in :mod:`repoze.bfg` 1.1.
     """
diff --git a/repoze/bfg/wsgi.py b/repoze/bfg/wsgi.py
index 26229836a..c576253b3 100644
--- a/repoze/bfg/wsgi.py
+++ b/repoze/bfg/wsgi.py
@@ -2,11 +2,11 @@ from repoze.bfg.compat import wraps
 from repoze.bfg.traversal import quote_path_segment
 
 def wsgiapp(wrapped):
-    """ Decorator to turn a WSGI application into a repoze.bfg view
-    callable.  This decorator differs from the ``wsgiapp2`` decorator
-    inasmuch as fixups of ``PATH_INFO`` and ``SCRIPT_NAME`` within the
-    WSGI environment *are not* performed before the application is
-    invoked.
+    """ Decorator to turn a WSGI application into a :mod:`repoze.bfg`
+    :term:`view callable`.  This decorator differs from the
+    :func:`repoze.bfg.wsgi.wsgiapp2` decorator inasmuch as fixups of
+    ``PATH_INFO`` and ``SCRIPT_NAME`` within the WSGI environment *are
+    not* performed before the application is invoked.
 
     E.g., the following in a ``views.py`` module::
 
@@ -24,14 +24,16 @@ def wsgiapp(wrapped):
           name="hello_world.txt"
         />
 
-    Or the following :term:`Configurator` ``add_view`` method call::
+    Or the following call to
+    :meth:`repoze.bfg.configuration.Configurator.add_view`::
 
         from views import hello_world
         config.add_view(hello_world, name='hello_world.txt')
 
-    The wsgiapp decorator will convert the result of the WSGI
-    application to a Response and return it to repoze.bfg as if the
-    WSGI app were a repoze.bfg view.  
+    The ``wsgiapp`` decorator will convert the result of the WSGI
+    application to a :term:`Response` and return it to
+    :mod:`repoze.bfg` as if the WSGI app were a :mod:`repoze.bfg`
+    view.
     
     """
     def decorator(context, request):
@@ -39,11 +41,11 @@ def wsgiapp(wrapped):
     return wraps(wrapped)(decorator) # grokkability
 
 def wsgiapp2(wrapped):
-    """ Decorator to turn a WSGI application into a repoze.bfg view
-    callable.  This decorator differs from the ``wsgiapp`` decorator
-    inasmuch as fixups of ``PATH_INFO`` and ``SCRIPT_NAME`` within the
-    WSGI environment *are* performed before the application is
-    invoked.
+    """ Decorator to turn a WSGI application into a :mod:`repoze.bfg`
+    view callable.  This decorator differs from the
+    :func:`repoze.bfg.wsgi.wsgiapp` decorator inasmuch as fixups of
+    ``PATH_INFO`` and ``SCRIPT_NAME`` within the WSGI environment
+    *are* performed before the application is invoked.
 
     E.g. the following in a ``views.py`` module::
 
@@ -61,17 +63,18 @@ def wsgiapp2(wrapped):
           name="hello_world.txt"
         />
 
-    Or the following :term:`Configurator` ``add_view`` method call::
+    Or the following call to
+    :meth:`repoze.bfg.configuration.Configurator.add_view`::
 
         from views import hello_world
         config.add_view(hello_world, name='hello_world.txt')
 
-    The wsgiapp2 decorator will convert the result of the WSGI
-    application to a Response and return it to repoze.bfg as if the
-    WSGI app were a repoze.bfg view.  The ``SCRIPT_NAME`` and
-    ``PATH_INFO`` values present in the WSGI environment are fixed up
-    before the application is invoked.
-    """
+    The ``wsgiapp2`` decorator will convert the result of the WSGI
+    application to a Response and return it to :mod:`repoze.bfg` as if
+    the WSGI app were a :mod:`repoze.bfg` view.  The ``SCRIPT_NAME``
+    and ``PATH_INFO`` values present in the WSGI environment are fixed
+    up before the application is invoked.  """
+    
     def decorator(context, request):
         traversed = request.traversed
         vroot_path = request.virtual_root_path or ()