- Most references to ZCML in narrative chapters have been removed or

redirected to ``pyramid_zcml`` locations.
davidjb · Jan 18, 2011 · c9c3c48 · c9c3c48
1 parent 47af907
commit c9c3c48
Show file tree

Hide file tree

Showing 39 changed files with 74 additions and 1,847 deletions.
diff --git a/CHANGES.txt b/CHANGES.txt
@@ -26,8 +26,8 @@ Backwards Incompatibilities
 
 - The ``pyramid.includes`` subpackage has been removed.  ZCML files which use
   include the package ``pyramid.includes`` (e.g. ``<include
-  package="pyramid.includes">``) now must include the ``pyramid_zcml``
-  package instead (e.g. ``<include package="pyramid_zcml"/>).
+  package="pyramid.includes"/>``) now must include the ``pyramid_zcml``
+  package instead (e.g. ``<include package="pyramid_zcml"/>``).
 
 - The ``pyramid.view.action`` decorator has been removed from the Pyramid
   core.  Handlers are now a feature of the ``pyramid_handlers`` package.  It
@@ -101,7 +101,10 @@ Documentation
   "Renderers" chapter in a section named "Overriding A Renderer at Runtime".
 
 - The "Declarative Configuration" narrative chapter has been removed (it was
-  moved to the ``pyramid_zcml`` pakcage).
+  moved to the ``pyramid_zcml`` package).
+
+- Most references to ZCML in narrative chapters have been removed or
+  redirected to ``pyramid_zcml`` locations.
 
 Deprecations
 ------------

diff --git a/docs/authorintro.rst b/docs/authorintro.rst
@@ -79,12 +79,6 @@ This book is divided into four major parts:
   :app:`Pyramid`.  The API documentation is organized
   alphabetically by module name.
 
-:ref:`zcml_reference`
-
-  Comprehensive reference material for every :term:`ZCML directive`
-  provided by :app:`Pyramid`.  The ZCML directive documentation is
-  organized alphabetically by directive name.
-
 .. index::
    single: repoze.zope2
    single: Zope 3

diff --git a/docs/designdefense.rst b/docs/designdefense.rst
@@ -453,34 +453,11 @@ Pyramid "Encourages Use of ZCML"
 :term:`Zope Component Architecture` registry that :app:`Pyramid` uses for
 application configuration.  Often people claim that Pyramid "needs ZCML".
 
-Quick answer: it doesn't. At least not anymore.  In :mod:`repoze.bfg` (the
-predecessor to Pyramid) versions 1.0 and and 1.1, an application needed to
-possess a ZCML file for it to begin executing successfully.  However,
-:mod:`repoze.bfg` 1.2 and greater (including :app:`Pyramid` 1.0) includes a
-completely imperative mode for all configuration.  You will be able to make
-"single file" apps in this mode, which should help people who need to see
-everything done completely imperatively.  For example, the very most basic
-:app:`Pyramid` "helloworld" program has become something like:
-
-.. code-block:: python
-   :linenos:
-
-   from webob import Response
-   from paste.httpserver import serve
-   from pyramid.config import Configurator
-
-   def hello_world(request):
-       return Response('Hello world!')
-
-   if __name__ == '__main__':
-       config = Configurator()
-       config.add_view(hello_world)
-       app = config.make_wsgi_app()
-       serve(app)
-
-In this mode, no ZCML is required at all, nor any other sort of frameworky
-frontend to application configuration.  Hopefully this mode will allow people
-who are used to doing everything imperatively feel more comfortable.
+It doesn't.  In :app:`Pyramid` 1.0, ZCML doesn't ship as part of the core;
+instead it ships in the :term:`pyramid_zcml` add-on package, which is
+completely optional.  No ZCML is required at all to use :app:`Pyramid`, nor
+any other sort of frameworky declarative frontend to application
+configuration.
 
 Pyramid Uses ZCML; ZCML is XML and I Don't Like XML
 ---------------------------------------------------

diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -89,9 +89,9 @@ Glossary
    dotted Python name
      A reference to a Python object by name using a string, in the form
      ``path.to.modulename:attributename``.  Often used in Paste and
-     setuptools configurations.  A variant is used in dotted names
-     within :term:`ZCML` attributes that name objects (such as the ZCML
-     "view" directive's "view" attribute): the colon (``:``) is not
+     setuptools configurations.  A variant is used in dotted names within
+     configurator method arguments that name objects (such as the "add_view"
+     method's "view" and "context" attributes): the colon (``:``) is not
      used; in its place is a dot.
 
    view
@@ -116,8 +116,8 @@ Glossary
      with configuration information.  This configuration information helps
      map a given :term:`request` to a particular view callable and it can
      influence the response of a view callable.  :app:`Pyramid` views can be
-     configured via :term:`imperative configuration`, :term:`ZCML` or by a
-     special ``@view_config`` decorator coupled with a :term:`scan`.  See
+     configured via :term:`imperative configuration`, or by a special
+     ``@view_config`` decorator coupled with a :term:`scan`.  See
      :ref:`view_config_chapter` for more information about view
      configuration.
 
@@ -377,29 +377,10 @@ Glossary
      ultimately a :term:`view`).  See also :term:`url dispatch`.
 
    route configuration
-     Route configuration is the act of using :term:`imperative
-     configuration` or a :term:`ZCML` ``<route>`` statement to
-     associate request parameters with a particular :term:`route` using
-     pattern matching and :term:`route predicate` statements.  See
-     :ref:`urldispatch_chapter` for more information about route
-     configuration.
-
-   ZCML
-     `Zope Configuration Markup Language
-     <http://www.muthukadan.net/docs/zca.html#zcml>`_, an XML dialect
-     used by Zope and :app:`Pyramid` for configuration tasks.  ZCML
-     is capable of performing different types of :term:`configuration
-     declaration`, but its primary purpose in :app:`Pyramid` is to
-     perform :term:`view configuration` and :term:`route configuration`
-     within the ``configure.zcml`` file in a :app:`Pyramid`
-     application.  You can use ZCML as an alternative to
-     :term:`imperative configuration`.
-
-   ZCML directive
-     A ZCML "tag" such as ``<view>`` or ``<route>``.
-
-   ZCML declaration
-     The concrete use of a :term:`ZCML directive` within a ZCML file.
+     Route configuration is the act of associating request parameters with a
+     particular :term:`route` using pattern matching and :term:`route
+     predicate` statements.  See :ref:`urldispatch_chapter` for more
+     information about route configuration.
 
    Zope Component Architecture
      The `Zope Component Architecture
@@ -457,9 +438,9 @@ Glossary
 
    subscriber
      A callable which receives an :term:`event`.  A callable becomes a
-     subscriber via :term:`imperative configuration` or the
-     ``<subscriber>`` ZCML directive.  See :ref:`events_chapter` for
-     more information.
+     subscriber via :term:`imperative configuration` or via
+     :term:`configuration decoration`.  See :ref:`events_chapter` for more
+     information.
 
    request type
      An attribute of a :term:`request` that allows for specialization
@@ -577,15 +558,13 @@ Glossary
      also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_.
 
    configuration declaration
-     An individual method call made to an instance of a
-     :app:`Pyramid` :term:`Configurator` object which performs an
-     arbitrary action, such as registering a :term:`view configuration`
-     (via the ``view`` method of the configurator) or :term:`route
-     configuration` (via the ``route`` method of the configurator).  A
-     set of configuration declarations is also usually implied via the
-     use of a :term:`ZCML declaration` within an application, or a set
-     of configuration declarations might be performed by a :term:`scan`
-     of code in a package.
+     An individual method call made to an instance of a :app:`Pyramid`
+     :term:`Configurator` object which performs an arbitrary action, such as
+     registering a :term:`view configuration` (via the ``add_view`` method of
+     the configurator) or :term:`route configuration` (via the ``add_route``
+     method of the configurator).  A set of configuration declarations is
+     also implied by the :term:`configuration decoration` detected by a
+     :term:`scan` of code in a package.
 
    configuration decoration
      Metadata implying one or more :term:`configuration declaration`
@@ -609,8 +588,8 @@ Glossary
      declaration` required by your application.
 
    declarative configuration
-     The configuration mode in which you use :term:`ZCML` to make
-     a set of :term:`configuration declaration` statements.
+     The configuration mode in which you use :term:`ZCML` to make a set of
+     :term:`configuration declaration` statements.  See :term:`pyramid_zcml`.
 
    Not Found view
       An :term:`exception view` invoked by :app:`Pyramid` when the
@@ -862,3 +841,21 @@ Glossary
     ``request.matchdict`` when a :term:`URL dispatch` route has been matched.
     Its keys are names as identified within the route pattern; its values are
     the values matched by each pattern name.
+
+   pyramid_zcml
+     An add-on package to :app:`Pyramid` which allows applications to be
+     configured via ZCML.  It is available on :term:`PyPI`.  If you use
+     ``pyramid_zcml``, you can use ZCML as an alternative to
+     :term:`imperative configuration`.
+
+   ZCML
+     `Zope Configuration Markup Language
+     <http://www.muthukadan.net/docs/zca.html#zcml>`_, an XML dialect
+     used by Zope and :term:`pyramid_zcml` for configuration tasks.  
+
+   ZCML directive
+     A ZCML "tag" such as ``<view>`` or ``<route>``.
+
+   ZCML declaration
+     The concrete use of a :term:`ZCML directive` within a ZCML file.
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -85,14 +85,12 @@ applications to various platforms.
 Reference Material
 ==================
 
-Reference material includes API documentation and documentation of
-every :app:`Pyramid` :term:`ZCML directive`.
+Reference material includes documentation for every :app:`Pyramid` API.
 
 .. toctree::
    :maxdepth: 2
 
    api
-   zcml
 
 Detailed Change History
 =======================

diff --git a/docs/latexindex.rst b/docs/latexindex.rst
@@ -97,7 +97,6 @@ API Reference
    api/renderers
    api/request
    api/response
-   api/router
    api/scripting
    api/security
    api/settings
@@ -108,35 +107,6 @@ API Reference
    api/view
    api/wsgi
 
-.. _zcml_reference:
-
-ZCML Directive Reference
-@@@@@@@@@@@@@@@@@@@@@@@@
-
-.. toctree::
-   :maxdepth: 1
-
-   zcml/aclauthorizationpolicy
-   zcml/adapter
-   zcml/authtktauthenticationpolicy
-   zcml/asset
-   zcml/configure
-   zcml/default_permission
-   zcml/forbidden
-   zcml/include
-   zcml/localenegotiator
-   zcml/notfound
-   zcml/remoteuserauthenticationpolicy
-   zcml/renderer
-   zcml/repozewho1authenticationpolicy
-   zcml/route
-   zcml/scan
-   zcml/static
-   zcml/subscriber
-   zcml/translationdir
-   zcml/utility
-   zcml/view
-
 .. backmatter::
 
 Glossary and Index

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
@@ -115,11 +115,8 @@ allowing the circumstance to go unreported, by default Pyramid raises a
 running.
 
 Conflict detection happens for any kind of configuration: imperative
-configuration, :term:`ZCML` configuration, or configuration that results from
-the execution of a :term:`scan`.
-
-.. note:: If you use, ZCML, its conflict detection algorithm is described in
-   :ref:`zcml_conflict_detection`.
+configuration or configuration that results from the execution of a
+:term:`scan`.
 
 Manually Resolving Conflicts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/narr/events.rst b/docs/narr/events.rst
@@ -82,9 +82,6 @@ function found via a :term:`scan`.
    decorated function for the decorator to have any effect.  See
    :func:`pyramid.subscriber` for more information.
 
-.. note:: You can also configure an event listener via ZCML.  See
-   :ref:`zcml_event_listener`.
-
 Either of the above registration examples implies that every time the
 :app:`Pyramid` framework emits an event object that supplies an
 :class:`pyramid.events.NewRequest` interface, the ``mysubscriber`` function

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
@@ -70,9 +70,6 @@ Here's some sample code that implements a minimal NotFound view callable:
    :exc:`pyramid.exceptions.NotFound` exception instance.  If available, the
    resource context will still be available as ``request.context``.
 
-For information about how to configure a not found view via :term:`ZCML`, see
-:ref:`notfound_zcml`.
-
 .. index::
    single: forbidden view
 
@@ -138,9 +135,6 @@ Here's some sample code that implements a minimal forbidden view:
    an alternate forbidden view.  For example, it would make sense to
    return a response with a ``403 Forbidden`` status code.
 
-For information about how to configure a forbidden view via :term:`ZCML`, see
-:ref:`forbidden_zcml`.
-
 .. index::
    single: request factory
 
@@ -185,8 +179,6 @@ already constructed a :term:`configurator` it can also be registered via the
    config = Configurator()
    config.set_request_factory(MyRequest)
 
-To use ZCML for the same purpose, see :ref:`changing_request_factory_zcml`.
-
 .. index::
    single: renderer globals
 
@@ -242,9 +234,6 @@ already constructed a :term:`configurator` it can also be registered via the
 Another mechanism which allows event subscribers to add renderer global values
 exists in :ref:`beforerender_event`.
 
-If you'd rather ZCML to register a renderer globals factory, see
-:ref:`adding_renderer_globals_zcml`.
-
 .. index::
    single: before render event
 
@@ -474,9 +463,6 @@ when the application :term:`root factory` returned an instance of the
 ``myapp.resources.MyRoot`` object.  Otherwise it would use the default
 :app:`Pyramid` traverser to do traversal.
 
-For information about how to configure an alternate traverser via
-:term:`ZCML`, see :ref:`changing_traverser_zcml`.
-
 .. index::
    single: url generator
 

diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
@@ -890,9 +890,6 @@ 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`.
 
-.. note:: You can also add a translation directory via ZCML.  See
-   :ref:`zcml_adding_a_translation_directory`
-
 Setting the Locale
 ~~~~~~~~~~~~~~~~~~
 
@@ -1019,5 +1016,3 @@ For example:
    config = Configurator()
    config.set_locale_negotiator(my_locale_negotiator)
 
-.. note:: You can also add a custom locale negotiator via ZCML.  See
-   :ref:`zcml_adding_a_locale_negotiator`
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
@@ -26,7 +26,6 @@ and so therefore they are often referred to as "paster templates".
 .. index::
    single: paster templates
    single: pyramid_starter paster template
-   single: pyramid_starter_zcml paster template
    single: pyramid_zodb paster template
    single: pyramid_alchemy paster template
    single: pyramid_routesalchemy paster template
@@ -45,8 +44,6 @@ each other on a number of axes:
 - the mechanism they use to map URLs to code (:term:`traversal` or :term:`URL
   dispatch`).
 
-- the type of configuration used (:term:`ZCML` vs. imperative configuration).
-
 - whether or not the ``pyramid_beaker`` library is relied upon as the
   sessioning implementation (as opposed to no sessioning or default
   sessioning).
@@ -56,10 +53,6 @@ The included templates are these:
 ``pyramid_starter``
   URL mapping via :term:`traversal` and no persistence mechanism.
 
-``pyramid_starter_zcml``
-  URL mapping via :term:`traversal` and no persistence mechanism, using
-  :term:`ZCML` (declarative configuration).
-
 ``pyramid_zodb``
   URL mapping via :term:`traversal` and persistence via :term:`ZODB`.
 

diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
@@ -400,10 +400,6 @@ factory.
 Renderers can be registered imperatively using the
 :meth:`pyramid.config.Configurator.add_renderer` API.
 
-.. note:: The tasks described in this section can also be performed via
-   :term:`declarative configuration`.  See
-   :ref:`zcml_adding_and_overriding_renderers`.
-
 For example, to add a renderer which renders views which have a
 ``renderer`` attribute that is a path that ends in ``.jinja2``: