Roles.

1 files changed, 99 insertions, 92 deletions

diff --git a/docs/whatsnew-1.2.rst b/docs/whatsnew-1.2.rst
index 4332c9948..cae307c14 100644
--- a/docs/whatsnew-1.2.rst
+++ b/docs/whatsnew-1.2.rst
@@ -33,7 +33,7 @@ The simplest possible :mod:`repoze.bfg` application is now:
      :linenos:
 
      from webob import Response
-     from wsgiref import simple_server
+     from paste.httpserver import serve
      from repoze.bfg.configuration import Configurator
 
      def hello_world(request):
@@ -45,7 +45,7 @@ The simplest possible :mod:`repoze.bfg` application is now:
          config.add_view(hello_world)
          config.end()
          app = config.make_wsgi_app()
-         simple_server.make_server('', 8080, app).serve_forever()
+         serve(app)
 
 For an introduction to imperative-mode configuration, see
 :ref:`configuration_narr`.
@@ -53,47 +53,49 @@ For an introduction to imperative-mode configuration, see
 Minor Miscellaneous Feature Additions
 -------------------------------------
 
-- The ``repoze.bfg.testing.setUp`` function now accepts three extra
-  optional keyword arguments: ``registry``, ``request`` and
+- The :func:`repoze.bfg.testing.setUp` function now accepts three
+  extra optional keyword arguments: ``registry``, ``request`` and
   ``hook_zca``.
 
   If the ``registry`` argument is not ``None``, the argument will be
   treated as the registry that is set as the "current registry" (it
-  will be returned by ``repoze.bfg.threadlocal.get_current_registry``)
-  for the duration of the test.  If the ``registry`` argument is
-  ``None`` (the default), a new registry is created and used for the
-  duration of the test.
+  will be returned by
+  :func:`repoze.bfg.threadlocal.get_current_registry`) for the
+  duration of the test.  If the ``registry`` argument is ``None`` (the
+  default), a new registry is created and used for the duration of the
+  test.
 
   The value of the ``request`` argument is used as the "current
   request" (it will be returned by
-  ``repoze.bfg.threadlocal.get_current_request``) for the duration of
-  the test; it defaults to ``None``.
+  :func:`repoze.bfg.threadlocal.get_current_request`) for the duration
+  of the test; it defaults to ``None``.
 
   If ``hook_zca`` is ``True`` (the default), the
-  ``zope.component.getSiteManager`` function will be hooked with a
+  :func:`zope.component.getSiteManager` function will be hooked with a
   function that returns the value of ``registry`` (or the
   default-created registry if ``registry`` is ``None``) instead of the
-  registry returned by ``zope.component.getGlobalSiteManager``,
+  registry returned by :func:`zope.component.getGlobalSiteManager`,
   causing the Zope Component Architecture API (``getSiteManager``,
   ``getAdapter``, ``getUtility``, and so on) to use the testing
   registry instead of the global ZCA registry.
 
-- The ``repoze.bfg.testing.tearDown`` function now accepts an
+- The :func:`repoze.bfg.testing.tearDown` function now accepts an
   ``unhook_zca`` argument.  If this argument is ``True`` (the
-  default), ``zope.component.getSiteManager.reset()`` will be called.
-  This will cause the result of the ``zope.component.getSiteManager``
-  function to be the global ZCA registry (the result of
-  ``zope.component.getGlobalSiteManager``) once again.
+  default), :func:`zope.component.getSiteManager.reset` will be
+  called.  This will cause the result of the
+  :func:`zope.component.getSiteManager` function to be the global ZCA
+  registry (the result of :func:`zope.component.getGlobalSiteManager`)
+  once again.
 
-- ``repoze.bfg.testing.DummyModel`` now accepts a new constructor
+- :class:`repoze.bfg.testing.DummyModel` now accepts a new constructor
   keyword argument: ``__provides__``.  If this constructor argument is
   provided, it should be an interface or a tuple of interfaces.  The
   resulting model will then provide these interfaces (they will be
   attached to the constructed model via
-  ``zope.interface.alsoProvides``).
+  :func:`zope.interface.alsoProvides`).
 
-- When the ``repoze.bfg.exceptions.NotFound`` or
-  ``repoze.bfg.exceptions.Forbidden`` error is raised from within a
+- When the :exc:`repoze.bfg.exceptions.NotFound` or
+  :exc:`repoze.bfg.exceptions.Forbidden` error is raised from within a
   custom :term:`root factory` or the factory of a :term:`route`, the
   appropriate response is sent to the requesting user agent (the
   result of the notfound view or the forbidden view, respectively).
@@ -106,76 +108,77 @@ Minor Miscellaneous Feature Additions
 Backwards Incompatibilites
 --------------------------
 
-- Unit tests which use ``zope.testing.cleanup.cleanUp`` for the
+- Unit tests which use :func:`zope.testing.cleanup.cleanUp` for the
   purpose of isolating tests from one another may now begin to fail
   due to lack of isolation between tests.
 
   Here's why: In repoze.bfg 1.1 and prior, the registry returned by
-  ``repoze.bfg.threadlocal.get_current_registry`` when no other
+  :func:`repoze.bfg.threadlocal.get_current_registry` when no other
   registry had been pushed on to the threadlocal stack was the
-  ``zope.component.globalregistry.base`` global registry (aka the
-  result of ``zope.component.getGlobalSiteManager()``).  In repoze.bfg
-  1.2+, however, the registry returned in this situation is the new
-  module-scope ``repoze.bfg.registry.global_registry`` object.  The
-  ``zope.testing.cleanup.cleanUp`` function clears the
-  ``zope.component.globalregistry.base`` global registry
+  :data:`zope.component.globalregistry.base` global registry (aka the
+  result of :func:`zope.component.getGlobalSiteManager()`).  In
+  :mod:`repoze.bfg` 1.2+, however, the registry returned in this
+  situation is the new module-scope
+  :data:`repoze.bfg.registry.global_registry` object.  The
+  :func:`zope.testing.cleanup.cleanUp` function clears the
+  :data:`zope.component.globalregistry.base` global registry
   unconditionally.  However, it does not know about the
-  ``repoze.bfg.registry.global_registry`` object, so it does not clear
-  it.
+  :data:`repoze.bfg.registry.global_registry` object, so it does not
+  clear it.
 
-  If you use the ``zope.testing.cleanup.cleanUp`` function in the
+  If you use the :func:`zope.testing.cleanup.cleanUp` function in the
   ``setUp`` of test cases in your unit test suite instead of using the
-  (more correct as of 1.1) ``repoze.bfg.testing.setUp``, you will need
-  to replace all calls to ``zope.testing.cleanup.cleanUp`` with a call
-  to ``repoze.bfg.testing.setUp``.
+  (more correct as of 1.1) :func:`repoze.bfg.testing.setUp`, you will
+  need to replace all calls to :func:`zope.testing.cleanup.cleanUp`
+  with a call to :func:`repoze.bfg.testing.setUp`.
 
-  If replacing all calls to ``zope.testing.cleanup.cleanUp`` with a
-  call to ``repoze.bfg.testing.setUp`` is infeasible, you can put the
-  below-mentioned bit of code somewhere that is executed exactly
-  **once** (*not* for each test in a test suite).  Placing this in the
-  ``__init__.py`` of your package or the ``__init__.py`` of a
-  ``tests`` subpackage would be a reasonable place)::
+  If replacing all calls to :func:`zope.testing.cleanup.cleanUp` with
+  a call to :func:`repoze.bfg.testing.setUp` is infeasible, you can
+  put the below-mentioned bit of code somewhere that is executed
+  exactly **once** (*not* for each test in a test suite).  Placing
+  this in the ``__init__.py`` of your package or the ``__init__.py``
+  of a ``tests`` subpackage would be a reasonable place)::
 
     import zope.testing.cleanup
     from repoze.bfg.testing import setUp
     zope.testing.cleanup.addCleanUp(setUp)
 
 - When there is no "current registry" in the
