- The SQL Wiki tutorial was updated to take into account changes to the

  ``pyramid_routesalchemy`` paster template.

25 files changed, 332 insertions, 449 deletions

diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index 6d8347f79..1746689e4 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -17,11 +17,17 @@ The source code for this tutorial stage can be browsed at
 `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/authorization/
 <http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/authorization/>`_.
 
+Changing ``__init__.py`` For Authorization
+-------------------------------------------
+
+We're going to be making several changes to our ``__init__.py`` file which
+will help us configure an authorization policy.
+
 Adding A Root Factory
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 We're going to start to use a custom :term:`root factory` within our
-``run.py`` file.  The objects generated by the root factory will be
+``__init__.py`` file.  The objects generated by the root factory will be
 used as the :term:`context` of each request to our application.  In
 order for :mod:`pyramid` declarative security to work properly, the
 context object generated during a request must be decorated with
@@ -29,10 +35,10 @@ security declarations; when we begin to use a custom root factory to
 generate our contexts, we can begin to make use of the declarative
 security features of :mod:`pyramid`.
 
-Let's modify our ``run.py``, passing in a :term:`root factory` to our
-:term:`Configurator` constructor.  We'll point it at a new class we
-create inside our ``models.py`` file.  Add the following statements to
-your ``models.py`` file:
+We'll modify our ``__init__.py``, passing in a :term:`root factory` to our
+:term:`Configurator` constructor.  We'll point it at a new class we create
+inside our ``models.py`` file.  Add the following statements to your
+``models.py`` file:
 
 .. code-block:: python
 
@@ -59,70 +65,75 @@ an access control list during view callable execution.  See
 :ref:`assigning_acls` for more information about what an :term:`ACL`
 represents.
 
-.. note: Although we don't use the functionality here, the ``factory``
-   used to create route contexts may differ per-route as opposed to
-   globally.  See the ``factory`` attribute in
-   :ref:`route_zcml_directive` for more info.
+.. note: Although we don't use the functionality here, the ``factory`` used
+   to create route contexts may differ per-route as opposed to globally.  See
+   the ``factory`` argument to
+   :meth:`pyramid.configuration.Configurator.add_route` for more info.
 
 We'll pass the ``RootFactory`` we created in the step above in as the
