Merge remote branch 'source/master'

Conflicts:
	docs/narr/hooks.rst

1 files changed, 136 insertions, 71 deletions

diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index 565bd0e96..4d3496788 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -2,10 +2,9 @@
 Basic Layout
 ============
 
-The starter files generated by the ``pyramid_routesalchemy`` template
-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 ``pyramid_routesalchemy`` template are
+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/
@@ -23,58 +22,94 @@ The generated ``development.ini`` file is read by ``paster`` which looks for
 the application module in the ``use`` variable of the ``app:tutorial``
 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 the following ``main``
-function:
+point* is defined as ``tutorial:main`` and points to a function named ``main``.
+
+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:tutorial]`` section.  This will be a URI (something like
+``sqlite://``):
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
+      :lines: 6-9
       :linenos:
       :language: py
 
-#. *Lines 1-4*. Imports to support later code.
-
-#. *Line 9*. Create a SQLAlchemy database engine from the ``sqlalchemy.``
-   prefixed settings in the ``development.ini`` file's ``[app:tutorial]``
-   section.  This will be a URI (something like ``sqlite://``).
-
-#. *Line 10*. We initialize our SQL database using SQLAlchemy, passing
-   it the engine
-
-#. *Line 11*.  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 12*.  We call
-   :meth:`pyramid.config.Configurator.add_static_view` with the
-   arguments ``static`` (the name), and ``tutorial:static`` (the path).  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.
-
-#. *Lines 13-14*.  Register a :term:`route configuration` via the
-   :meth:`pyramid.config.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.config.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.
-
-#. *Line 15*.  We use the
-   :meth:`pyramid.config.Configurator.make_wsgi_app` method to return
-   a :term:`WSGI` application.
+We then initialize 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`:
+
+   .. 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 ``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):
+
+   .. 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.
+
+Using the configurator we can also register a :term:`route configuration`
+via the :meth:`pyramid.config.Configurator.add_route` method that will be
+used when the URL is ``/``:
+
+   .. literalinclude:: src/basiclayout/tutorial/__init__.py
+      :lines: 13-14
+      :language: py
+
+Since this route has a ``pattern`` equalling ``/`` it is the route that will
+be called when the URL ``/`` is visted, e.g. ``http://localhost:6543/``.  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.config.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.
+
+Fimnally, we use the :meth:`pyramid.config.Configurator.make_wsgi_app`
+method to return a :term:`WSGI` application:
+
+   .. literalinclude:: src/basiclayout/tutorial/__init__.py
+      :lines: 15
+      :language: py
+
+Our final ``__init__.py`` file will look like this:
+
+   .. literalinclude:: src/basiclayout/tutorial/__init__.py
+      :linenos:
+      :language: py
 
 Content Models with ``models.py``
 ---------------------------------
@@ -85,34 +120,64 @@ SQLAlchemy is an "object relational mapper" (an ORM).  The
 ``models.py`` file is where the ``pyramid_routesalchemy`` Paster
 template put the classes that implement our models.
 
-Here is the source for ``models.py``:
+Let's take a look. First, we need some imports to support later code.
 
    .. literalinclude:: src/basiclayout/tutorial/models.py
+      :end-before: DBSession
       :linenos:
       :language: py
 
-#. *Lines 1-13*.  Imports to support later code.
+Next we set up a SQLAlchemy "DBSession" object: 
+
+   .. literalinclude:: src/basiclayout/tutorial/models.py
+      :lines: 15-16
+      :linenos:
+      :language: py
 
-#. *Line 15*.  We set up a SQLAlchemy "DBSession" object here.  We
-   specify that we'd like to use the "ZopeTransactionExtension".  This
-   extension is an extension which allows us to use a *transaction
-   manager* instead of controlling commits and aborts to database
-   operations by hand.
+We also need to create a declarative ``Base`` object to use as a
+base class for our model:
 
-#. *Line 16*.  We create a declarative ``Base`` object to use as a
-   base class for our model.
+   .. literalinclude:: src/basiclayout/tutorial/models.py
+      :lines: 17
+      :language: py
+
+To give a simple example of a  model class, we define one named ``MyModel``:
+
+   .. literalinclude:: src/basiclayout/tutorial/models.py
+      :pyobject: MyModel
+      :linenos:
+      :language: py
 
-#. *Lines 18-26*.  A model class named ``MyModel``.  It has an
-   ``__init__`` that takes a two arguments (``name``, and ``value``).
-   It stores these values as ``self.name`` and ``self.value`` within
-   the ``__init__`` function itself.  The ``MyModel`` class also has a
-   ``__tablename__`` attribute.  This informs SQLAlchemy which table
-   to use to store the data representing instances of this class.
+Our sample model has an ``__init__`` that takes a two arguments (``name``,
+and ``value``).  It stores these values as ``self.name`` and ``self.value``
+within the ``__init__`` function itself.  The ``MyModel`` class also has a
+``__tablename__`` attribute.  This informs SQLAlchemy which table to use to
+store the data representing instances of this class.
 
-#. *Lines 28-33*.  A function named ``populate`` which adds a single
-   model instance into our SQL storage and commits a transaction.
+Next we define a function named ``populate`` which adds a single
+model instance into our SQL storage and commits a transaction:
 
-#. *Lines 35-42*.  A function named ``initialize_sql`` which receives a SQL
-   database engine and binds it to our SQLAlchemy DBSession object.  It also
-   calls the ``populate`` function, to do initial database population.
+   .. literalinclude:: src/basiclayout/tutorial/models.py
+      :pyobject: populate
+      :linenos:
+      :language: py
+
+The function doesn't do a lot in this case, but it's there to illustrate
+how an application requiring many objects to be set up could work.
+
+Lastly we have a function named ``initialize_sql`` which receives a SQL
+database engine and binds it to our SQLAlchemy DBSession object.  It also
+calls the ``populate`` function, to do initial database population. This
+is the initialization function that is called from __init__.py above.
+
+   .. literalinclude:: src/basiclayout/tutorial/models.py
+      :pyobject: initialize_sql
+      :linenos:
+      :language: py
+
+Here is the complete source for ``models.py``:
+
+   .. literalinclude:: src/basiclayout/tutorial/models.py
+      :linenos:
+      :language: py