-  ``repoze.bfg.threadlocal.manager`` threadlocal data structure (this
-  is the case when there is no "current request" or we're not in the
-  midst of a ``r.b.testing.setUp`` or
-  ``r.b.configuration.Configurator.begin`` bounded unit test), the
-  ``.get`` method of the manager returns a data structure containing a
-  *global* registry.  In previous releases, this function returned the
-  global Zope "base" registry: the result of
-  ``zope.component.getGlobalSiteManager``, which is an instance of the
-  ``zope.component.registry.Component`` class.  In this release,
-  however, the global registry returns a globally importable instance
-  of the ``repoze.bfg.registry.Registry`` class.  This registry
-  instance can always be imported as
-  ``repoze.bfg.registry.global_registry``.
+  :data:`repoze.bfg.threadlocal.manager` threadlocal data structure
+  (this is the case when there is no "current request" or we're not in
+  the midst of a :func:`repoze.bfg.testing.setUp` or
+  :meth:`repoze.bfg.configuration.Configurator.begin` bounded unit
+  test), the ``.get`` method of the manager returns a data structure
+  containing a *global* registry.  In previous releases, this function
+  returned the global Zope "base" registry: the result of
+  :func:`zope.component.getGlobalSiteManager`, which is an instance of
+  the :class:`zope.component.registry.Component` class.  In this
+  release, however, the global registry returns a globally importable
+  instance of the :class:`repoze.bfg.registry.Registry` class.  This
+  registry instance can always be imported as
+  :data:`repoze.bfg.registry.global_registry`.
 
   Effectively, this means that when you call
-  ``repoze.bfg.threadlocal.get_current_registry`` when no "real"
+  :func:`repoze.bfg.threadlocal.get_current_registry` when no "real"
   request or bounded unit test is in effect, you will always get back
   the global registry that lives in
-  ``repoze.bfg.registry.global_registry``.  It also means that
-  :mod:`repoze.bfg` APIs that *call* ``get_current_registry`` will use
-  this registry.
+  :data:`repoze.bfg.registry.global_registry`.  It also means that
+  :mod:`repoze.bfg` APIs that *call*
+  :func:`repoze.bfg.threadlocal.get_current_registry` will use this
+  registry.
 
   This change was made because :mod:`repoze.bfg` now expects the
   registry it uses to have a slightly different API than a bare
-  instance of ``zope.component.registry.Components``.
+  instance of :class:`zope.component.registry.Components`.
 
 - View registration no longer registers a
-  ``repoze.bfg.interfaces.IViewPermission`` adapter (it is no longer
-  checked by the framework; since 1.1, views have been responsible for
-  providing their own security).
+  :class:`repoze.bfg.interfaces.IViewPermission` adapter (it is no
+  longer checked by the framework; since 1.1, views have been
+  responsible for providing their own security).
 
-- The ``repoze.bfg.router.make_app`` callable no longer accepts the
-  ``authentication_policy`` nor the ``authorization_policy``
-  arguments.  This feature was deprecated in version 1.0 and has been
-  removed.
+- The :func:`repoze.bfg.router.make_app` callable no longer accepts an
+  ``authentication_policy`` nor an ``authorization_policy`` argument.
+  These features were deprecated in version 1.0 and have been removed.
 
 - Obscure: the machinery which configured views with a
   ``request_type`` *and* a ``route_name`` would ignore the request
@@ -198,21 +201,24 @@ Backwards Incompatibilites
   file="meta.zcml"/>`` in the ZCML of a ``repoze.bfg`` application.  A
   ZCML conflict error will be raised if your ZCML does so.  This
   shouldn't be an issue for "normal" installations; it has always been
-  the responsibility of the ``repoze.bfg.includes`` ZCML to include
+  the responsibility of the :mod:`repoze.bfg.includes` ZCML to include
   this file in the past; it now just doesn't.
 
-- The ``repoze.bfg.testing.zcml_configure`` API was removed.  Use
-  the ``Configurator.load_zcml`` API instead.
+- The :func:`repoze.bfg.testing.zcml_configure` API was removed.  Use
+  the :meth:`repoze.bfg.configuration.Configurator.load_zcml` API
+  instead.
 
-- The ``repoze.bfg.templating`` module has been removed; it had been
-  deprecated in 1.1 and hasn't possessed any APIs since before 1.0.
+- The :mod:`repoze.bfg.templating` module has been removed; it had
+  been deprecated in 1.1 and hasn't possessed any APIs since before
+  1.0.
 
 Deprecations and Behavior Differences
 -------------------------------------
 