-``root_factory`` argument to a :term:`Configurator`.  When we're done,
-your application's ``run.py`` will look like this.
-
-.. literalinclude:: src/authorization/tutorial/run.py
+``root_factory`` argument to a :term:`Configurator`.  
+
+Configuring an Authorization Policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For any :mod:`pyramid` application to perform authorization, we need to add a
+``security.py`` module (we'll do that shortly) and we'll need to change our
+``__init__.py`` file to add an :term:`authentication policy` and an
+:term:`authorization policy` which uses the ``security.py`` file for a
+*callback*.
+
+We'll change our ``__init__.py`` file to enable an
+``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to enable
+declarative security checking.  We'll also change ``__init__.py`` to add a
+:meth:`pyramid.configuration.Configurator.add_view` call to points at our
+``login`` :term:`view callable`, also known as a :term:`forbidden view`.
+This configures our newly created login view to show up when :mod:`pyramid`
+detects that a view invocation can not be authorized.  Also, we'll add
+``view_permission`` arguments with the value ``edit`` to the ``edit_page``
+and ``add_page`` routes.  This indicates that the view callables which these
+routes reference cannot be invoked without the authenticated user possessing
+the ``edit`` permission with respect to the current context.
+
+This makes the assertion that only users who possess the effective ``edit``
+permission at the time of the request may invoke those two views.  We've
+granted the ``group:editors`` principal the ``edit`` permission at the root
+model via its ACL, so only the a user whom is a member of the group named
+``group:editors`` will able to invoke the views associated with the
+``add_page`` or ``edit_page`` routes.
+
+Viewing Your Changes
+~~~~~~~~~~~~~~~~~~~~
+
+When you're done, your ``__init__.py`` will look like so:
+
+.. literalinclude:: src/authorization/tutorial/__init__.py
    :linenos:
    :language: python
 
-Configuring a ``pyramid`` Authorization Policy
--------------------------------------------------
-
-For any :mod:`pyramid` application to perform authorization, we
-need to add a ``security.py`` module and we'll need to change our
-``configure.zcml`` file to add an :term:`authentication policy` and an
-:term:`authorization policy`.
-
-Changing ``configure.zcml``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We'll change our ``configure.zcml`` file to enable an
-``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to
-enable declarative security checking.  We'll also change
-``configure.zcml`` to add a view stanza which points at our ``login``
-:term:`view callable`, also known as a :term:`forbidden view`.  This
-configures our newly created login view to show up when
-:mod:`pyramid` detects that a view invocation can not be
-authorized.  Also, we'll add ``view_permission`` attributes with the
-value ``edit`` to the ``edit_page`` and ``add_page`` route
-declarations.  This indicates that the view callables which these
-routes reference cannot be invoked without the authenticated user
-possessing the ``edit`` permission with respect to the current
-context.
-
-This makes the assertion that only users who possess the effective
-``edit`` permission at the time of the request may invoke those two
-views.  We've granted the ``group:editors`` principal the ``edit``
-permission at the root model via its ACL, so only the a user whom is a
-member of the group named ``group:editors`` will able to invoke the
-views associated with the ``add_page`` or ``edit_page`` routes.  
-
-When you're done, your ``configure.zcml`` will look like so
-
-.. literalinclude:: src/authorization/tutorial/configure.zcml
-   :linenos:
-   :language: xml
+Note that that the
+:class:`pyramid.authentication.AuthTktAuthenticationPolicy` constructor
+accepts two arguments: ``secret`` and ``callback``.  ``secret`` is a string
+representing an encryption key used by the "authentication ticket" machinery
+represented by this policy: it is required.  The ``callback`` is a string,
+representing a :term:`dotted Python name`, which points at the
+``groupfinder`` function in the current directory's ``security.py`` file.  We
+haven't added that module yet, but we're about to.
 
-Note that the ``authtktauthenticationpolicy`` tag has two attributes:
-``secret`` and ``callback``.  ``secret`` is a string representing an
-encryption key used by the "authentication ticket" machinery
-represented by this policy: it is required.  The ``callback`` is a
-string, representing a :term:`dotted Python name`, which points at the
-``groupfinder`` function in the current directory's ``security.py``
-file.  We haven't added that module yet, but we're about to.
+Viewing Our Edits to ``__init__.py``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When we're done configuring a root factory, adding an authorization policy,
+and adding views, your application's ``__init__.py`` will look like this:
+
+.. literalinclude:: src/authorization/tutorial/__init__.py
+   :linenos:
+   :language: python
 
 Adding ``security.py``
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Add a ``security.py`` module within your package (in the same
-directory as "run.py", "views.py", etc) with the following content:
+Add a ``security.py`` module within your package (in the same directory as
+"__init__.py", "views.py", etc) with the following content:
 
 .. literalinclude:: src/authorization/tutorial/security.py
    :linenos:
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index 63175138c..bd5a04ef5 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -11,53 +11,82 @@ The source code for this tutorial stage can be browsed at
 `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/basiclayout/
 <http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/basiclayout/>`_.
 
-``__init__.py``
----------------
+App Startup with ``__init__.py``
+--------------------------------
 
-A directory on disk can be turned into a Python :term:`package` by
-containing an ``__init__.py`` file.  Even if empty, this marks a
-directory as a Python package.
+A directory on disk can be turned into a Python :term:`package` by containing
+an ``__init__.py`` file.  Even if empty, this marks a directory as a Python
+package.  We use ``__init__.py`` both as a package marker and to contain
+configuration code.
 
-Configuration With ``configure.zcml``
---------------------------------------
-
-:mod:`pyramid` uses a configuration markup language syntactically
-the same as Zope's implementation of :term:`ZCML`, but using a
-different default XML namespace.  Our sample ZCML file looks like the
-following:
+When you run the application using the ``paster`` command using the
+``development.ini`` generated config file, the application configuration
+points at an Setuptools *entry point* described as ``egg:tutorial#app``.  In
+our application, because the application's ``setup.py`` file says so, this
+entry point happens to be the ``app`` function within the file named
+``__init__.py``:
 
-   .. literalinclude:: src/basiclayout/tutorial/configure.zcml
+   .. literalinclude:: src/basiclayout/tutorial/__init__.py
       :linenos:
-      :language: xml
-
-#. *Line 1*.  The root ``<configure>`` element.
-
-#. *Lines 3-4*. Boilerplate, the comment explains.
-
-#. *Lines 6-11*.  Register a ``<route>`` :term:`route configuration`
-   that will be used when the URL is ``/``.  Since this ``<route>``
-   has an empty ``pattern`` attribute, it is the "default" route. The
-   attribute named ``view`` with the value ``.views.my_view`` is the
-   dotted name to a *function* we write (generated by the
-   ``pyramid_routesalchemy`` template) that is given a ``request``
-   object and which returns a response or a dictionary.  You will use
-   mostly ``<route>`` statements in a :term:`URL dispatch` based
-   application to map URLs to code.  This ``route`` also names a
-   ``view_renderer``, which is a template which lives in the
-   ``templates`` subdirectory of the package.  When the
-   ``.views.my_view`` view returns a dictionary, a :term:`renderer`
+      :language: py
+
+#. *Lines 1-4*. Imports to support later code.
+
+#. *Lines 12-14*. Get the database configuration string from the
+   ``development.ini`` file's ``[app:sqlalchemy]`` section.  This will be a
+   URI (something like ``sqlite://``).
+
+#. *Line 15*. Get the database echo setting from ``development.ini``
+   file's ``[app:sqlalchemy]`` section.  This will either be ``true``
+   or ``false``.  If ``true``, the application will print SQL to the
+   console as it is generated and run by SQLAlchemy.  By default, it
+   is false.
+
+#. Line *16*. We initialize our SQL database using SQLAlchemy, passing
+   it the db string and a variant of the db_echo value.
+
+#. *Line 17*.  We construct a :term:`Configurator`.  ``settings`` is
+   passed as a keyword argument with the dictionary values passed by
+   PasteDeploy as the ``settings`` argument.  This will be a
+   dictionary of settings parsed by PasteDeploy, which contains
+   deployment-related values such as ``reload_templates``,
+   ``db_string``, etc.
+
+#. *Line 18*.  We call :meth:`pyramid.configuration.Configurator.begin` which
+    tells the configuration machinery we are starting configuration.
+
+#. *Line 19*.  We call
+   :meth:`pyramid.configuration.Configurator.add_static_view` with the
+   arguments ``static`` (the name), and ``tutorial:templates/static``.  This
+   registers a static resource view which will match any URL that starts with
+   ``/static/``.  This will serve up static resources for us from within the
+   ``templates/static`` directory of our ``tutorial`` package, in this case,
+   via ``http://localhost:6543/static/`` and below.  With this declaration,
+   we're saying that any URL that starts with ``/static`` should go to the
+   static view; any remainder of its path (e.g. the ``/foo`` in
+   ``/static/foo``) will be used to compose a path to a static file resource,
+   such as a CSS file.
+
+#. *Lines 20-21*.  Register a :term:`route configuration` via the
+   :meth:`pyramid.configuration.Configurator.add_route` method that will be
+   used when the URL is ``/``.  Since this route has an ``pattern`` equalling
+   ``/`` it is the "default" route. The argument named ``view`` with the
+   value ``tutorial.views.my_view`` is the dotted name to a *function* we
+   write (generated by the ``pyramid_routesalchemy`` template) that is given
+   a ``request`` object and which returns a response or a dictionary.  You
+   will use :meth:`pyramid.configuration.Configurator.add_route` statements
+   in a :term:`URL dispatch` based application to map URLs to code.  This
+   route also names a ``view_renderer``, which is a template which lives in
+   the ``templates`` subdirectory of the package.  When the
+   ``tutorial.views.my_view`` view returns a dictionary, a :term:`renderer`
    will use this template to create a response.
 
-#. *Lines 13-16*.  Register a ``<static>`` directive that will match
-   any URL that starts with ``/static/``.  This will serve up static
-   resources for us, in this case, at
-   ``http://localhost:6543/static/`` and below.  With this
-   declaration, we're saying that any URL that starts with ``/static``
-   should go to the static view; any remainder of its path (e.g. the
-   ``/foo`` in ``/static/foo``) will be used to compose a path to a
-   static file resource, such as a CSS file.
+#. *Line 22*.  We call :meth:`pyramid.configuration.Configurator.end` which
+    tells the configuration machinery we are ending configuration.
 
-#. *Line 18*.  The closing ``</configure>`` tag.
+#. *Line 23*.  We use the
+   :meth:`pyramid.configuration.Configurator.make_wsgi_app` method to return
+   a :term:`WSGI` application.
 
 Content Models with ``models.py``
 ---------------------------------
@@ -100,49 +129,3 @@ Here is the source for ``models.py``:
    object.  It also calls the ``populate`` function, to do initial
    database population.
 
-App Startup with ``run.py``
----------------------------
-
-When you run the application using the ``paster`` command using the
-``tutorial.ini`` generated config file, the application configuration
-points at an Setuptools *entry point* described as
-``egg:tutorial#app``.  In our application, because the application's
-``setup.py`` file says so, this entry point happens to be the ``app``
-function within the file named ``run.py``:
-
-   .. literalinclude:: src/basiclayout/tutorial/run.py
-      :linenos:
-      :language: py
-
-#. *Lines 1-3*. Imports to support later code.
-
-#. *Line 12*.  Obtain the ``configure_zcml`` setting from a value in
-   the ``tutorial.ini`` file's ``[app:sqlalchemy]`` section.  If it
-   doesn't exist in the configuration file, default to
-   ``configure.zcml``.
-
-#. *Lines 13-15*. Get the database configuration string from the
-   ``tutorial.ini`` file's ``[app:sqlalchemy]`` section.  This will be a URI
-   (something like ``sqlite://``).
-
-#. *Line 16*. Get the database echo settingf rom ``tutorial.ini``
-   file's ``[app:sqlalchemy]`` section.  This will either be ``true``
-   or ``false``.  If ``true``, the application will print SQL to the
-   console as it is generated and run by SQLAlchemy.  By default, it
-   is false.
-
-#. Line *17*. We initialize our SQL database using SQLAlchemy, passing
-   it the db string and a variant of the db_echo value.
-
-#. *Line 18*.  We construct a :term:`Configurator`.  ``settings`` is
-   passed as a keyword argument with the dictionary values passed by
-   PasteDeploy as the ``settings`` argument.  This will be a
-   dictionary of settings parsed by PasteDeploy, which contains
-   deployment-related values such as ``reload_templates``,
-   ``db_string``, etc.
-
-#. *Lines 19-22*.  We then load a ZCML file to do application
-   configuration, and use the
-   :meth:`pyramid.configuration.Configurator.make_wsgi_app` method
-   to return a :term:`WSGI` application.
-
diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index 18d8363ad..9fb0c5d9c 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -34,16 +34,15 @@ code generated by our ``routesalchemy`` paster template does not use
 declarative SQLAlchemy syntax, so we'll need to change various things
 to begin to use declarative syntax.
 
-Our ``Page`` class will have a class level attribute ``__tablename__``
-which equals the string ``pages``.  This means that SQLAlchemy will
-store our wiki data in a SQL table named ``pages``.  Our Page class
-will also have class-level attributes named ``id``, ``pagename`` and
-``data`` (all instances of :class:`sqlalchemy.Column`).  These will
-map to columns in the ``pages`` table.  The ``id`` attribute will be
-the primary key in the table.  The ``name`` attribute will be a text
-attribute, each value of which needs to be unique within the column.
-The ``data`` attribute is a text attribute that will hold the body of
-each page.
+Our ``Page`` class will have a class level attribute ``__tablename__`` which
+equals the string ``pages``.  This means that SQLAlchemy will store our wiki
+data in a SQL table named ``pages``.  Our Page class will also have
+class-level attributes named ``id``, ``pagename`` and ``data`` (all instances
+of :class:`sqlalchemy.Column`).  These will map to columns in the ``pages``
+table.  The ``id`` attribute will be the primary key in the table.  The
+``name`` attribute will be a text attribute, each value of which needs to be
+unique within the column.  The ``data`` attribute is a text attribute that
+will hold the body of each page.
 
 We'll also remove our ``populate`` function.  We'll inline the
 populate step into ``initialize_sql``, changing our ``initialize_sql``
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index 559e6df2f..a10e8b9ca 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -20,15 +20,14 @@ assumed to return a :term:`response` object.
    view function that only takes the request as a single argument, you
    can obtain it via ``request.context``.
 
-The request passed to every view that is called as the result of a
-route match has an attribute named ``matchdict`` that contains the
-elements placed into the URL by the ``pattern`` of a ``route``
-statement.  For instance, if a route statement in ``configure.zcml``
-had the pattern ``:one/:two``, and the URL at
+The request passed to every view that is called as the result of a route
+match has an attribute named ``matchdict`` that contains the elements placed
+into the URL by the ``pattern`` of a ``route`` statement.  For instance, if a
+call to :meth:`pyramid.configuration.Configurator.add_route` in
+``__init__.py`` had the pattern ``:one/:two``, and the URL at
 ``http://example.com/foo/bar`` was invoked, matching this pattern, the
-matchdict dictionary attached to the request passed to the view would
-have a ``one`` key with the value ``foo`` and a ``two`` key with the
-value ``bar``.
+matchdict dictionary attached to the request passed to the view would have a
+``one`` key with the value ``foo`` and a ``two`` key with the value ``bar``.
 
 The source code for this tutorial stage can be browsed at
 `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/views/
@@ -122,7 +121,7 @@ The fact that this view returns a dictionary (as opposed to a
 try to use a :term:`renderer` associated with the view configuration
 to render a template.  In our case, the template which will be
 rendered will be the ``templates/view.pt`` template, as per the
-configuration put into effect in ``configure.zcml``.
+configuration put into effect in ``__init__.py``.
 
 The ``add_page`` view function
 ------------------------------
@@ -258,56 +257,53 @@ available `online
 
 
 This CSS file will be accessed via
-e.g. ``http://localhost:6543/static/style.css`` by virtue of the
-``<static>`` directive we've defined in the ``configure.zcml`` file.
-Any number and type of static resources can be placed in this
-directory (or subdirectories) and are just referred to by URL within
+e.g. ``http://localhost:6543/static/style.css`` by virtue of the call we've
+made to :meth:`pyramid.configuration.Configurator.add_static_view` within our
+``__init__.py`` file.  Any number and type of static resources can be placed
+in this directory (or subdirectories) and are just referred to by URL within
 templates.
 
-Mapping Views to URLs in ``configure.zcml``
-===========================================
+Mapping Views to URLs in ``__init__.py``
+========================================
 
-The ``configure.zcml`` file contains ``route`` declarations (and a
-lone ``view`` declaration) which serve to map URLs via :term:`url
-dispatch` to view functions.  First, we’ll get rid of the existing
-``route`` created by the template using the name ``home``. It’s only
-an example and isn’t relevant to our application. 
+The ``__init__.py`` file contains
+:meth:`pyramid.configuration.Configurator.add_route` calls which serve to map
+URLs via :term:`url dispatch` to view functions.  First, we’ll get rid of the
+existing route created by the template using the name ``home``. It’s only an
+example and isn’t relevant to our application.
 
-We then need to add four ``route`` declarations to ``configure.zcml``.
-Note that the *ordering* of these declarations is very important.
-``route`` declarations are matched in the order they're found in the
-``configure.zcml`` file.
+We then need to add four calls to ``add_route``.  Note that the *ordering* of
+these declarations is very important.  ``route`` declarations are matched in
+the order they're found in the ``__init__.py`` file.
 
-#. Add a declaration which maps the empty pattern (signifying the root
-   URL) to the view named ``view_wiki`` in our ``views.py`` file with
-   the name ``view_wiki``.  This is the :term:`default view` for the
-   wiki.
+#. Add a declaration which maps the pattern ``/`` (signifying the root URL)
+   to the view named ``view_wiki`` in our ``views.py`` file with the name
+   ``view_wiki``.  This is the :term:`default view` for the wiki.
 
-#. Add a declaration which maps the pattern ``:pagename`` to the
-   view named ``view_page`` in our ``views.py`` file with the view
-   name ``view_page``.  This is the regular view for a page.
+#. Add a declaration which maps the pattern ``/:pagename`` to the view named
+   ``view_page`` in our ``views.py`` file with the view name ``view_page``.
+   This is the regular view for a page.
 
 #. Add a declaration which maps the pattern
-   ``:pagename/edit_page`` to the view named ``edit_page`` in our
-   ``views.py`` file with the name ``edit_page``.  This is the edit view
-   for a page.
-
-#. Add a declaration which maps the pattern
-   ``add_page/:pagename`` to the view named ``add_page`` in our
+   ``/add_page/:pagename`` to the view named ``add_page`` in our
    ``views.py`` file with the name ``add_page``.  This is the add view
    for a new page.
 
-As a result of our edits, the ``configure.zcml`` file should look
+#. Add a declaration which maps the pattern ``/:pagename/edit_page`` to the
+   view named ``edit_page`` in our ``views.py`` file with the name
+   ``edit_page``.  This is the edit view for a page.
+
+As a result of our edits, the ``__init__.py`` file should look
 something like so:
 
-.. literalinclude:: src/views/tutorial/configure.zcml
+.. literalinclude:: src/views/tutorial/__init__.py
    :linenos:
    :language: xml
 
 The WSGI Pipeline
 -----------------
 
-Within ``tutorial.ini``, note the existence of a ``[pipeline:main]``
+Within ``development.ini``, note the existence of a ``[pipeline:main]``
 section which specifies our WSGI pipeline.  This "pipeline" will be
 served up as our WSGI application.  As far as the WSGI server is
 concerned the pipeline *is* our application.  Simpler configurations
@@ -328,9 +324,9 @@ Let's add a piece of middleware to the WSGI pipeline.  We'll add
 the browser while you're developing (this is *not* recommended for
 deployment as it is a security risk).  Let's insert evalerror into the
 pipeline right above ``egg:repoze.tm2#tm``, making our resulting
-``tutorial.ini`` file look like so:
+``development.ini`` file look like so:
 
-.. literalinclude:: src/views/tutorial.ini
+.. literalinclude:: src/views/development.ini
    :linenos:
    :language: ini
 
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index ae2eb4d06..2f103272a 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -266,11 +266,20 @@ Decisions the ``pyramid_routesalchemy`` Template Has Made For You
 =================================================================
 
 Creating a project using the ``pyramid_routesalchemy`` template makes
-the assumption that you are willing to use :term:`SQLAlchemy` as a
-database access tool and :term:`url dispatch` to map URLs to code.
-:mod:`pyramid` supports any persistent storage mechanism (e.g. object
-database or filesystem files, etc).  It also supports an additional
-mechanism to map URLs to code (:term:`traversal`).  However, for the
-purposes of this tutorial, we'll only be using url dispatch and
-SQLAlchemy.
+the following assumptions:
+
+- you are willing to use :term:`SQLAlchemy` as a database access tool
+
+- you are willing to use :term:`url dispatch` to map URLs to code.
+
+- you want to configure your application *imperatively* (no
+  :term:`declarative configuration` such as ZCML).
+
+.. note::
+
+   :mod:`pyramid` supports any persistent storage mechanism (e.g. object
+   database or filesystem files, etc).  It also supports an additional
+   mechanism to map URLs to code (:term:`traversal`).  However, for the
+   purposes of this tutorial, we'll only be using url dispatch and
+   SQLAlchemy.
 
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial.ini b/docs/tutorials/wiki2/src/authorization/development.ini
index 85f131c2e..85f131c2e 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial.ini
+++ b/docs/tutorials/wiki2/src/authorization/development.ini
diff --git a/docs/tutorials/wiki2/src/authorization/setup.py b/docs/tutorials/wiki2/src/authorization/setup.py
index eeac5c397..5dabb69a2 100644
--- a/docs/tutorials/wiki2/src/authorization/setup.py
+++ b/docs/tutorials/wiki2/src/authorization/setup.py
@@ -40,7 +40,7 @@ setup(name='tutorial',
       install_requires = requires,
       entry_points = """\
       [paste.app_factory]
-      app = tutorial.run:app
+      app = tutorial:app
       """
       )
 
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
index cbdfd3ac6..8c93e5d5a 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
@@ -1,2 +1,51 @@
-# A package
+from pyramid.configuration import Configurator
+from pyramid.authentication import AuthTktAuthenticationPolicy
+from pyramid.authorization import ACLAuthorizationPolicy
+
+from paste.deploy.converters import asbool
+
+from tutorial.models import initialize_sql
+
+def app(global_config, **settings):
+    """ This function returns a WSGI application.
+    
+    It is usually called by the PasteDeploy framework during 
+    ``paster serve``.
+    """
+    db_string = settings.get('db_string')
+    if db_string is None:
+        raise ValueError("No 'db_string' value in application configuration.")
+    db_echo = settings.get('db_echo', 'false')
+    initialize_sql(db_string, asbool(db_echo))
+    authn_policy = AuthTktAuthenticationPolicy(
+        'sosecret', callback='tutorial.security.groupfinder')
+    authz_policy = ACLAuthorizationPolicy()
+    config = Configurator(settings=settings,
+                          root_factory='tutorial.models.RootFactory',
+                          authentication_policy=authn_policy,
+                          authorization_policy=authz_policy)
+    config.begin()
+    config.add_static_view('static', 'templates/static')
+    config.add_route('view_wiki', '/', view='tutorial.views.view_wiki')
+    config.add_route('view_page', '/:pagename',
+                     view='tutorial.views.view_page',
+                     view_renderer='tutorial:templates/view.pt')
+    config.add_route('add_page', '/add_page/:pagename',
+                     view='tutorial.views.add_page',
+                     view_renderer='tutorial:templates/view.pt',
+                     view_permission='edit')
+    config.add_route('edit_page', '/:pagename/edit_page',
+                     view='tutorial.views.edit_page',
+                     view_renderer='tutorial:templates/edit.pt',
+                     view_permission='edit')
+    config.add_route('login', '/login',
+                     view='tutorial.login.login',
+                     view_renderer='tutorial:templates/login.pt')
+    config.add_route('logout', '/logout',
+                     view='tutorial.login.loout')
+    config.add_view('tutorial.login.login',
+                    renderer='tutorial:templates/login.pt',
+                    context='pyramid.exceptions.Forbidden')
+    config.end()
+    return config.make_wsgi_app()
 
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/configure.zcml b/docs/tutorials/wiki2/src/authorization/tutorial/configure.zcml
deleted file mode 100644
index 03b0e5b5a..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/configure.zcml
+++ /dev/null
@@ -1,65 +0,0 @@
-<configure xmlns="http://pylonshq.com/pyramid">
-
-  <!-- this must be included for the view declarations to work -->
-  <include package="pyramid.includes" />
-
-  <static
-    path="templates/static"
-    name="static"
-    />
-
-  <route
-     pattern="login"
-     name="login"
-     view=".login.login"
-     view_renderer="templates/login.pt"
-     />
-
-  <route
-     pattern="logout"
-     name="logout"
-     view=".login.logout"
-     />
-
-  <route
-    pattern=""
-    name="view_wiki"
-    view=".views.view_wiki"
-    />
-    
-  <route
-     pattern=":pagename"
-     name="view_page"
-     view=".views.view_page"
-     view_renderer="templates/view.pt"
-     />
-
-  <route
-     pattern="add_page/:pagename"
-     name="add_page"
-     view=".views.add_page"
-     view_renderer="templates/edit.pt"
-     view_permission="edit"
-     />
-
-  <route
-     pattern=":pagename/edit_page"
-     name="edit_page"
-     view=".views.edit_page"
-     view_renderer="templates/edit.pt"
-     view_permission="edit"
-     />
-
-  <view
-     view=".login.login"
-     renderer="templates/login.pt"
-     for="pyramid.exceptions.Forbidden"/>
-
-  <authtktauthenticationpolicy
-    secret="sosecret"
-    callback=".security.groupfinder"
-    />
-
-  <aclauthorizationpolicy/>
-
-</configure>
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/run.py b/docs/tutorials/wiki2/src/authorization/tutorial/run.py
deleted file mode 100644
index 82ce37490..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/run.py
+++ /dev/null
@@ -1,25 +0,0 @@
-from pyramid.configuration import Configurator
-from paste.deploy.converters import asbool
-
-from tutorial.models import initialize_sql
-from tutorial.models import RootFactory
-
-def app(global_config, **settings):
-    """ This function returns a WSGI application.
-    
-    It is usually called by the PasteDeploy framework during 
-    ``paster serve``.
-    """
-    zcml_file = settings.get('configure_zcml', 'configure.zcml')
-    db_string = settings.get('db_string')
-    if db_string is None:
-        raise ValueError(
-            "No 'db_string' value in application configuration.")
-    db_echo = settings.get('db_echo', 'false')
-    initialize_sql(db_string, asbool(db_echo))
-    config = Configurator(settings=settings, root_factory=RootFactory)
-    config.begin()
-    config.load_zcml(zcml_file)
-    config.end()
-    return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial.ini b/docs/tutorials/wiki2/src/basiclayout/development.ini
index 73b5ed9a4..73b5ed9a4 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/development.ini
diff --git a/docs/tutorials/wiki2/src/basiclayout/setup.py b/docs/tutorials/wiki2/src/basiclayout/setup.py
index aca548b32..79b1a37c9 100644
--- a/docs/tutorials/wiki2/src/basiclayout/setup.py
+++ b/docs/tutorials/wiki2/src/basiclayout/setup.py
@@ -39,7 +39,7 @@ setup(name='tutorial',
       install_requires = requires,
       entry_points = """\
       [paste.app_factory]
-      app = tutorial.run:app
+      app = tutorial:app
       """
       )
 
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
index cbdfd3ac6..e1ef485f7 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
@@ -1,2 +1,23 @@
-# A package
+from pyramid.configuration import Configurator
+from paste.deploy.converters import asbool
 
+from tutorial.models import initialize_sql
+
+def app(global_config, **settings):
+    """ This function returns a WSGI application.
+    
+    It is usually called by the PasteDeploy framework during 
+    ``paster serve``.
+    """
+    db_string = settings.get('db_string')
+    if db_string is None:
+        raise ValueError("No 'db_string' value in application configuration.")
+    db_echo = settings.get('db_echo', 'false')
+    initialize_sql(db_string, asbool(db_echo))
+    config = Configurator(settings=settings)
+    config.begin()
+    config.add_static_view('static', 'templates/static')
+    config.add_route('home', '/', view='tutorial.views.my_view',
+                     view_renderer='templates/mytemplate.pt')
+    config.end()
+    return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/configure.zcml b/docs/tutorials/wiki2/src/basiclayout/tutorial/configure.zcml
deleted file mode 100644
index 47adfbefb..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/configure.zcml
+++ /dev/null
@@ -1,18 +0,0 @@
-<configure xmlns="http://pylonshq.com/pyramid">
-
-  <!-- this must be included for the view declarations to work -->
-  <include package="pyramid.includes" />
-
-  <route 
-    pattern=""
-    name="home"
-    view=".views.my_view"
-    view_renderer="templates/mytemplate.pt"
-    />
-
-  <static
-    name="static"
-    path="templates/static"
-    />
-
-</configure>
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/run.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/run.py
deleted file mode 100644
index 7225987ee..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/run.py
+++ /dev/null
@@ -1,24 +0,0 @@
-from pyramid.configuration import Configurator
-from paste.deploy.converters import asbool
-
-from tutorial.models import initialize_sql
-
-def app(global_config, **settings):
-    """ This function returns a WSGI application.
-    
-    It is usually called by the PasteDeploy framework during 
-    ``paster serve``.
-    """
-    zcml_file = settings.get('configure_zcml', 'configure.zcml')
-    db_string = settings.get('db_string')
-    if db_string is None:
-        raise ValueError(
-            "No 'db_string' value in application configuration.")
-    db_echo = settings.get('db_echo', 'false')
-    initialize_sql(db_string, asbool(db_echo))
-    config = Configurator(settings=settings)
-    config.begin()
-    config.load_zcml(zcml_file)
-    config.end()
-    return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/models/tutorial.ini b/docs/tutorials/wiki2/src/models/development.ini
index 73b5ed9a4..73b5ed9a4 100644
--- a/docs/tutorials/wiki2/src/models/tutorial.ini
+++ b/docs/tutorials/wiki2/src/models/development.ini
diff --git a/docs/tutorials/wiki2/src/models/setup.py b/docs/tutorials/wiki2/src/models/setup.py
index aca548b32..79b1a37c9 100644
--- a/docs/tutorials/wiki2/src/models/setup.py
+++ b/docs/tutorials/wiki2/src/models/setup.py
@@ -39,7 +39,7 @@ setup(name='tutorial',
       install_requires = requires,
       entry_points = """\
       [paste.app_factory]
-      app = tutorial.run:app
+      app = tutorial:app
       """
       )
 
diff --git a/docs/tutorials/wiki2/src/models/tutorial/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
index cbdfd3ac6..e1ef485f7 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
@@ -1,2 +1,23 @@
-# A package
+from pyramid.configuration import Configurator
+from paste.deploy.converters import asbool
 
+from tutorial.models import initialize_sql
+
+def app(global_config, **settings):
+    """ This function returns a WSGI application.
+    
+    It is usually called by the PasteDeploy framework during 
+    ``paster serve``.
+    """
+    db_string = settings.get('db_string')
+    if db_string is None:
+        raise ValueError("No 'db_string' value in application configuration.")
+    db_echo = settings.get('db_echo', 'false')
+    initialize_sql(db_string, asbool(db_echo))
+    config = Configurator(settings=settings)
+    config.begin()
+    config.add_static_view('static', 'templates/static')
+    config.add_route('home', '/', view='tutorial.views.my_view',
+                     view_renderer='templates/mytemplate.pt')
+    config.end()
+    return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki2/src/models/tutorial/configure.zcml b/docs/tutorials/wiki2/src/models/tutorial/configure.zcml
deleted file mode 100644
index 47adfbefb..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/configure.zcml
+++ /dev/null
@@ -1,18 +0,0 @@
-<configure xmlns="http://pylonshq.com/pyramid">
-
-  <!-- this must be included for the view declarations to work -->
-  <include package="pyramid.includes" />
-
-  <route 
-    pattern=""
-    name="home"
-    view=".views.my_view"
-    view_renderer="templates/mytemplate.pt"
-    />
-
-  <static
-    name="static"
-    path="templates/static"
-    />
-
-</configure>
diff --git a/docs/tutorials/wiki2/src/models/tutorial/run.py b/docs/tutorials/wiki2/src/models/tutorial/run.py
deleted file mode 100644
index 7225987ee..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/run.py
+++ /dev/null
@@ -1,24 +0,0 @@
-from pyramid.configuration import Configurator
-from paste.deploy.converters import asbool
-
-from tutorial.models import initialize_sql
-
-def app(global_config, **settings):
-    """ This function returns a WSGI application.
-    
-    It is usually called by the PasteDeploy framework during 
-    ``paster serve``.
-    """
-    zcml_file = settings.get('configure_zcml', 'configure.zcml')
-    db_string = settings.get('db_string')
-    if db_string is None:
-        raise ValueError(
-            "No 'db_string' value in application configuration.")
-    db_echo = settings.get('db_echo', 'false')
-    initialize_sql(db_string, asbool(db_echo))
-    config = Configurator(settings=settings)
-    config.begin()
-    config.load_zcml(zcml_file)
-    config.end()
-    return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/views/tutorial.ini b/docs/tutorials/wiki2/src/views/development.ini
index 85f131c2e..85f131c2e 100644
--- a/docs/tutorials/wiki2/src/views/tutorial.ini
+++ b/docs/tutorials/wiki2/src/views/development.ini
diff --git a/docs/tutorials/wiki2/src/views/setup.py b/docs/tutorials/wiki2/src/views/setup.py
index eeac5c397..5dabb69a2 100644
--- a/docs/tutorials/wiki2/src/views/setup.py
+++ b/docs/tutorials/wiki2/src/views/setup.py
@@ -40,7 +40,7 @@ setup(name='tutorial',
       install_requires = requires,
       entry_points = """\
       [paste.app_factory]
-      app = tutorial.run:app
+      app = tutorial:app
       """
       )
 
diff --git a/docs/tutorials/wiki2/src/views/tutorial/__init__.py b/docs/tutorials/wiki2/src/views/tutorial/__init__.py
index cbdfd3ac6..2d00cccc2 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/__init__.py
@@ -1,2 +1,32 @@
-# A package
+from pyramid.configuration import Configurator
+from paste.deploy.converters import asbool
+
+from tutorial.models import initialize_sql
+
+def app(global_config, **settings):
+    """ This function returns a WSGI application.
+    
+    It is usually called by the PasteDeploy framework during 
+    ``paster serve``.
+    """
+    db_string = settings.get('db_string')
+    if db_string is None:
+        raise ValueError("No 'db_string' value in application configuration.")
+    db_echo = settings.get('db_echo', 'false')
+    initialize_sql(db_string, asbool(db_echo))
+    config = Configurator(settings=settings)
+    config.begin()
+    config.add_static_view('static', 'templates/static')
+    config.add_route('home', '/', view='tutorial.views.view_wiki')
+    config.add_route('view_page', '/:pagename',
+                     view='tutorial.views.view_page',
+                     view_renderer='tutorial:templates/view.pt')
+    config.add_route('add_page', '/add_page/:pagename',
+                     view='tutorial.views.add_page',
+                     view_renderer='tutorial:templates/view.pt')
+    config.add_route('edit_page', '/:pagename/edit_page',
+                     view='tutorial.views.edit_page',
+                     view_renderer='tutorial:templates/edit.pt')
+    config.end()
+    return config.make_wsgi_app()
 
diff --git a/docs/tutorials/wiki2/src/views/tutorial/configure.zcml b/docs/tutorials/wiki2/src/views/tutorial/configure.zcml
deleted file mode 100644
index 3a2e13a7a..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/configure.zcml
+++ /dev/null
@@ -1,38 +0,0 @@
-<configure xmlns="http://pylonshq.com/pyramid">
-
-  <!-- this must be included for the view declarations to work -->
-  <include package="pyramid.includes" />
-
-  <static
-    path="templates/static"
-    name="static"
-    />
-
-  <route
-    pattern=""
-    name="view_wiki"
-    view=".views.view_wiki"
-    />
-    
-  <route
-     pattern=":pagename"
-     name="view_page"
-     view=".views.view_page"
-     view_renderer="templates/view.pt"
-     />
-
-  <route
-     pattern="add_page/:pagename"
-     name="add_page"
-     view=".views.add_page"
-     view_renderer="templates/edit.pt"
-     />
-
-  <route
-     pattern=":pagename/edit_page"
-     name="edit_page"
-     view=".views.edit_page"
-     view_renderer="templates/edit.pt"
-     />
-
-</configure>
diff --git a/docs/tutorials/wiki2/src/views/tutorial/run.py b/docs/tutorials/wiki2/src/views/tutorial/run.py
deleted file mode 100644
index 7225987ee..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/run.py
+++ /dev/null
@@ -1,24 +0,0 @@
-from pyramid.configuration import Configurator
-from paste.deploy.converters import asbool
-
-from tutorial.models import initialize_sql
-
-def app(global_config, **settings):
-    """ This function returns a WSGI application.
-    
-    It is usually called by the PasteDeploy framework during 
-    ``paster serve``.
-    """
-    zcml_file = settings.get('configure_zcml', 'configure.zcml')
-    db_string = settings.get('db_string')
-    if db_string is None:
-        raise ValueError(
-            "No 'db_string' value in application configuration.")
-    db_echo = settings.get('db_echo', 'false')
-    initialize_sql(db_string, asbool(db_echo))
-    config = Configurator(settings=settings)
-    config.begin()
-    config.load_zcml(zcml_file)
-    config.end()
-    return config.make_wsgi_app()
-