Merge branch 'master' of github.com:Pylons/pyramid

10 files changed, 274 insertions, 124 deletions

diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst
index bf88c3bd8..d900f17a3 100644
--- a/docs/tutorials/wiki/authorization.rst
+++ b/docs/tutorials/wiki/authorization.rst
@@ -42,7 +42,7 @@ declarative security checking. We need to import the new policies:
 Then, we'll add those policies to the configuration:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 20-25
+   :lines: 17-22
    :linenos:
    :language: python
 
@@ -60,10 +60,6 @@ look like so:
    :linenos:
    :language: python
 
-.. note::
-   (Your ``config.scan('tutorial')`` needs the package name you used
-   instead of "tutorial", if you used a different name.)
-
 Add ``security.py``
 ~~~~~~~~~~~~~~~~~~~
 
@@ -77,14 +73,13 @@ content:
 
 The ``groupfinder`` function defined here is an :term:`authentication policy`
 "callback"; it is a callable that accepts a userid and a request.  If the
-userid exists in the system, the callback will
-return a sequence of group identifiers (or an empty sequence if the user
-isn't a member of any groups).  If the userid *does not* exist in the system,
-the callback will return ``None``.  In a production system, user and group data will
-most often come from a database, but here we use "dummy" data to represent
-user and groups sources. Note that the ``editor`` user is a member of the
-``group:editors`` group in our dummy group data (the ``GROUPS`` data
-structure).
+userid exists in the system, the callback will return a sequence of group
+identifiers (or an empty sequence if the user isn't a member of any groups).
+If the userid *does not* exist in the system, the callback will return
+``None``.  In a production system, user and group data will most often come
+from a database, but here we use "dummy" data to represent user and groups
+sources. Note that the ``editor`` user is a member of the ``group:editors``
+group in our dummy group data (the ``GROUPS`` data structure).
 
 Give Our Root Resource an ACL
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
index 897775428..56f817a85 100644
--- a/docs/tutorials/wiki/basiclayout.rst
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -10,8 +10,8 @@ The source code for this tutorial stage can be browsed via
 `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/
 <http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/>`_.
 
-App Startup with ``__init__.py``
---------------------------------
+Appplication Configuration 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
@@ -45,16 +45,19 @@ point happens to be the ``main`` function within the file named
    ``http://localhost:6543/static/`` and below.  The first argument is the
    "name" ``static``, which indicates that the URL path prefix of the view
    will be ``/static``.  the The second argument of this tag is the "path",
-   which is an :term:`asset specification`, so it finds the resources it
-   should serve within the ``static`` directory inside the ``tutorial``
-   package.
+   which is a relative :term:`asset specification`, so it finds the resources
+   it should serve within the ``static`` directory inside the ``tutorial``
+   package.  The scaffold could have alternately used an *absolute* asset
+   specification as the path (``tutorial:static``) but it does not.
 
 #. *Line 14*.  Perform a :term:`scan`.  A scan will find :term:`configuration
-   decoration`, such as view configuration decorators
-   (e.g. ``@view_config``) in the source code of the ``tutorial`` package and
-   will take actions based on these decorators.  The argument to
-   :meth:`~pyramid.config.Configurator.scan` is the package name to scan,
-   which is ``tutorial``.
+   decoration`, such as view configuration decorators (e.g. ``@view_config``)
+   in the source code of the ``tutorial`` package and will take actions based
+   on these decorators.  We don't pass any arguments to
+   :meth:`~pyramid.config.Configurator.scan`, which implies that the scan
+   should take place in the current package (in this case, ``tutorial``).
+   The scaffold could have equivalently said ``config.scan('tutorial')`` but
+   it chose to omit the package name argument.
 
 #. *Line 15*.  Use the
    :meth:`pyramid.config.Configurator.make_wsgi_app` method
@@ -119,7 +122,7 @@ Let's try to understand the components in this module:
    decoration` to perform a :term:`view configuration` registration.  This
    view configuration registration will be activated when the application is
    started.  It will be activated by virtue of it being found as the result
-   of a :term:`scan` (when Line 17 of ``__init__.py`` is run).
+   of a :term:`scan` (when Line 14 of ``__init__.py`` is run).
 
    The ``@view_config`` decorator accepts a number of keyword arguments.  We
    use two keyword arguments here: ``context`` and ``renderer``.
@@ -131,12 +134,15 @@ Let's try to understand the components in this module:
    model, this view callable will be invoked.
 
    The ``renderer`` argument names an :term:`asset specification` of
-   ``tutorial:templates/mytemplate.pt``.  This asset specification points at
-   a :term:`Chameleon` template which lives in the ``mytemplate.pt`` file
+   ``templates/mytemplate.pt``.  This asset specification points at a
+   :term:`Chameleon` template which lives in the ``mytemplate.pt`` file
    within the ``templates`` directory of the ``tutorial`` package.  And
    indeed if you look in the ``templates`` directory of this package, you'll
    see a ``mytemplate.pt`` template file, which renders the default home page
-   of the generated project.
+   of the generated project.  This asset specification is *relative* (to the
+   view.py's current package).  We could have alternately an used the
+   absolute asset specification ``tutorial:templates/mytemplate.pt``, but
+   chose to use the relative version.
 
    Since this call to ``@view_config`` doesn't pass a ``name`` argument, the
    ``my_view`` function which it decorates represents the "default" view
diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst
index 15b9f13ab..371cae8eb 100644
--- a/docs/tutorials/wiki/definingviews.rst
+++ b/docs/tutorials/wiki/definingviews.rst
@@ -293,7 +293,7 @@ replicate within the body of this guide, however it is available `online
 <http://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki/src/views/tutorial/static/pylons.css>`_.
 
 This CSS file will be accessed via
-e.g. ``http://localhost:6543/static/pylons.css`` by virtue of the call to
+e.g. ``/static/pylons.css`` by virtue of the call to
 ``add_static_view`` directive we've made in the ``__init__.py`` file.  Any
 number and type of static assets can be placed in this directory (or
 subdirectories) and are just referred to by URL.
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/views.py b/docs/tutorials/wiki/src/basiclayout/tutorial/views.py
index 9dfdee3f1..4265b6bf7 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/views.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/views.py
@@ -1,7 +1,6 @@
 from pyramid.view import view_config
 from .models import MyModel
 
-@view_config(context=MyModel,
-             renderer='templates/mytemplate.pt')
+@view_config(context=MyModel, renderer='templates/mytemplate.pt')
 def my_view(request):
     return {'project':'tutorial'}
diff --git a/docs/tutorials/wiki/src/views/tutorial/views.py b/docs/tutorials/wiki/src/views/tutorial/views.py
index 862bd0da9..016f5b6bb 100644
--- a/docs/tutorials/wiki/src/views/tutorial/views.py
+++ b/docs/tutorials/wiki/src/views/tutorial/views.py
@@ -13,8 +13,7 @@ wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")
 def view_wiki(context, request):
     return HTTPFound(location=request.resource_url(context, 'FrontPage'))
 
-@view_config(context='.models.Page',
-             renderer='templates/view.pt')
+@view_config(context='.models.Page', renderer='templates/view.pt')
 def view_page(context, request):
     wiki = context.__parent__
 
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index db8ab1fbe..dc5664c5b 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -2,82 +2,96 @@
 Basic Layout
 ============
 
-The starter files generated by the ``alchemy`` scaffold are
-basic, but they provide a good orientation for the high-level patterns common
-to most :term:`url dispatch` -based :app:`Pyramid` projects.
+The starter files generated by the ``alchemy`` scaffold are very basic, but
+they provide a good orientation for the high-level patterns common to most
+:term:`url dispatch` -based :app:`Pyramid` projects.
 
 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/>`_.
 
-App Startup with ``__init__.py``
---------------------------------
+Application Configuration 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.  We use ``__init__.py`` both as a package marker and to contain
-configuration code.
+package.  We use ``__init__.py`` both as a marker indicating the directory
+it's contained within is a package, and to contain configuration code.  Our
+``__init__.py`` file will look like this:
 
-The generated ``development.ini`` file is read by ``pserve`` which looks for
-the application module in the ``use`` variable of the ``app:main``
-section. The *entry point* is defined in the Setuptools configuration of this
-module, specifically in the ``setup.py`` file. For this tutorial, the *entry
-point* is defined as ``tutorial:main`` and points to a function named
-``main``.
+   .. literalinclude:: src/basiclayout/tutorial/__init__.py
+      :linenos:
+      :language: py
 
-First we need some imports to support later code:
+Let's go over this piece-by-piece.  First, we need some imports to support
+later code:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
       :end-before: main
       :linenos:
       :language: py
 
-Next we define the main function and create a SQLAlchemy database engine from
-the ``sqlalchemy.`` prefixed settings in the ``development.ini`` file's
-``[app:main]`` section.  This will be a URI (something like
-``sqlite://``):
+``__init__.py`` defines a function named ``main``.  Here is the entirety of
+the ``main`` function we've defined in our ``__init__.py``:
+
+   .. literalinclude:: src/basiclayout/tutorial/__init__.py
+      :pyobject: main
+      :linenos:
+      :language: py
+
+When you invoke the ``pserve development.ini`` command, the ``main`` function
+above is executed.  It accepts some settings and returns a :term:`WSGI`
+application.  You can read :ref:`startup_chapter` for details about *how*
+this function is found and called when you run ``pserve``, but for purposes
+of brevity, we'll elide the details here.
+
+The main function first creates a SQLAlchemy database engine using
+``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the
+``development.ini`` file's ``[app:main]`` section.  This will be a URI
+(something like ``sqlite://``):
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 6-9
+      :lines: 9
       :linenos:
       :language: py
 
-We then initialize our SQL database using SQLAlchemy, passing
-it the engine:
+``main`` then initializes our SQL database using SQLAlchemy, passing it the
+engine:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
       :lines: 10
       :language: py
 
-The next step is to construct a :term:`Configurator`:
+The next step of ``main`` is to construct a :term:`Configurator` object:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
       :lines: 11
       :language: py
 
 ``settings`` is passed to the Configurator as a keyword argument with the
-dictionary values passed by PasteDeploy as the ``**settings`` argument.  This
-will be a dictionary of settings parsed from the ``.ini`` file, which
-contains deployment-related values such as ``pyramid.reload_templates``,
+dictionary values passed as the ``**settings`` argument.  This will be a
+dictionary of settings parsed from the ``.ini`` file, which contains
+deployment-related values such as ``pyramid.reload_templates``,
 ``db_string``, etc.
 
-We now can call :meth:`pyramid.config.Configurator.add_static_view` with the
-arguments ``static`` (the name), and ``tutorial:static`` (the path):
+``'main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with
+two arguments: ``static`` (the name), and ``static`` (the path):
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
       :lines: 12
       :language: py
 
-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
-``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.
+This registers a static resource view which will match any URL that starts
+with the prefix ``/static`` (by virtue of the first argument to add_static
+view).  This will serve up static resources for us from within the ``static``
+directory of our ``tutorial`` package, in this case, via
+``http://localhost:6543/static/`` and below (by virtue of the second argument
+to add_static_view).  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.
 
-Using the configurator we can also register a :term:`route configuration`
+Using the configurator ``main`` also registers a :term:`route configuration`
 via the :meth:`pyramid.config.Configurator.add_route` method that will be
 used when the URL is ``/``:
 
@@ -88,44 +102,71 @@ used when the URL is ``/``:
 Since this route has a ``pattern`` equalling ``/`` it is the route that will
 be matched when the URL ``/`` is visted, e.g. ``http://localhost:6543/``.
 
-Mapping the ``home`` route to code is done by registering a view. You will
-use :meth:`pyramid.config.Configurator.add_view` in :term:`URL dispatch` to
-register views for the routes, mapping your patterns to code:
+``main`` next calls the ``scan`` method of the configurator, which will
+recursively scan our ``tutorial`` package, looking for ``@view_config`` (and
+other special) decorators.  When it finds a ``@view_config`` decorator, a
+view configuration will be registered, which will allow one of our
+application URLs to be mapped to some code.
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 14-15
+      :lines: 14
       :language: py
 
-The first positional ``add_view`` argument ``tutorial.views.my_view`` is the
-dotted name to a *function* we write (generated by the
-``alchemy`` scaffold) that is given a ``request`` object and
-which returns a response or a dictionary.  This view also names a
-``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.
-
-Finally, we use the :meth:`pyramid.config.Configurator.make_wsgi_app`
-method to return a :term:`WSGI` application:
+Finally, ``main`` is finished configuring things, so it uses the
+:meth:`pyramid.config.Configurator.make_wsgi_app` method to return a
+:term:`WSGI` application:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 16
+      :lines: 15
       :language: py
 
-Our final ``__init__.py`` file will look like this:
+View Declarations via ``views.py``
+----------------------------------
 
-   .. literalinclude:: src/basiclayout/tutorial/__init__.py
+Mapping a :term:`route` to code that will be executed when that route's
+pattern matches is done by registering a :term:`view configuration`. Our
+application uses the :meth:`pyramid.view.view_config` decorator to map view
+callables to each route, thereby mapping URL patterns to code.
+
+Here is the code in the ``views.py`` file within our package:
+
+   .. literalinclude:: src/basiclayout/tutorial/views.py
       :linenos:
       :language: py
 
+The important part to point out here is the ``@view_config`` decorator.  In
+fact, ``@view_config`` is so important that we're going to ignore the rest of
+the code in the module at this point just to explain it.  The
+``@view_config`` decorator associates the function it decorates with a
+:term:`view configuration`. The view configuration names a ``route_name``
+(``home``), and names a ``renderer``, which is a template which lives in the
+``templates`` subdirectory of the package.
+
+As the result of this view configuration, when the pattern associated with
+the view named ``home`` is matched during a request, the function named
+``my_view`` will be executed.  The the function named ``my_view`` returns a
+dictionary; the renderer will use the ``templates/mytemplate.pt`` template to
+create a response based on the values in the dictionary.
+
+Note that the decorated function named ``my_view`` accepts a single argument
+named ``request``.  This is the standard call signature for a Pyramid
+:term:`view callable`.
+
+Remember in our ``__init__.py`` when we executed the
+:meth:`pyramid.config.Configurator.scan` method, e.g. ``config.scan()``?  The
+purpose of calling the scan method was to find and process this
+``@view_config`` decorator in order to create a view configuration within our
+application.  Without being processed by ``scan``, the decorator effectively
+does nothing.  ``@view_config`` is inert without being detected via a
+:term:`scan`.
+
 Content Models with ``models.py``
 ---------------------------------
 
-In a SQLAlchemy-based application, a *model* object is an object
-composed by querying the SQL database which backs an application.
-SQLAlchemy is an "object relational mapper" (an ORM).  The
-``models.py`` file is where the ``alchemy`` scaffold
-put the classes that implement our models.
+In a SQLAlchemy-based application, a *model* object is an object composed by
+querying the SQL database.  SQLAlchemy is an "object relational mapper" (an
+ORM).  The ``models.py`` file is where the ``alchemy`` scaffold put the
+classes that implement our models.
 
 Let's take a look. First, we need some imports to support later code.
 
diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index 083ec0aa8..bc2c2de5f 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -80,6 +80,11 @@ something like this:
    :linenos:
    :language: python
 
+Populating the Database
+-----------------------
+
+XXX The ``populate_tutorial`` :term:`console script``.
+
 Viewing the Application in a Browser
 ------------------------------------
 
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index 147f7f563..381e0a90f 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -40,13 +40,6 @@ Preparation, UNIX
 
       $ bin/easy_install pyramid
 
-#. Use ``easy_install`` to install various packages from PyPI.
-
-   .. code-block:: text
-
-      $ bin/easy_install docutils nose coverage zope.sqlalchemy \
-                SQLAlchemy pyramid_tm
-
 Preparation, Windows
 --------------------
 
@@ -69,14 +62,6 @@ Preparation, Windows
 
       c:\pyramidtut> Scripts\easy_install pyramid
 
-#. Use ``easy_install`` to install various packages from PyPI.
-
-   .. code-block:: text
-
-      c:\pyramidtut> Scripts\easy_install docutils \
-               nose coverage zope.sqlalchemy SQLAlchemy pyramid_tm
-
-
 .. _sql_making_a_project:
 
 Making a Project
@@ -108,6 +93,13 @@ On Windows:
    startup problems, try putting both the virtualenv and the project
    into directories that do not contain spaces in their paths.
 
+Success executing this command will end with a line to the console something
+like::
+
+   Please run the "populate_tutorial" script to set up the SQL 
+   database before starting the application (e.g. 
+   "$myvirtualenv/bin/populate_tutorial development.ini".)
+
 Installing the Project in "Development Mode"
 ============================================
 
@@ -131,6 +123,11 @@ On Windows:
    c:\pyramidtut> cd tutorial
    c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
 
+Success executing this command will end with a line to the console something
+like::
+
+   Finished processing dependencies for tutorial==0.0
+
 .. _sql_running_tests:
 
 Running the Tests
@@ -151,6 +148,14 @@ On Windows:
 
    c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
 
+For a successful test run, you should see output like this::
+
+  .
+  ----------------------------------------------------------------------
+  Ran 1 test in 0.094s
+ 
+  OK
+
 Exposing Test Coverage Information
 ==================================
 
@@ -191,8 +196,24 @@ On Windows:
    c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial ^
          --cover-erase --with-coverage
 
-Looks like our package's ``models`` module doesn't quite have 100%
-test coverage.
+If successful, you will see output something like this::
+
+  .
+  Name               Stmts   Miss  Cover   Missing
+  ------------------------------------------------
+  tutorial              11      7    36%   9-15
+  tutorial.models       17      0   100%   
+  tutorial.scripts       0      0   100%   
+  tutorial.tests        24      0   100%   
+  tutorial.views         6      0   100%   
+  ------------------------------------------------
+  TOTAL                 58      7    88%   
+  ----------------------------------------------------------------------
+  Ran 1 test in 0.459s
+
+  OK
+
+Looks like our package doesn't quite have 100% test coverage.
 
 Starting the Application
 ========================
@@ -211,11 +232,96 @@ On Windows:
 
    c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload
 
-Visit the Application in a Browser
-==================================
+If successful, you will see something like this on your console::
+
+  Starting subprocess with file monitor
+  Starting server in PID 8966.
+  Starting HTTP server on http://0.0.0.0:6543
+
+This means the server is ready to accept requests.
+
+Populating the Database
+=======================
+
+In a web browser, visit ``http://localhost:6543/``. 
+
+You will see an error page with a title something like this::
+
+  sqlalchemy.exc.OperationalError
+
+  OperationalError: (OperationalError) no such table: models ...
+
+Oh no!  Something isn't working!
+
+This happens because we haven't populated the database with any table
+information yet.  We need to use the ``populate_tutorial`` :term:`console
+script` to populate our database before we can see the page render correctly.
+
+Stop the running Pyramid application by pressing ``ctrl-C`` in the console.
+Make sure you're still in the ``tutorial`` directory (the directory with a
+``development.ini`` in it) and type the following command:
+
+On UNIX:
+
+.. code-block:: text
+
+   $ ../bin/populate_tutorial development.ini
+
+On Windows:
+
+.. code-block:: text
+
+   c:\pyramidtut\tutorial> ..\Scripts\populate_tutorial development.ini
+
+The output to your console should be something like this::
+
+  2011-11-26 14:42:25,012 INFO  [sqlalchemy.engine.base.Engine][MainThread] 
+                                PRAGMA table_info("models")
+  2011-11-26 14:42:25,013 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
+  2011-11-26 14:42:25,013 INFO  [sqlalchemy.engine.base.Engine][MainThread] 
+  CREATE TABLE models (
+  	id INTEGER NOT NULL, 
+  	name VARCHAR(255), 
+  	value INTEGER, 
+  	PRIMARY KEY (id), 
+  	UNIQUE (name)
+  )
+  2011-11-26 14:42:25,013 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
+  2011-11-26 14:42:25,135 INFO  [sqlalchemy.engine.base.Engine][MainThread] 
+                                COMMIT
+  2011-11-26 14:42:25,137 INFO  [sqlalchemy.engine.base.Engine][MainThread] 
+                                BEGIN (implicit)
+  2011-11-26 14:42:25,138 INFO  [sqlalchemy.engine.base.Engine][MainThread] 
+                                INSERT INTO models (name, value) VALUES (?, ?)
+  2011-11-26 14:42:25,139 INFO  [sqlalchemy.engine.base.Engine][MainThread] 
+                                (u'one', 1)
+  2011-11-26 14:42:25,140 INFO  [sqlalchemy.engine.base.Engine][MainThread] 
+                                COMMIT
+
+Success!  You should now have a ``tutorial.db`` file in your current working
+directory.  This will be a SQLite database with a single table defined in it
+(``models``).
+
+Starting the Application (Again)
+================================
+
+Start the application again.
+
+On UNIX:
+
+.. code-block:: text
+
+   $ ../bin/pserve development.ini --reload
+
+On Windows:
+
+.. code-block:: text
+
+   c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload
 
-In a browser, visit ``http://localhost:6543/``.  You will see the
-generated application's default page.
+At this point, when you visit ``http://localhost:6543/`` in your web browser,
+you will no longer see an error; instead you will see the generated
+application's default page.
 
 One thing you'll notice is the "debug toolbar" icon on right hand side of the
 page.  You can read more about the purpose of the icon at
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
index b4038de3c..1f2cfd307 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
@@ -1,18 +1,15 @@
 from pyramid.config import Configurator
 from sqlalchemy import engine_from_config
 
-from tutorial.models import initialize_sql
+from .models import DBSession
 
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
     engine = engine_from_config(settings, 'sqlalchemy.')
-    initialize_sql(engine)
+    DBSession.configure(bind=engine)
     config = Configurator(settings=settings)
-    config.add_static_view('static', 'tutorial:static', cache_max_age=3600)
+    config.add_static_view('static', 'static', cache_max_age=3600)
     config.add_route('home', '/')
-    config.add_view('tutorial.views.my_view', route_name='home',
-                    renderer='templates/mytemplate.pt')
+    config.scan()
     return config.make_wsgi_app()
-
-
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
index e550e3257..631af9b6a 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
@@ -1,7 +1,9 @@
-from tutorial.models import DBSession
-from tutorial.models import MyModel
+from pyramid.view import view_config
 
+from .models import DBSession
+from .models import MyModel
+
+@view_config(route_name='home', renderer='templates/mytemplate.pt')
 def my_view(request):
-    dbsession = DBSession()
-    root = dbsession.query(MyModel).filter(MyModel.name==u'root').first()
-    return {'root':root, 'project':'tutorial'}
+    one = DBSession.query(MyModel).filter(MyModel.name==u'root').first()
+    return {'one':one, 'project':'tutorial'}