-- If you disuse the legacy ``repoze.bfg.router.make_app`` function in
-  favor of ``repoze.bfg.configuration.Configurator.make_wsgi_app``,
-  and you also want to use the "global" ZCA API (``getUtility``,
+- If you disuse the legacy :func:`repoze.bfg.router.make_app` function
+  in favor of
+  :meth:`repoze.bfg.configuration.Configurator.make_wsgi_app`, and you
+  also want to use the "global" ZCA API (``getUtility``,
   ``getAdapter``, ``getSiteManager``, etc), you will need to "hook"
   the ZCA before calling methods of the configurator using the
   ``sethook`` method of the ``getSiteManager`` API, e.g.::
@@ -229,16 +235,16 @@ Deprecations and Behavior Differences
         config.load_zcml(zcml_file)
         return config.make_wsgi_app()
 
-  The ``repoze.bfg.router.make_app`` function does this on your
+  The :func:`repoze.bfg.router.make_app` function does this on your
   behalf for backward compatibility purposes.
 
-- The ``repoze.bfg.router.make_app`` function is now nominally
+- The :func:`repoze.bfg.router.make_app` function is now nominally
   deprecated.  Its import and usage does not throw a warning, nor will
   it probably ever disappear.  However, using a
-  ``repoze.bfg.configuration.Configurator`` class is now the preferred
-  way to generate a WSGI application.
+  :class:`repoze.bfg.configuration.Configurator` class is now the
+  preferred way to generate a WSGI application.
 
-  Note that ``make_app`` calls
+  Note that :func:`repoze.bfg.router.make_app` calls
   ``zope.component.getSiteManager.sethook(
   repoze.bfg.threadlocal.get_current_registry)`` on the caller's
   behalf, hooking ZCA global API lookups, for backwards compatibility
@@ -264,21 +270,22 @@ Documentation Enhancements
   request`` convention is also supported and documented, and will be
   "forever".
 
-- ``repoze.bfg.configuration`` API documentation has been added.
+- :mod:`repoze.bfg.configuration` API documentation has been added.
 
 - A narrative documentation chapter entitled "Creating Your First
   ``repoze.bfg`` Application" has been added.  This chapter details
-  usage of the new ``repoze.bfg.configuration.Configurator`` class,
-  and demonstrates a simplified "imperative-mode" configuration; doing
-  ``repoze.bfg`` application configuration imperatively was previously
-  much more difficult.
+  usage of the new :class:`repoze.bfg.configuration.Configurator`
+  class, and demonstrates a simplified "imperative-mode"
+  configuration; doing :mod:`repoze.bfg` application configuration
+  imperatively was previously much more difficult.
 
 - A narrative documentation chapter entitled "Configuration,
-  Decorations and Code Scanning" explaining ZCML- vs. imperative-
-  vs. decorator-based configuration equivalence.
+  Decorations and Code Scanning" (:ref:`scanning_chapter`) explaining
+  ZCML- vs. imperative- vs. decorator-based configuration equivalence.
 
-- The "ZCML Hooks" chapter has been renamed to "Hooks"; it documents
-  how to override hooks now via imperative configuration and ZCML.
+- The "ZCML Hooks" chapter has been renamed to "Hooks"
+  (:ref:`hooks_chapter`); it documents how to override hooks now via
+  imperative configuration and ZCML.
 
 - The explanation about how to supply an alternate "response factory"
   has been removed from the "Hooks" chapter.  This feature may be
@@ -286,16 +293,16 @@ Documentation Enhancements
   documented).
 
 - Add a section entitled "Test Set Up and Tear Down" to the
-  unittesting chapter.
+  unittesting chapter (:ref:`unittesting_chapter`).
 
 - Remove explanation of changing the request type in a new request
   event subscriber in the "Events" narrative documentation chapter, as
   other predicates are now usually an easier way to get this done.
 
 - Added "Thread Locals" narrative chapter to documentation, and added
-  a API chapter documenting the ``repoze.bfg.threadlocals`` module.
+  a API chapter documenting the :mod:`repoze.bfg.threadlocals` module.
 
 - Added a "Special Exceptions" section to the "Views" narrative
   documentation chapter explaining the effect of raising
-  ``repoze.bfg.exceptions.NotFound`` and
-  ``repoze.bfg.exceptions.Forbidden`` from within view code.
+  :exc:`repoze.bfg.exceptions.NotFound` and
+  :exc:`repoze.bfg.exceptions.Forbidden` from within view code.