Merge remote-tracking branch 'refs/remotes/Pylons/master'

384 files changed, 12034 insertions, 6214 deletions

diff --git a/docs/tutorials/.gitignore b/docs/tutorials/.gitignore
new file mode 100644
index 000000000..71e689620
--- /dev/null
+++ b/docs/tutorials/.gitignore
@@ -0,0 +1 @@
+env*/
diff --git a/docs/tutorials/bfg/index.rst b/docs/tutorials/bfg/index.rst
deleted file mode 100644
index e68e63b0b..000000000
--- a/docs/tutorials/bfg/index.rst
+++ /dev/null
@@ -1,204 +0,0 @@
-.. index::
-   single: converting a BFG app
-   single: bfg2pyramid
-
-.. _converting_a_bfg_app:
-
-Converting a :mod:`repoze.bfg` Application to :app:`Pyramid`
-============================================================
-
-Prior iterations of :app:`Pyramid` were released as a package named
-:mod:`repoze.bfg`.  :mod:`repoze.bfg` users are encouraged to upgrade
-their deployments to :app:`Pyramid`, as, after the first final release
-of :app:`Pyramid`, further feature development on :mod:`repoze.bfg`
-will cease.
-
-Most existing :mod:`repoze.bfg` applications can be converted to a
-:app:`Pyramid` application in a completely automated fashion.
-However, if your application depends on packages which are not "core"
-parts of :mod:`repoze.bfg` but which nonetheless have ``repoze.bfg``
-in their names (e.g. ``repoze.bfg.skins``,
-``repoze.bfg.traversalwrapper``, ``repoze.bfg.jinja2``), you will need
-to find an analogue for each.  For example, by the time you read this,
-there will be a ``pyramid_jinja2`` package, which can be used instead
-of ``repoze.bfg.jinja2``.  If an analogue does not seem to exist for a
-``repoze.bfg`` add-on package that your application uses, please email
-the `Pylons-devel <http://groups.google.com/group/pylons-devel>`_
-maillist; we'll convert the package to a :app:`Pyramid` analogue for
-you.
-
-Here's how to convert a :mod:`repoze.bfg` application to a
-:app:`Pyramid` application:
-
-#. Ensure that your application works under :mod:`repoze.bfg` *version
-   1.3 or better*.  See
-   `http://docs.repoze.org/bfg/1.3/narr/install.html
-   <http://docs.repoze.org/bfg/1.3/narr/install.html>`_ for
-   :mod:`repoze.bfg` 1.3 installation instructions.  If your
-   application has an automated test suite, run it while your
-   application is using :mod:`repoze.bfg` 1.3+.  Otherwise, test it
-   manually.  It is only safe to proceed to the next step once your
-   application works under :mod:`repoze.bfg` 1.3+.
-
-   If your application has a proper set of dependencies, and a
-   standard automated test suite, you might test your
-   :mod:`repoze.bfg` application against :mod:`repoze.bfg` 1.3 like
-   so:
-
-   .. code-block:: bash
-
-     $ bfgenv/bin/python setup.py test
-
-   ``bfgenv`` above will be the virtualenv into which you've installed
-   :mod:`repoze.bfg` 1.3.
-
-#. Install :app:`Pyramid` into a *separate* virtualenv as per the
-   instructions in :ref:`installing_chapter`.  The :app:`Pyramid`
-   virtualenv should be separate from the one you've used to install
-   :mod:`repoze.bfg`.  A quick way to do this:
-
-   .. code-block:: bash
-
-      $ cd ~
-      $ virtualenv --no-site-packages pyramidenv
-      $ cd pyramidenv
-      $ bin/easy_install pyramid
-
-#. Put a *copy* of your :mod:`repoze.bfg` application into a temporary
-   location (perhaps by checking a fresh copy of the application out
-   of a version control repository).  For example:
-
-   .. code-block:: bash
-
-      $ cd /tmp
-      $ svn co http://my.server/my/bfg/application/trunk bfgapp
-
-#. Use the ``bfg2pyramid`` script present in the ``bin`` directory of
-   the :app:`Pyramid` virtualenv to convert all :mod:`repoze.bfg`
-   Python import statements into compatible :app:`Pyramid` import
-   statements. ``bfg2pyramid`` will also fix ZCML directive usages of
-   common :mod:`repoze.bfg` directives. You invoke ``bfg2pyramid`` by
-   passing it the *path* of the copy of your application.  The path
-   passed should contain a "setup.py" file, representing your
-   :mod:`repoze.bfg` application's setup script.  ``bfg2pyramid`` will
-   change the copy of the application *in place*.
-
-   .. code-block:: bash
- 
-      $ ~/pyramidenv/bfg2pyramid /tmp/bfgapp
-
-   ``bfg2pyramid`` will convert the following :mod:`repoze.bfg`
-   application aspects to :app:`Pyramid` compatible analogues:
-
-   - Python ``import`` statements naming :mod:`repoze.bfg` APIs will
-     be converted to :app:`Pyramid` compatible ``import`` statements.
-     Every Python file beneath the top-level path will be visited and
-     converted recursively, except Python files which live in
-     directories which start with a ``.`` (dot).
-
-   - Each ZCML file found (recursively) within the path will have the
-     default ``xmlns`` attribute attached to the ``configure`` tag
-     changed from ``http://namespaces.repoze.org/bfg`` to
-     ``http://pylonshq.com/pyramid``.  Every ZCML file beneath the
-     top-level path (files ending with ``.zcml``) will be visited and
-     converted recursively, except ZCML files which live in
-     directories which start with a ``.`` (dot).
-
-   - ZCML files which contain directives that have attributes which
-     name a ``repoze.bfg`` API module or attribute of an API module
-     (e.g. ``context="repoze.bfg.exceptions.NotFound"``) will be
-     converted to :app:`Pyramid` compatible ZCML attributes
-     (e.g. ``context="pyramid.exceptions.NotFound``).  Every ZCML file
-     beneath the top-level path (files ending with ``.zcml``) will be
-     visited and converted recursively, except ZCML files which live
-     in directories which start with a ``.`` (dot).
-
-#. Edit the ``setup.py`` file of the application you've just converted
-   (if you've been using the example paths, this will be
-   ``/tmp/bfgapp/setup.py``) to depend on the ``pyramid`` distribution
-   instead the of ``repoze.bfg`` distribution in its
-   ``install_requires`` list.  If you used a scaffold to
-   create the :mod:`repoze.bfg` application, you can do so by changing
-   the ``requires`` line near the top of the ``setup.py`` file.  The
-   original may look like this:
-
-   .. code-block:: text
-
-     requires = ['repoze.bfg', ... other dependencies ...]
-
-   Edit the ``setup.py`` so it has:
-
-   .. code-block:: text
-
-     requires = ['pyramid', ... other dependencies ...]
-
-   All other install-requires and tests-requires dependencies save for
-   the one on ``repoze.bfg`` can remain the same.
-
-#. Convert any ``install_requires`` dependencies your application has
-   on other add-on packages which have ``repoze.bfg`` in their names
-   to :app:`Pyramid` compatible analogues (e.g. ``repoze.bfg.jinja2``
-   should be replaced with ``pyramid_jinja2``).  You may need to
-   adjust configuration options and/or imports in your
-   :mod:`repoze.bfg` application after replacing these add-ons.  Read
-   the documentation of the :app:`Pyramid` add-on package for
-   information.
-
-#. *Only if you use ZCML and add-ons which use ZCML*: The default
-   ``xmlns`` of the ``configure`` tag in ZCML has changed.  The
-   ``bfg2pyramid`` script effects the default namespace change (it
-   changes the ``configure`` tag default ``xmlns`` from
-   ``http://namespaces.repoze.org/bfg`` to
-   ``http://pylonshq.com/pyramid``).
-
-   This means that uses of add-ons which define ZCML directives in the
-   ``http://namespaces.repoze.org/bfg`` namespace will begin to "fail"
-   (they're actually not really failing, but your ZCML assumes that
-   they will always be used within a ``configure`` tag which names the
-   ``http://namespaces.repoze.org/bfg`` namespace as its default
-   ``xmlns``). Symptom: when you attempt to start the application, an
-   error such as ``ConfigurationError: ('Unknown directive',
-   u'http://namespaces.repoze.org/bfg', u'workflow')`` is printed to
-   the console and the application fails to start.  In such a case,
-   either add an ``xmlns="http://namespaces.repoze.org/bfg"``
-   attribute to each tag which causes a failure, or define a namespace
-   alias in the configure tag and prefix each failing tag.  For
-   example, change this "failing" tag instance::
-
-     <configure xmlns="http://pylonshq.com/pyramid">
-         <failingtag attr="foo"/>
-     </configure>
- 
-   To this, which will begin to succeed::
-
-     <configure xmlns="http://pylonshq.com/pyramid"
-                xmlns:bfg="http://namespaces.repoze.org/bfg">
-         <bfg:failingtag attr="foo"/>
-     </configure>
-
-   You will also need to add the ``pyramid_zcml`` package to your
-   ``setup.py`` ``install_requires`` list.  In Pyramid, ZCML configuration
-   became an optional add-on supported by the ``pyramid_zcml`` package.
-
-#. Retest your application using :app:`Pyramid`.  This might be as
-   easy as:
-
-   .. code-block:: bash
-
-     $ cd /tmp/bfgapp
-     $ ~/pyramidenv/bin/python setup.py test
-
-#. Fix any test failures.
-
-#. Fix any code which generates deprecation warnings.
-
-#. Start using the converted version of your application.  Celebrate.
-
-Two terminological changes have been made to Pyramid which make its
-documentation and newer APIs different than those of ``repoze.bfg``.  The
-concept that BFG called ``model`` is called ``resource`` in Pyramid and the
-concept that BFG called ``resource`` is called ``asset`` in Pyramid.  Various
-APIs have changed as a result (although all have backwards compatible shims).
-Additionally, the environment variables that influenced server behavior which
-used to be prefixed with ``BFG_`` (such as ``BFG_DEBUG_NOTFOUND``) must now
-be prefixed with ``PYRAMID_``.
diff --git a/docs/tutorials/gae/index.rst b/docs/tutorials/gae/index.rst
deleted file mode 100644
index 9c8e8c07e..000000000
--- a/docs/tutorials/gae/index.rst
+++ /dev/null
@@ -1,231 +0,0 @@
-.. _appengine_tutorial:
-
-Running :app:`Pyramid` on Google's App Engine
-================================================
-
-It is possible to run a :app:`Pyramid` application on Google's `App
-Engine <http://code.google.com/appengine/>`_.  Content from this
-tutorial was contributed by YoungKing, based on the
-`"appengine-monkey" tutorial for Pylons
-<http://code.google.com/p/appengine-monkey/wiki/Pylons>`_.  This
-tutorial is written in terms of using the command line on a UNIX
-system; it should be possible to perform similar actions on a Windows
-system.
-
-#. Download Google's `App Engine SDK
-   <http://code.google.com/appengine/downloads.html>`_ and install it
-   on your system.
-
-#. Use Subversion to check out the source code for
-   ``appengine-monkey``.
-
-   .. code-block:: text
-
-      $ svn co http://appengine-monkey.googlecode.com/svn/trunk/ \
-          appengine-monkey
-
-#. Use ``appengine_homedir.py`` script in ``appengine-monkey`` to
-   create a :term:`virtualenv` for your application.
-
-   .. code-block:: text
- 
-      $ export GAE_PATH=/usr/local/google_appengine
-      $ python2.5 /path/to/appengine-monkey/appengine-homedir.py --gae \
-        $GAE_PATH pyramidapp
-
-   Note that ``$GAE_PATH`` should be the path where you have unpacked
-   the App Engine SDK.  (On Mac OS X at least,
-   ``/usr/local/google_appengine`` is indeed where the installer puts
-   it).
-
-   This will set up an environment in ``pyramidapp/``, with some tools
-   installed in ``pyramidapp/bin``. There will also be a directory
-   ``pyramidapp/app/`` which is the directory you will upload to
-   appengine.
-
-#. Install :app:`Pyramid` into the virtualenv
-
-   .. code-block:: text
-
-      $ cd pyramidapp/
-      $ bin/easy_install pyramid
-
-   This will install :app:`Pyramid` in the environment.
-
-#. Create your application
-
-   We'll use the standard way to create a :app:`Pyramid`
-   application, but we'll have to move some files around when we are
-   done.  The below commands assume your current working directory is
-   the ``pyramidapp`` virtualenv directory you created in the third step
-   above:
-
-   .. code-block:: text
-
-      $ cd app
-      $ rm -rf pyramidapp
-      $ bin/paster create -t pyramid_starter pyramidapp
-      $ mv pyramidapp aside
-      $ mv aside/pyramidapp .
-      $ rm -rf aside
-
-#. Edit ``config.py``
-
-   Edit the ``APP_NAME`` and ``APP_ARGS`` settings within
-   ``config.py``.  The ``APP_NAME`` must be ``pyramidapp:main``, and
-   the APP_ARGS must be ``({},)``.  Any other settings in
-   ``config.py`` should remain the same.
-
-   .. code-block:: python
-
-      APP_NAME = 'pyramidapp:main'
-      APP_ARGS = ({},)
-
-#. Edit ``runner.py``
-
-   To prevent errors for ``import site``, add this code stanza before
-   ``import site`` in app/runner.py:
-
-   .. code-block:: python
-
-      import sys
-      sys.path = [path for path in sys.path if 'site-packages' not in path]
-      import site
-
-   You will also need to comment out the line that starts with
-   ``assert sys.path`` in the file.
-
-   .. code-block:: python
-
-      # comment the sys.path assertion out
-      # assert sys.path[:len(cur_sys_path)] == cur_sys_path, (
-      #   "addsitedir() caused entries to be prepended to sys.path")
-
-   For GAE development environment 1.3.0 or better, you will also need
-   the following somewhere near the top of the ``runner.py`` file to
-   fix a compatibility issue with ``appengine-monkey``:
-
-   .. code-block:: python
-
-      import os
-      os.mkdir = None
-
-#. Run the application.  ``dev_appserver.py`` is typically installed
-   by the SDK in the global path but you need to be sure to run it
-   with Python 2.5 (or whatever version of Python your GAE SDK
-   expects).
-
-   .. code-block:: text
-      :linenos:
-
-      $ cd ../..
-      $ python2.5 /usr/local/bin/dev_appserver.py pyramidapp/app/
-
-   Startup success looks something like this:
-
-   .. code-block:: text
-
-      [chrism@vitaminf pyramid_gae]$ python2.5 \
-                    /usr/local/bin/dev_appserver.py \
-                    pyramidapp/app/
-      INFO     2009-05-03 22:23:13,887 appengine_rpc.py:157] # ... more... 
-      Running application pyramidapp on port 8080: http://localhost:8080
-
-   You may need to run "Make Symlinks" from the Google App Engine
-   Launcher GUI application if your system doesn't already have the
-   ``dev_appserver.py`` script sitting around somewhere.
-
-#. Hack on your pyramid application, using a normal run, debug, restart
-   process.  For tips on how to use the ``pdb`` module within Google
-   App Engine, `see this blog post
-   <http://jjinux.blogspot.com/2008/05/python-debugging-google-app-engine-apps.html>`_.
-   In particular, you can create a function like so and call it to
-   drop your console into a pdb trace:
-
-   .. code-block:: python
-      :linenos:
-
-      def set_trace():
-          import pdb, sys
-          debugger = pdb.Pdb(stdin=sys.__stdin__, 
-              stdout=sys.__stdout__)
-          debugger.set_trace(sys._getframe().f_back)
-
-#. `Sign up for a GAE account <http://code.google.com/appengine/>`_
-   and create an application.  You'll need a mobile phone to accept an
-   SMS in order to receive authorization.
-
-#. Edit the application's ID in ``app.yaml`` to match the application
-   name you created during GAE account setup.
-
-   .. code-block:: yaml
-
-      application: mycoolpyramidapp
-
-#. Upload the application
-
-   .. code-block:: text
-
-      $ python2.5 /usr/local/bin/appcfg.py update pyramidapp/app
-
-   You almost certainly won't hit the 3000-file GAE file number limit
-   when invoking this command.  If you do, however, it will look like
-   so:
-
-   .. code-block:: text
-
-       HTTPError: HTTP Error 400: Bad Request
-       Rolling back the update.
-       Error 400: --- begin server output ---
-       Max number of files and blobs is 3000.
-       --- end server output ---
-
-   If you do experience this error, you will be able to get around
-   this by zipping libraries. You can use ``pip`` to create zipfiles
-   from packages.  See :ref:`pip_zip` for more information about this.
-
-   A successful upload looks like so:
-
-   .. code-block:: text
-
-      [chrism@vitaminf pyramidapp]$ python2.5 /usr/local/bin/appcfg.py \
-                                    update ../pyramidapp/app/
-      Scanning files on local disk.
-      Scanned 500 files.
-      # ... more output ...
-      Will check again in 16 seconds.
-      Checking if new version is ready to serve.
-      Closing update: new version is ready to start serving.
-      Uploading index definitions.
-
-#. Visit ``http://<yourapp>.appspot.com`` in a browser.
-
-.. _pip_zip:
-
-Zipping Files Via Pip
----------------------
-
-If you hit the Google App Engine 3000-file limit, you may need to
-create zipfile archives out of some distributions installed in your
-application's virtualenv.
-
-First, see which packages are available for zipping:
-
-.. code-block:: text
-
-   $ bin/pip zip -l
-
-This shows your zipped packages (by default, none) and your unzipped
-packages. You can zip a package like so:
-
-.. code-block:: text
-
-   $ bin/pip zip pytz-2009g-py2.5.egg
-
-Note that it requires the whole egg file name.  For a :app:`Pyramid` app, the
-following packages are good candidates to be zipped.
-
-- Chameleon
-- zope.i18n
-
-Once the zipping procedure is finished you can try uploading again.
diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst
index 6e3e4ce37..3cc182d13 100644
--- a/docs/tutorials/modwsgi/index.rst
+++ b/docs/tutorials/modwsgi/index.rst
@@ -1,18 +1,17 @@
 .. _modwsgi_tutorial:
 
 Running a :app:`Pyramid` Application under ``mod_wsgi``
-==========================================================
+=======================================================
 
 :term:`mod_wsgi` is an Apache module developed by Graham Dumpleton.
 It allows :term:`WSGI` programs to be served using the Apache web
 server.
 
-This guide will outline broad steps that can be used to get a
-:app:`Pyramid` application running under Apache via ``mod_wsgi``.
-This particular tutorial was developed under Apple's Mac OS X platform
-(Snow Leopard, on a 32-bit Mac), but the instructions should be
-largely the same for all systems, delta specific path information for
-commands and files.
+This guide will outline broad steps that can be used to get a :app:`Pyramid`
+application running under Apache via ``mod_wsgi``.  This particular tutorial
+was developed under Apple's Mac OS X platform (Snow Leopard, on a 32-bit
+Mac), but the instructions should be largely the same for all systems, delta
+specific path information for commands and files.
 
 .. note:: Unfortunately these instructions almost certainly won't work for
    deploying a :app:`Pyramid` application on a Windows system using
@@ -25,21 +24,15 @@ commands and files.
     system.  If you do not, install Apache 2.X for your platform in
     whatever manner makes sense.
 
+#.  It is also assumed that you have satisfied the
+    :ref:`requirements-for-installing-packages`.
+
 #.  Once you have Apache installed, install ``mod_wsgi``.  Use the
     (excellent) `installation instructions
     <http://code.google.com/p/modwsgi/wiki/InstallationInstructions>`_
     for your platform into your system's Apache installation.
 
-#.  Install :term:`virtualenv` into the Python which mod_wsgi will
-    run using the ``easy_install`` program.
-
-    .. code-block:: text
-
-       $ sudo /usr/bin/easy_install-2.6 virtualenv
-
-    This command may need to be performed as the root user.
-
-#.  Create a :term:`virtualenv` which we'll use to install our
+#.  Create a :term:`virtual environment` which we'll use to install our
     application.
 
     .. code-block:: text
@@ -47,14 +40,14 @@ commands and files.
        $ cd ~
        $ mkdir modwsgi
        $ cd modwsgi
-       $ /usr/local/bin/virtualenv --no-site-packages env
+       $ python3 -m venv env
 
-#.  Install :app:`Pyramid` into the newly created virtualenv:
+#.  Install :app:`Pyramid` into the newly created virtual environment:
 
     .. code-block:: text
 
        $ cd ~/modwsgi/env
-       $ bin/easy_install pyramid
+       $ $VENV/bin/pip install pyramid
     
 #.  Create and install your :app:`Pyramid` application.  For the purposes of
     this tutorial, we'll just be using the ``pyramid_starter`` application as
@@ -64,20 +57,21 @@ commands and files.
     .. code-block:: text
 
        $ cd ~/modwsgi/env
-       $ bin/paster create -t pyramid_starter myapp
+       $ $VENV/bin/pcreate -s starter myapp
        $ cd myapp
-       $ ../bin/python setup.py install
+       $ $VENV/bin/pip install -e .
 
-#.  Within the virtualenv directory (``~/modwsgi/env``), create a
+#.  Within the virtual environment directory (``~/modwsgi/env``), create a
     script named ``pyramid.wsgi``.  Give it these contents:
 
     .. code-block:: python
 
-       from pyramid.paster import get_app
-       application = get_app(
-         '/Users/chrism/modwsgi/env/myapp/production.ini', 'main')
+       from pyramid.paster import get_app, setup_logging
+       ini_path = '/Users/chrism/modwsgi/env/myapp/production.ini'
+       setup_logging(ini_path)
+       application = get_app(ini_path, 'main')
 
-    The first argument to ``get_app`` is the project Paste configuration file
+    The first argument to ``get_app`` is the project configuration file
     name.  It's best to use the ``production.ini`` file provided by your
     scaffold, as it contains settings appropriate for
     production.  The second is the name of the section within the .ini file
@@ -85,12 +79,15 @@ commands and files.
     ``application`` is important: mod_wsgi requires finding such an
     assignment when it opens the file.
 
-#.  Make the ``pyramid.wsgi`` script executable.
+    The call to ``setup_logging`` initializes the standard library's
+    `logging` module to allow logging within your application.
+    See :ref:`logging_config`.
 
-    .. code-block:: text
-
-       $ cd ~/modwsgi/env
-       $ chmod 755 pyramid.wsgi
+    There is no need to make the ``pyramid.wsgi`` script executable.
+    However, you'll need to make sure that *two* users have access to change
+    into the ``~/modwsgi/env`` directory: your current user (mine is
+    ``chrism`` and the user that Apache will run as often named ``apache`` or
+    ``httpd``).  Make sure both of these users can "cd" into that directory.
 
 #.  Edit your Apache configuration and add some stuff.  I happened to
     create a file named ``/etc/apache2/other/modwsgi.conf`` on my own
@@ -99,12 +96,12 @@ commands and files.
     .. code-block:: apache
 
        # Use only 1 Python sub-interpreter.  Multiple sub-interpreters
-       # play badly with C extensions.
+       # play badly with C extensions.  See
+       # http://stackoverflow.com/a/10558360/209039
        WSGIApplicationGroup %{GLOBAL}
        WSGIPassAuthorization On
-       WSGIDaemonProcess pyramid user=chrism group=staff processes=1 \
-          threads=4 \
-          python-path=/Users/chrism/modwsgi/env/lib/python2.6/site-packages
+       WSGIDaemonProcess pyramid user=chrism group=staff threads=4 \
+          python-path=/Users/chrism/modwsgi/env/lib/python2.7/site-packages
        WSGIScriptAlias /myapp /Users/chrism/modwsgi/env/pyramid.wsgi
 
        <Directory /Users/chrism/modwsgi/env>
@@ -128,4 +125,3 @@ serve up a :app:`Pyramid` application.  See the `mod_wsgi
 configuration documentation
 <http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines>`_ for
 more in-depth configuration information.
-
diff --git a/docs/tutorials/wiki/NOTE-relocatable.txt b/docs/tutorials/wiki/NOTE-relocatable.txt
new file mode 100644
index 000000000..e942caba8
--- /dev/null
+++ b/docs/tutorials/wiki/NOTE-relocatable.txt
@@ -0,0 +1,13 @@
+We specifically use relative package references where possible so this demo
+works even if the user names their package (in the '$VENV/bin/pcreate -s
+zodb ...' step) something other than 'tutorial'.
+
+Specifically:
+
+- use relative imports
+- use plain relative URLs for resources (like stylesheets and images) in
+  page templates.
+
+Direct uses of the package name, like in __init__.py 'config.scan()'
+statements, are already adjusted by the paster/pcreate, so we don't have to
+worry about them.
diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst
index 358c1d5eb..44097b35b 100644
--- a/docs/tutorials/wiki/authorization.rst
+++ b/docs/tutorials/wiki/authorization.rst
@@ -1,297 +1,372 @@
+.. _wiki_adding_authorization:
+
 ====================
-Adding Authorization
+Adding authorization
 ====================
 
-Our application currently allows anyone with access to the server to view,
-edit, and add pages to our wiki.  For purposes of demonstration we'll change
-our application to allow people whom are members of a *group* named
-``group:editors`` to add and edit wiki pages but we'll continue allowing
-anyone with access to the server to view pages.  :app:`Pyramid` provides
-facilities for :term:`authorization` and :term:`authentication`.  We'll make
-use of both features to provide security to our application.
+:app:`Pyramid` provides facilities for :term:`authentication` and
+:term:`authorization`. We'll make use of both features to provide security to
+our application. Our application currently allows anyone with access to the
+server to view, edit, and add pages to our wiki. We'll change that to allow
+only people who are members of a *group* named ``group:editors`` to add and
+edit wiki pages, but we'll continue allowing anyone with access to the server
+to view pages.
 
-We will add an :term:`authentication policy` and an
-:term:`authorization policy` to our :term:`application
-registry`, add a ``security.py`` module and give our :term:`root`
-resource an :term:`ACL`.
+We will also add a login page and a logout link on all the pages.  The login
+page will be shown when a user is denied access to any of the views that
+require permission, instead of a default "403 Forbidden" page.
 
-Then we will add ``login`` and ``logout`` views, and modify the
-existing views to make them return a ``logged_in`` flag to the
-renderer and add :term:`permission` declarations to their ``view_config``
-decorators.
+We will implement the access control with the following steps:
 
-Finally, we will add a ``login.pt`` template and change the existing
-``view.pt`` and ``edit.pt`` to show a "Logout" link when not logged in.
+* Add users and groups (``security.py``, a new module).
+* Add an :term:`ACL` (``models.py``).
+* Add an :term:`authentication policy` and an :term:`authorization policy`
+  (``__init__.py``).
+* Add :term:`permission` declarations to the ``edit_page`` and ``add_page``
+  views (``views.py``).
 
-The source code for this tutorial stage can be browsed via
-`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/authorization/
-<http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/authorization/>`_.
+Then we will add the login and logout feature:
 
-Adding Authentication and Authorization Policies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Add ``login`` and ``logout`` views (``views.py``).
+* Add a login template (``login.pt``).
+* Make the existing views return a ``logged_in`` flag to the renderer
+  (``views.py``).
+* Add a "Logout" link to be shown when logged in and viewing or editing a page
+  (``view.pt``, ``edit.pt``).
 
-We'll change our package's ``__init__.py`` file to enable an
-``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to enable
-declarative security checking. We need to import the new policies:
 
-.. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 4-5,8
+Access control
+--------------
+
+Add users and groups
+~~~~~~~~~~~~~~~~~~~~
+
+Create a new ``tutorial/security.py`` module with the
+following content:
+
+.. literalinclude:: src/authorization/tutorial/security.py
    :linenos:
    :language: python
 
-Then, we'll add those policies to the configuration:
+The ``groupfinder`` function accepts a userid and a request and
+returns one of these values:
 
-.. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 16-18,26-28
+- If the userid exists in the system, it 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, it will return ``None``.
+
+For example, ``groupfinder('editor', request )`` returns ``['group:editor']``,
+``groupfinder('viewer', request)`` returns ``[]``, and ``groupfinder('admin',
+request)`` returns ``None``.  We will use ``groupfinder()`` as an
+:term:`authentication policy` "callback" that will provide the
+:term:`principal` or principals for a user.
+
+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.
+
+Add an ACL
+~~~~~~~~~~
+
+Open ``tutorial/models.py`` and add the following import
+statement at the head:
+
+.. literalinclude:: src/authorization/tutorial/models.py
+   :lines: 4-7
    :linenos:
    :language: python
 
-Note that the creation of an ``AuthTktAuthenticationPolicy`` requires 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 reference to a
-``groupfinder`` function in the ``tutorial`` package's ``security.py`` file.
-We haven't added that module yet, but we're about to.
-
-When you're done, your ``__init__.py`` will
-look like so:
+Add the following lines to the ``Wiki`` class:
 
-.. literalinclude:: src/authorization/tutorial/__init__.py
+.. literalinclude:: src/authorization/tutorial/models.py
+   :lines: 9-13
    :linenos:
+   :lineno-start: 9
+   :emphasize-lines: 4-5
    :language: python
 
-Adding ``security.py``
-~~~~~~~~~~~~~~~~~~~~~~
+We import :data:`~pyramid.security.Allow`, an action that means that
+permission is allowed, and :data:`~pyramid.security.Everyone`, a special
+:term:`principal` that is associated to all requests.  Both are used in the
+:term:`ACE` entries that make up the ACL.
 
-Add a ``security.py`` module within your package (in the same
-directory as ``__init__.py``, ``views.py``, etc.) with the following
-content:
+The ACL is a list that needs to be named `__acl__` and be an attribute of a
+class.  We define an :term:`ACL` with two :term:`ACE` entries: the first entry
+allows any user the `view` permission.  The second entry allows the
+``group:editors`` principal the `edit` permission.
 
-.. literalinclude:: src/authorization/tutorial/security.py
+The ``Wiki`` class that contains the ACL is the :term:`resource` constructor
+for the :term:`root` resource, which is a ``Wiki`` instance.  The ACL is
+provided to each view in the :term:`context` of the request as the ``context``
+attribute.
+
+It's only happenstance that we're assigning this ACL at class scope.  An ACL
+can be attached to an object *instance* too; this is how "row level security"
+can be achieved in :app:`Pyramid` applications.  We actually need only *one*
+ACL for the entire system, however, because our security requirements are
+simple, so this feature is not demonstrated.  See :ref:`assigning_acls` for
+more information about what an :term:`ACL` represents.
+
+Add authentication and authorization policies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Open ``tutorial/__init__.py`` and add the highlighted import
+statements:
+
+.. literalinclude:: src/authorization/tutorial/__init__.py
+   :lines: 1-8
    :linenos:
+   :emphasize-lines: 4-5,8
    :language: python
 
-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).
+Now add those policies to the configuration:
 
-Giving Our Root Resource an ACL
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: src/authorization/tutorial/__init__.py
+   :lines: 18-23
+   :linenos:
+   :lineno-start: 18
+   :emphasize-lines: 1-3,5-6
+   :language: python
 
-We need to give our root resource object an :term:`ACL`.  This ACL will be
-sufficient to provide enough information to the :app:`Pyramid` security
-machinery to challenge a user who doesn't have appropriate credentials when
-he attempts to invoke the ``add_page`` or ``edit_page`` views.
+Only the highlighted lines need to be added.
 
-We need to perform some imports at module scope in our ``models.py`` file:
+We are enabling an ``AuthTktAuthenticationPolicy``, which is based in an auth
+ticket that may be included in the request. We are also enabling an
+``ACLAuthorizationPolicy``, which uses an ACL to determine the *allow* or
+*deny* outcome for a view.
 
-.. code-block:: python
-   :linenos:
+Note 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 the
+``groupfinder()`` function that we created before.
 
-   from pyramid.security import Allow
-   from pyramid.security import Everyone
+Add permission declarations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Open ``tutorial/views.py`` and add a ``permission='edit'`` parameter
+to the ``@view_config`` decorators for ``add_page()`` and ``edit_page()``:
 
-Our root resource object is a ``Wiki`` instance.  We'll add the following
-line at class scope to our ``Wiki`` class:
+.. literalinclude:: src/authorization/tutorial/views.py
+   :lines: 50-52
+   :emphasize-lines: 2-3
+   :language: python
 
-.. code-block:: python
-   :linenos:
+.. literalinclude:: src/authorization/tutorial/views.py
+   :lines: 70-72
+   :emphasize-lines: 2-3
+   :language: python
 
-   __acl__ = [ (Allow, Everyone, 'view'),
-               (Allow, 'group:editors', 'edit') ]
+Only the highlighted lines, along with their preceding commas, need to be
+edited and added.
 
-It's only happenstance that we're assigning this ACL at class scope.  An ACL
-can be attached to an object *instance* too; this is how "row level security"
-can be achieved in :app:`Pyramid` applications.  We actually only need *one*
-ACL for the entire system, however, because our security requirements are
-simple, so this feature is not demonstrated.
+The result is that only users who possess the ``edit`` permission at the time
+of the request may invoke those two views.
 
-Our resulting ``models.py`` file will now look like so:
+Add a ``permission='view'`` parameter to the ``@view_config`` decorator for
+``view_wiki()`` and ``view_page()`` as follows:
 
-.. literalinclude:: src/authorization/tutorial/models.py
-   :linenos:
+.. literalinclude:: src/authorization/tutorial/views.py
+   :lines: 23-24
+   :emphasize-lines: 1-2
    :language: python
 
-Adding Login and Logout Views
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: src/authorization/tutorial/views.py
+   :lines: 28-29
+   :emphasize-lines: 1-2
+   :language: python
+
+Only the highlighted lines, along with their preceding commas, need to be
+edited and added.
 
-We'll add a ``login`` view which renders a login form and processes
-the post from the login form, checking credentials.
+This allows anyone to invoke these two views.
 
-We'll also add a ``logout`` view to our application and provide a link
-to it.  This view will clear the credentials of the logged in user and
+We are done with the changes needed to control access.  The changes that
+follow will add the login and logout feature.
+
+Login, logout
+-------------
+
+Add login and logout views
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We'll add a ``login`` view which renders a login form and processes the post
+from the login form, checking credentials.
+
+We'll also add a ``logout`` view callable to our application and provide a
+link to it.  This view will clear the credentials of the logged in user and
 redirect back to the front page.
 
-We'll add a different file (for presentation convenience) to add login
-and logout views.  Add a file named ``login.py`` to your application
-(in the same directory as ``views.py``) with the following content:
+Add the following import statements to the head of
+``tutorial/views.py``:
 
-.. literalinclude:: src/authorization/tutorial/login.py
-   :linenos:
+.. literalinclude:: src/authorization/tutorial/views.py
+   :lines: 6-17
+   :emphasize-lines: 1-12
    :language: python
 
-Note that the ``login`` view callable in the ``login.py`` file has *two* view
-configuration decorators.  The order of these decorators is unimportant.
-Each just adds a different :term:`view configuration` for the ``login`` view
-callable.
-
-The first view configuration decorator configures the ``login`` view callable
-so it will be invoked when someone visits ``/login`` (when the context is a
-Wiki and the view name is ``login``).  The second decorator (with context of
-``pyramid.exceptions.Forbidden``) specifies a :term:`forbidden view`.  This
-configures our login view to be presented to the user when :app:`Pyramid`
-detects that a view invocation can not be authorized.  Because we've
-configured a forbidden view, the ``login`` view callable will be invoked
-whenever one of our users tries to execute a view callable that they are not
-allowed to invoke as determined by the :term:`authorization policy` in use.
-In our application, for example, this means that if a user has not logged in,
-and he tries to add or edit a Wiki page, he will be shown the login form.
-Before being allowed to continue on to the add or edit form, he will have to
-provide credentials that give him permission to add or edit via this login
-form.
-
-Changing Existing Views
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Then we need to change each of our ``view_page``, ``edit_page`` and
-``add_page`` views in ``views.py`` to pass a "logged in" parameter
-into its template.  We'll add something like this to each view body:
-
-.. ignore-next-block
-.. code-block:: python
-   :linenos:
+All the highlighted lines need to be added or edited.
 
-   from pyramid.security import authenticated_userid
-   logged_in = authenticated_userid(request)
+:meth:`~pyramid.view.forbidden_view_config` will be used to customize the
+default 403 Forbidden page. :meth:`~pyramid.security.remember` and
+:meth:`~pyramid.security.forget` help to create and expire an auth ticket
+cookie.
 
-We'll then change the return value of each view that has an associated
-``renderer`` to pass the resulting ``logged_in`` value to the
-template.  For example:
+Now add the ``login`` and ``logout`` views at the end of the file:
 
-.. ignore-next-block
-.. code-block:: python
+.. literalinclude:: src/authorization/tutorial/views.py
+   :lines: 82-116
    :linenos:
+   :lineno-start: 82
+   :language: python
+
+``login()`` has two decorators:
+
+- a ``@view_config`` decorator which associates it with the ``login`` route
+  and makes it visible when we visit ``/login``,
+- a ``@forbidden_view_config`` decorator which turns it into a
+  :term:`forbidden view`. ``login()`` will be invoked when a user tries to
+  execute a view callable for which they lack authorization.  For example, if
+  a user has not logged in and tries to add or edit a Wiki page, they will be
+  shown the login form before being allowed to continue.
 
-   return dict(page = context,
-               content = content,
-               logged_in = logged_in,
-               edit_url = edit_url)
-
-Adding ``permission`` Declarations to our ``view_config`` Decorators
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To protect each of our views with a particular permission, we need to pass a
-``permission`` argument to each of our :class:`pyramid.view.view_config`
-decorators.  To do so, within ``views.py``:
-
-- We add ``permission='view'`` to the decorator attached to the
-  ``view_wiki`` and ``view_page`` view functions. This makes the
-  assertion that only users who possess the ``view`` permission
-  against the context resource at the time of the request may
-  invoke these views.  We've granted
-  :data:`pyramid.security.Everyone` the view permission at the
-  root model via its ACL, so everyone will be able to invoke the
-  ``view_wiki`` and ``view_page`` views.
-
-- We add ``permission='edit'`` to the decorator attached to the
-  ``add_page`` and ``edit_page`` view functions.  This makes the
-  assertion that only users who possess the effective ``edit``
-  permission against the context resource at the time of the
-  request may invoke these views.  We've granted the
-  ``group:editors`` principal the ``edit`` permission at the
-  root model via its ACL, so only a user whom is a member of
-  the group named ``group:editors`` will able to invoke the
-  ``add_page`` or  ``edit_page`` views.  We've likewise given
-  the ``editor`` user membership to this group via the
-  ``security.py`` file by mapping him to the ``group:editors``
-  group in the ``GROUPS`` data structure (``GROUPS
-  = {'editor':['group:editors']}``); the ``groupfinder``
-  function consults the ``GROUPS`` data structure.  This means
-  that the ``editor`` user can add and edit pages.
-
-Adding the ``login.pt`` Template
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Add a ``login.pt`` template to your templates directory.  It's
-referred to within the login view we just added to ``login.py``.
+The order of these two :term:`view configuration` decorators is unimportant.
+
+``logout()`` is decorated with a ``@view_config`` decorator which associates
+it with the ``logout`` route.  It will be invoked when we visit ``/logout``.
+
+Add the ``login.pt`` Template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create ``tutorial/templates/login.pt`` with the following content:
 
 .. literalinclude:: src/authorization/tutorial/templates/login.pt
-   :language: xml
+   :language: html
+
+The above template is referenced in the login view that we just added in
+``views.py``.
+
+Return a ``logged_in`` flag to the renderer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Change ``view.pt`` and ``edit.pt``
+Open ``tutorial/views.py`` again. Add a ``logged_in`` parameter to
+the return value of ``view_page()``, ``add_page()``, and ``edit_page()`` as
+follows:
+
+.. literalinclude:: src/authorization/tutorial/views.py
+   :lines: 47-48
+   :emphasize-lines: 1-2
+   :language: python
+
+.. literalinclude:: src/authorization/tutorial/views.py
+   :lines: 67-68
+   :emphasize-lines: 1-2
+   :language: python
+
+.. literalinclude:: src/authorization/tutorial/views.py
+   :lines: 78-80
+   :emphasize-lines: 2-3
+   :language: python
+
+Only the highlighted lines need to be added or edited.
+
+The :meth:`pyramid.request.Request.authenticated_userid` will be ``None`` if
+the user is not authenticated, or a userid if the user is authenticated.
+
+Add a "Logout" link when logged in
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-We'll also need to change our ``edit.pt`` and ``view.pt`` templates to
-display a "Logout" link if someone is logged in.  This link will
-invoke the logout view.
+Open ``tutorial/templates/edit.pt`` and
+``tutorial/templates/view.pt`` and add the following code as
+indicated by the highlighted lines.
 
-To do so we'll add this to both templates within the ``<div id="right"
-class="app-welcome align-right">`` div:
+.. literalinclude:: src/authorization/tutorial/templates/edit.pt
+   :lines: 34-38
+   :emphasize-lines: 3-5
+   :language: html
 
-.. code-block:: xml
+The attribute ``tal:condition="logged_in"`` will make the element be included
+when ``logged_in`` is any user id. The link will invoke the logout view.  The
+above element will not be included if ``logged_in`` is ``None``, such as when
+a user is not authenticated.
 
-   <span tal:condition="logged_in">
-      <a href="${request.application_url}/logout">Logout</a>
-   </span>
+Reviewing our changes
+---------------------
 
-Seeing Our Changes To ``views.py`` and our Templates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Our ``tutorial/__init__.py`` will look like this when we're done:
 
-Our ``views.py`` module will look something like this when we're done:
+.. literalinclude:: src/authorization/tutorial/__init__.py
+   :linenos:
+   :emphasize-lines: 4-5,8,18-20,22-23
+   :language: python
+
+Only the highlighted lines need to be added or edited.
+
+Our ``tutorial/models.py`` will look like this when we're done:
+
+.. literalinclude:: src/authorization/tutorial/models.py
+   :linenos:
+   :emphasize-lines: 4-7,12-13
+   :language: python
+
+Only the highlighted lines need to be added or edited.
+
+Our ``tutorial/views.py`` will look like this when we're done:
 
 .. literalinclude:: src/authorization/tutorial/views.py
    :linenos:
+   :emphasize-lines: 8,11-15,17,24,29,48,52,68,72,80,82-120
    :language: python
 
-Our ``edit.pt`` template will look something like this when we're done:
+Only the highlighted lines need to be added or edited.
+
+Our ``tutorial/templates/edit.pt`` template will look like this when
+we're done:
 
 .. literalinclude:: src/authorization/tutorial/templates/edit.pt
    :linenos:
-   :language: xml
+   :emphasize-lines: 36-38
+   :language: html
+
+Only the highlighted lines need to be added or edited.
 
-Our ``view.pt`` template will look something like this when we're done:
+Our ``tutorial/templates/view.pt`` template will look like this when
+we're done:
 
 .. literalinclude:: src/authorization/tutorial/templates/view.pt
    :linenos:
-   :language: xml
-
-Viewing the Application in a Browser
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We can finally examine our application in a browser.  The views we'll try are
-as follows:
-
-- Visiting ``http://localhost:6543/`` in a browser invokes the ``view_wiki``
-  view.  This always redirects to the ``view_page`` view of the ``FrontPage``
-  page resource.  It is executable by any user.
-
-- Visiting ``http://localhost:6543/FrontPage/`` in a browser invokes the
-  ``view_page`` view of the ``FrontPage`` Page resource.  This is because
-  it's the :term:`default view` (a view without a ``name``) for ``Page``
-  resources.  It is executable by any user.
-
-- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser invokes
-  the edit view for the ``FrontPage`` Page resource.  It is executable by
-  only the ``editor`` user.  If a different user (or the anonymous user)
-  invokes it, a login form will be displayed.  Supplying the credentials with
-  the username ``editor``, password ``editor`` will show the edit page form
-  being displayed.
-
-- Visiting ``http://localhost:6543/add_page/SomePageName`` in a
-  browser invokes the add view for a page.  It is executable by only
-  the ``editor`` user.  If a different user (or the anonymous user)
-  invokes it, a login form will be displayed.  Supplying the
-  credentials with the username ``editor``, password ``editor`` will
-  show the edit page form being displayed.
-
-- After logging in (as a result of hitting an edit or add page and
-  submitting the login form with the ``editor`` credentials), we'll see
-  a Logout link in the upper right hand corner.  When we click it,
-  we're logged out, and redirected back to the front page.
+   :emphasize-lines: 36-38
+   :language: html
+
+Only the highlighted lines need to be added or edited.
+
+Viewing the application in a browser
+------------------------------------
+
+We can finally examine our application in a browser (See
+:ref:`wiki-start-the-application`).  Launch a browser and visit each of the
+following URLs, checking that the result is as expected:
+
+- http://localhost:6543/ invokes the ``view_wiki`` view.  This always
+  redirects to the ``view_page`` view of the ``FrontPage`` Page resource.  It
+  is executable by any user.
+
+- http://localhost:6543/FrontPage invokes the ``view_page`` view of the
+  ``FrontPage`` Page resource. This is because it's the :term:`default view`
+  (a view without a ``name``) for ``Page`` resources.  It is executable by any
+  user.
+
+- http://localhost:6543/FrontPage/edit_page invokes the edit view for the
+  FrontPage object.  It is executable by only the ``editor`` user.  If a
+  different user (or the anonymous user) invokes it, a login form will be
+  displayed.  Supplying the credentials with the username ``editor``, password
+  ``editor`` will display the edit page form.
+
+- http://localhost:6543/add_page/SomePageName invokes the add view for a page.
+  It is executable by only the ``editor`` user.  If a different user (or the
+  anonymous user) invokes it, a login form will be displayed. Supplying the
+  credentials with the username ``editor``, password ``editor`` will display
+  the edit page form.
+
+- After logging in (as a result of hitting an edit or add page and submitting
+  the login form with the ``editor`` credentials), we'll see a Logout link in
+  the upper right hand corner.  When we click it, we're logged out, and
+  redirected back to the front page.
diff --git a/docs/tutorials/wiki/background.rst b/docs/tutorials/wiki/background.rst
index e49407b70..31dcd6b53 100644
--- a/docs/tutorials/wiki/background.rst
+++ b/docs/tutorials/wiki/background.rst
@@ -1,3 +1,5 @@
+.. _wiki_background:
+
 ==========
 Background
 ==========
@@ -11,8 +13,11 @@ Python web framework experience.
 
 To code along with this tutorial, the developer will need a UNIX
 machine with development tools (Mac OS X with XCode, any Linux or BSD
-variant, etc) *or* he will need a Windows system of any kind.
+variant, etc.) *or* a Windows system of any kind.
+
+.. warning::
 
-This tutorial targets :app:`Pyramid` version 1.0.
+  This tutorial has been written for Python 2.  It is unlikely to work
+  without modification under Python 3.
 
 Have fun!
diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
index 66cf37e4e..20bfdf754 100644
--- a/docs/tutorials/wiki/basiclayout.rst
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -1,76 +1,76 @@
+.. _wiki_basic_layout:
+
 ============
 Basic Layout
 ============
 
-The starter files generated by the ``pyramid_zodb`` scaffold are basic, but
+The starter files generated by the ``zodb`` scaffold are very basic, but
 they provide a good orientation for the high-level patterns common to most
-:term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` based) projects.
+:term:`traversal`-based (and :term:`ZODB`-based) :app:`Pyramid` projects.
 
-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``
---------------------------------
+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.  Our application uses ``__init__.py`` as both a package marker, as
-well as to contain application configuration code.
+package.  We use ``__init__.py`` both as a marker, indicating the directory in
+which it's contained is a package, and to contain application configuration
+code.
+
+When you run the application using the ``pserve`` command using the
+``development.ini`` generated configuration file, the application
+configuration points at a setuptools *entry point* described as
+``egg:tutorial``.  In our application, because the application's ``setup.py``
+file says so, this entry point happens to be the ``main`` function within the
+file named ``__init__.py``.
 
-When you run the application using the ``paster`` command using the
-``development.ini`` generated config file, the application configuration
-points at a Setuptools *entry point* described as ``egg:tutorial``.  In our
-application, because the application's ``setup.py`` file says so, this entry
-point happens to be the ``main`` function within the file named
-``__init__.py``:
+Open ``tutorial/__init__.py``.  It should already contain the following:
 
-   .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :linenos:
-      :language: py
+.. literalinclude:: src/basiclayout/tutorial/__init__.py
+  :linenos:
+  :language: py
 
 #. *Lines 1-3*.  Perform some dependency imports.
 
-#. *Line 8*. Get the ZODB configuration from the ``development.ini``
-   file's ``[app:main]`` section represented by the ``settings``
-   dictionary passed to our ``app`` function.  This will be a URI
-   (something like ``file:///path/to/Data.fs``).
+#. *Lines 6-8*.  Define a :term:`root factory` for our Pyramid application.
 
-#. *Line 12*. We create a "finder" object using the
-   ``PersistentApplicationFinder`` helper class, passing it the ZODB
-   URI and the "appmaker" we've imported from ``models.py``.
+#. *Line 11*.  ``__init__.py`` defines a function named ``main``.
 
-#. *Lines 13 - 14*.  We create a :term:`root factory` which uses the
-   finder to return a ZODB root object.
+#. *Line 14*.  We construct a :term:`Configurator` with a root
+   factory and the settings keywords parsed by :term:`PasteDeploy`.  The root
+   factory is named ``root_factory``.
 
-#. *Line 15*.  We construct a :term:`Configurator` with a :term:`root
-   factory` and the settings keywords parsed by PasteDeploy.  The root
-   factory is named ``get_root``.
+#. *Line 15*.  Include support for the :term:`Chameleon` template rendering
+   bindings, allowing us to use the ``.pt`` templates.
 
-#. *Line 16*.  Register a 'static view' which answers requests which start
-   with with URL path ``/static`` using the
-   :meth:`pyramid.config.Configurator.add_static_view method`.  This
+#. *Line 16*.  Register a "static view", which answers requests whose URL
+   paths start with ``/static``, using the
+   :meth:`pyramid.config.Configurator.add_static_view` method.  This
    statement registers a view that will serve up static assets, such as CSS
    and image files, for us, in this case, at
    ``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.
+   will be ``/static``.  The second argument of this tag is the "path",
+   which is a relative :term:`asset specification`, so it finds the resources
+   it should serve within the ``static`` directory inside the ``tutorial``
+   package.  Alternatively the scaffold could have used an *absolute* asset
+   specification as the path (``tutorial:static``).
 
 #. *Line 17*.  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 18*.  Use the
    :meth:`pyramid.config.Configurator.make_wsgi_app` method
    to return a :term:`WSGI` application.
 
-Resources and Models with ``models.py``
+Resources and models with ``models.py``
 ---------------------------------------
 
 :app:`Pyramid` uses the word :term:`resource` to describe objects arranged
@@ -79,33 +79,33 @@ hierarchically in a :term:`resource tree`.  This tree is consulted by
 tree represents the site structure, but it *also* represents the
 :term:`domain model` of the application, because each resource is a node
 stored persistently in a :term:`ZODB` database.  The ``models.py`` file is
-where the ``pyramid_zodb`` scaffold put the classes that implement our
-resource objects, each of which happens also to be a domain model object.
+where the ``zodb`` scaffold put the classes that implement our
+resource objects, each of which also happens to be a domain model object.
 
 Here is the source for ``models.py``:
 
-   .. literalinclude:: src/basiclayout/tutorial/models.py
-      :linenos:
-      :language: py
+.. literalinclude:: src/basiclayout/tutorial/models.py
+  :linenos:
+  :language: python
 
-#. *Lines 3-4*.  The ``MyModel`` :term:`resource` class is implemented here.
-   Instances of this class will be capable of being persisted in :term:`ZODB`
+#. *Lines 4-5*.  The ``MyModel`` :term:`resource` class is implemented here.
+   Instances of this class are capable of being persisted in :term:`ZODB`
    because the class inherits from the
    :class:`persistent.mapping.PersistentMapping` class.  The ``__parent__``
    and ``__name__`` are important parts of the :term:`traversal` protocol.
    By default, have these as ``None`` indicating that this is the
    :term:`root` object.
 
-#. *Lines 6-12*.  ``appmaker`` is used to return the *application
+#. *Lines 8-14*.  ``appmaker`` is used to return the *application
    root* object.  It is called on *every request* to the
    :app:`Pyramid` application.  It also performs bootstrapping by
    *creating* an application root (inside the ZODB root object) if one
-   does not already exist.
+   does not already exist.  It is used by the ``root_factory`` we've defined
+   in our ``__init__.py``.
  
-   We do so by first seeing if the database has the persistent
-   application root.  If not, we make an instance, store it, and
-   commit the transaction.  We then return the application root
-   object.
+   Bootstrapping is done by first seeing if the database has the persistent
+   application root.  If not, we make an instance, store it, and commit the
+   transaction.  We then return the application root object.
 
 Views With ``views.py``
 -----------------------
@@ -116,19 +116,19 @@ the URL ``http://localhost:6543/``.
 
 Here is the source for ``views.py``:
 
-   .. literalinclude:: src/basiclayout/tutorial/views.py
-      :linenos:
-      :language: py
+.. literalinclude:: src/basiclayout/tutorial/views.py
+  :linenos:
+  :language: python
 
 Let's try to understand the components in this module:
 
 #. *Lines 1-2*. Perform some dependency imports.
 
-#. *Line 4*.  Use the :func:`pyramid.view.view_config` :term:`configuration
+#. *Line 5*.  Use the :func:`pyramid.view.view_config` :term:`configuration
    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``.
@@ -140,20 +140,23 @@ 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).  Alternatively we could have 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
    callable used when the context is of the type ``MyModel``.
 
-#. *Lines 5-6*.  We define a :term:`view callable` named ``my_view``, which
+#. *Lines 6-7*.  We define a :term:`view callable` named ``my_view``, which
    we decorated in the step above.  This view callable is a *function* we
-   write generated by the ``pyramid_zodb`` scaffold that is given a
+   write generated by the ``zodb`` scaffold that is given a
    ``request`` and which returns a dictionary.  The ``mytemplate.pt``
    :term:`renderer` named by the asset specification in the step above will
    convert this dictionary to a :term:`response` on our behalf.
@@ -162,45 +165,18 @@ Let's try to understand the components in this module:
    dictionary is used by the template named by the ``mytemplate.pt`` asset
    specification to fill in certain values on the page.
 
-The WSGI Pipeline in ``development.ini``
-----------------------------------------
+Configuration in ``development.ini``
+------------------------------------
 
 The ``development.ini`` (in the tutorial :term:`project` directory, as
 opposed to the tutorial :term:`package` directory) looks like this:
 
-.. literalinclude:: src/views/development.ini
-   :language: 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 don't use a pipeline: instead they expose a single WSGI
-application as "main".  Our setup is more complicated, so we use a pipeline
-composed of :term:`middleware`.
-
-The ``egg:WebError#evalerror`` middleware is at the "top" of the pipeline.
-This is middleware which displays debuggable errors in the browser while
-you're developing (not recommended for a production system).
-
-The ``egg:repoze.zodbconn#closer`` middleware is in the middle of the
-pipeline.  This is a piece of middleware which closes the ZODB connection
-opened by the ``PersistentApplicationFinder`` at the end of the request.
-
-The ``egg:repoze.retry#retry`` middleware catches ``ConflictError``
-exceptions from ZODB and retries the request up to three times (ZODB is an
-optimistic concurrency database that relies on application-level transaction
-retries when a conflict occurs).
-
-The ``tm`` middleware is the last piece of middleware in the pipeline.  This
-commits a transaction near the end of the request unless there's an exception
-raised or the HTTP response code is an error code.  The ``tm`` refers to the
-``[filter:tm]`` section beneath the pipeline declaration, which configures
-the transaction manager.
+.. literalinclude:: src/basiclayout/development.ini
+  :language: ini
 
-The final line in the ``[pipeline:main]`` section is ``tutorial``, which
-refers to the ``[app:tutorial]`` section above it.  The ``[app:tutorial]``
-section is the section which actually defines our application settings.  The
-values within this section are passed as ``**settings`` to the ``main``
+Note the existence of a ``[app:main]`` section which specifies our WSGI
+application.  Our ZODB database settings are specified as the
+``zodbconn.uri`` setting within this section.  This value, and the other
+values within this section, are passed as ``**settings`` to the ``main``
 function we defined in ``__init__.py`` when the server is started via
-``paster serve``.
+``pserve``.
diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst
index baf497458..73dce14d5 100644
--- a/docs/tutorials/wiki/definingmodels.rst
+++ b/docs/tutorials/wiki/definingmodels.rst
@@ -1,9 +1,11 @@
+.. _wiki_defining_the_domain_model:
+
 =========================
 Defining the Domain Model
 =========================
 
-The first change we'll make to our stock paster-generated application will be
-to define two :term:`resource` constructors, one representing a wiki page,
+The first change we'll make to our stock ``pcreate``-generated application will
+be to define two :term:`resource` constructors, one representing a wiki page,
 and another representing the wiki as a mapping of wiki page names to page
 objects.  We'll do this inside our ``models.py`` file.
 
@@ -14,12 +16,9 @@ constructors". Both our Page and Wiki constructors will be class objects.  A
 single instance of the "Wiki" class will serve as a container for "Page"
 objects, which will be instances of the "Page" class.
 
-The source code for this tutorial stage can be browsed via
-`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/models/
-<http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/models/>`_.
 
-Deleting the Database
----------------------
+Delete the database
+-------------------
 
 In the next step, we're going to remove the ``MyModel`` Python model
 class from our ``models.py`` file.  Since this class is referred to within
@@ -30,17 +29,23 @@ directory before proceeding any further.  It's always fine to do this as long
 as you don't care about the content of the database; the database itself will
 be recreated as necessary.
 
-Making Edits to ``models.py``
------------------------------
+Edit ``models.py``
+------------------
 
 .. note::
 
-  There is nothing automagically special about the filename ``models.py``.  A
-  project may have many models throughout its codebase in arbitrarily-named
-  files.  Files implementing models often have ``model`` in their filenames,
+  There is nothing special about the filename ``models.py``.  A
+  project may have many models throughout its codebase in arbitrarily named
+  files.  Files implementing models often have ``model`` in their filenames
   or they may live in a Python subpackage of your application package named
   ``models``, but this is only by convention.
 
+Open ``tutorial/models.py`` file and edit it to look like the following:
+
+.. literalinclude:: src/models/tutorial/models.py
+   :linenos:
+   :language: python
+
 The first thing we want to do is remove the ``MyModel`` class from the
 generated ``models.py`` file.  The ``MyModel`` class is only a sample and
 we're not going to use it.
@@ -59,11 +64,11 @@ of the root model is also always ``None``.
 Then we'll add a ``Page`` class.  This class should inherit from the
 :class:`persistent.Persistent` class.  We'll also give it an ``__init__``
 method that accepts a single parameter named ``data``.  This parameter will
-contain the :term:`ReStructuredText` body representing the wiki page content.
+contain the :term:`reStructuredText` body representing the wiki page content.
 Note that ``Page`` objects don't have an initial ``__name__`` or
 ``__parent__`` attribute.  All objects in a traversal graph must have a
 ``__name__`` and a ``__parent__`` attribute.  We don't specify these here
-because both ``__name__`` and ``__parent__`` will be set by by a :term:`view`
+because both ``__name__`` and ``__parent__`` will be set by a :term:`view`
 function when a Page is added to our Wiki mapping.
 
 As a last step, we want to change the ``appmaker`` function in our
@@ -73,28 +78,13 @@ front page) into the Wiki within the ``appmaker``.  This will provide
 :term:`traversal` a :term:`resource tree` to work against when it attempts to
 resolve URLs to resources.
 
-We're using a mini-framework callable named ``PersistentApplicationFinder``
-in our application (see ``__init__.py``).  A ``PersistentApplicationFinder``
-accepts a ZODB URL as well as an "appmaker" callback.  This callback
-typically lives in the ``models.py`` file.  We'll just change this function,
-making the necessary edits.
-
-Looking at the Result of Our Edits to ``models.py``
----------------------------------------------------
-
-The result of all of our edits to ``models.py`` will end up looking
-something like this:
-
-.. literalinclude:: src/models/tutorial/models.py
-   :linenos:
-   :language: python
-
-Viewing the Application in a Browser
-------------------------------------
+View the application in a browser
+---------------------------------
 
 We can't.  At this point, our system is in a "non-runnable" state; we'll need
 to change view-related files in the next chapter to be able to start the
-application successfully.  If you try to start the application, you'll wind
+application successfully.  If you try to start the application (See
+:ref:`wiki-start-the-application`), you'll wind
 up with a Python traceback on your console that ends with this exception:
 
 .. code-block:: text
diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst
index ae4fa6ffb..ac94d8059 100644
--- a/docs/tutorials/wiki/definingviews.rst
+++ b/docs/tutorials/wiki/definingviews.rst
@@ -1,3 +1,5 @@
+.. _wiki_defining_views:
+
 ==============
 Defining Views
 ==============
@@ -7,7 +9,9 @@ application is typically a simple Python function that accepts two
 parameters: :term:`context` and :term:`request`.  A view callable is
 assumed to return a :term:`response` object.
 
-.. note:: A :app:`Pyramid` view can also be defined as callable
+.. note::
+
+   A :app:`Pyramid` view can also be defined as callable
    which accepts *only* a :term:`request` argument.  You'll see
    this one-argument pattern used in other :app:`Pyramid` tutorials
    and applications.  Either calling convention will work in any
@@ -15,7 +19,7 @@ assumed to return a :term:`response` object.
    interchangeably as necessary. In :term:`traversal` based applications,
    URLs are mapped to a context :term:`resource`, and since our
    :term:`resource tree` also represents our application's
-   "domain model", we're often interested in the context, because
+   "domain model", we're often interested in the context because
    it represents the persistent storage of our application.  For
    this reason, in this tutorial we define views as callables that
    accept ``context`` in the callable argument list.  If you do
@@ -26,45 +30,91 @@ assumed to return a :term:`response` object.
 We're going to define several :term:`view callable` functions, then wire them
 into :app:`Pyramid` using some :term:`view configuration`.
 
-The source code for this tutorial stage can be browsed via
-`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/views/
-<http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/views/>`_.
 
 Declaring Dependencies in Our ``setup.py`` File
 ===============================================
 
 The view code in our application will depend on a package which is not a
 dependency of the original "tutorial" application.  The original "tutorial"
-application was generated by the ``paster create`` command; it doesn't know
-about our custom application requirements.  We need to add a dependency on
-the ``docutils`` package to our ``tutorial`` package's ``setup.py`` file by
-assigning this dependency to the ``install_requires`` parameter in the
-``setup`` function.
+application was generated by the ``pcreate`` command; it doesn't know
+about our custom application requirements.
 
-Our resulting ``setup.py`` should look like so:
+We need to add a dependency on the ``docutils`` package to our ``tutorial``
+package's ``setup.py`` file by assigning this dependency to the ``requires``
+parameter in the ``setup()`` function.
+
+Open ``setup.py`` and edit it to look like the following:
 
 .. literalinclude:: src/views/setup.py
    :linenos:
+   :emphasize-lines: 20
    :language: python
 
-.. note:: After these new dependencies are added, you will need to
-   rerun ``python setup.py develop`` inside the root of the
-   ``tutorial`` package to obtain and register the newly added
-   dependency package.
+Only the highlighted line needs to be added.
+
+
+Running ``pip install -e .``
+============================
+
+Since a new software dependency was added, you will need to run ``pip install
+-e .`` again inside the root of the ``tutorial`` package to obtain and register
+the newly added dependency distribution.
+
+Make sure your current working directory is the root of the project (the
+directory in which ``setup.py`` lives) and execute the following command.
+
+On UNIX:
+
+.. code-block:: bash
+
+   $ cd tutorial
+   $ $VENV/bin/pip install -e .
+
+On Windows:
+
+.. code-block:: doscon
+
+   c:\pyramidtut> cd tutorial
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e .
+
+Success executing this command will end with a line to the console something
+like:
+
+.. code-block:: text
+
+   Successfully installed docutils-0.12 tutorial-0.0
 
-Adding View Functions
-=====================
 
-We're going to add four :term:`view callable` functions to our ``views.py``
-module.  One view named ``view_wiki`` will display the wiki itself (it will
-answer on the root URL), another named ``view_page`` will display an
-individual page, another named ``add_page`` will allow a page to be added,
-and a final view named ``edit_page`` will allow a page to be edited.
+Adding view functions in ``views.py``
+=====================================
+
+It's time for a major change.  Open ``tutorial/views.py`` and edit it to look
+like the following:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :linenos:
+   :language: python
+
+We added some imports and created a regular expression to find "WikiWords".
+
+We got rid of the ``my_view`` view function and its decorator that was added
+when we originally rendered the ``zodb`` scaffold.  It was only an example and
+isn't relevant to our application.
+
+Then we added four :term:`view callable` functions to our ``views.py``
+module: 
+
+* ``view_wiki()`` - Displays the wiki itself. It will answer on the root URL.
+* ``view_page()`` - Displays an individual page.
+* ``add_page()`` - Allows the user to add a page.
+* ``edit_page()`` - Allows the user to edit a page.
+
+We'll describe each one briefly in the following sections.
 
 .. note::
 
   There is nothing special about the filename ``views.py``.  A project may
-  have many view callables throughout its codebase in arbitrarily-named
+  have many view callables throughout its codebase in arbitrarily named
   files.  Files implementing view callables often have ``view`` in their
   filenames (or may live in a Python subpackage of your application package
   named ``views``), but this is only by convention.
@@ -72,45 +122,72 @@ and a final view named ``edit_page`` will allow a page to be edited.
 The ``view_wiki`` view function
 -------------------------------
 
-The ``view_wiki`` function will be configured to respond as the default view
-callable for a Wiki resource.  We'll provide it with a ``@view_config``
-decorator which names the class ``tutorial.models.Wiki`` as its context.
-This means that when a Wiki resource is the context, and no :term:`view name`
-exists in the request, this view will be used.  The view configuration
-associated with ``view_wiki`` does not use a ``renderer`` because the view
-callable always returns a :term:`response` object rather than a dictionary.
-No renderer is necessary when a view returns a response object.
-
-The ``view_wiki`` view callable always redirects to the URL of a Page
-resource named "FrontPage".  To do so, it returns an instance of the
+Following is the code for the ``view_wiki`` view function and its decorator:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 12-14
+   :lineno-start: 12
+   :linenos:
+   :language: python
+
+.. note:: In our code, we use an *import* that is *relative* to our package
+    named ``tutorial``, meaning we can omit the name of the package in the
+    ``import`` and ``context`` statements. In our narrative, however, we refer
+    to a *class* and thus we use the *absolute* form, meaning that the name of
+    the package is included.
+
+``view_wiki()`` is the :term:`default view` that gets called when a request is
+made to the root URL of our wiki.  It always redirects to an URL which
+represents the path to our "FrontPage".
+
+We provide it with a ``@view_config`` decorator which names the class
+``tutorial.models.Wiki`` as its context. This means that when a Wiki resource
+is the context and no :term:`view name` exists in the request, then this view
+will be used.  The view configuration associated with ``view_wiki`` does not
+use a ``renderer`` because the view callable always returns a :term:`response`
+object rather than a dictionary. No renderer is necessary when a view returns
+a response object.
+
+The ``view_wiki`` view callable always redirects to the URL of a Page resource
+named "FrontPage".  To do so, it returns an instance of the
 :class:`pyramid.httpexceptions.HTTPFound` class (instances of which implement
-the WebOb :term:`response` interface).  The :func:`pyramid.url.resource_url`
-API.  :func:`pyramid.url.resource_url` constructs a URL to the ``FrontPage``
-page resource (e.g. ``http://localhost:6543/FrontPage``), and uses it as the
-"location" of the HTTPFound response, forming an HTTP redirect.
+the :class:`pyramid.interfaces.IResponse` interface, like
+:class:`pyramid.response.Response` does). It uses the
+:meth:`pyramid.request.Request.route_url` API to construct an URL to the
+``FrontPage`` page resource (i.e., ``http://localhost:6543/FrontPage``), and
+uses it as the "location" of the ``HTTPFound`` response, forming an HTTP
+redirect.
 
 The ``view_page`` view function
 -------------------------------
 
-The ``view_page`` function will be configured to respond as the default view
-of a Page resource.  We'll provide it with a ``@view_config`` decorator which
+Here is the code for the ``view_page`` view function and its decorator:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 16-33
+   :lineno-start: 16
+   :linenos:
+   :language: python
+
+The ``view_page`` function is configured to respond as the default view
+of a Page resource.  We provide it with a ``@view_config`` decorator which
 names the class ``tutorial.models.Page`` as its context.  This means that
 when a Page resource is the context, and no :term:`view name` exists in the
 request, this view will be used.  We inform :app:`Pyramid` this view will use
 the ``templates/view.pt`` template file as a ``renderer``.
 
-The ``view_page`` function generates the :term:`ReStructuredText` body of a
+The ``view_page`` function generates the :term:`reStructuredText` body of a
 page (stored as the ``data`` attribute of the context passed to the view; the
-context will be a Page resource) as HTML.  Then it substitutes an HTML anchor
-for each *WikiWord* reference in the rendered HTML using a compiled regular
-expression.
+context will be a ``Page`` resource) as HTML.  Then it substitutes an HTML
+anchor for each *WikiWord* reference in the rendered HTML using a compiled
+regular expression.
 
 The curried function named ``check`` is used as the first argument to
 ``wikiwords.sub``, indicating that it should be called to provide a value for
 each WikiWord match found in the content.  If the wiki (our page's
 ``__parent__``) already contains a page with the matched WikiWord name, the
 ``check`` function generates a view link to be used as the substitution value
-and returns it.  If the wiki does not already contain a page with with the
+and returns it.  If the wiki does not already contain a page with the
 matched WikiWord name, the function generates an "add" link as the
 substitution value and returns it.
 
@@ -118,8 +195,8 @@ As a result, the ``content`` variable is now a fully formed bit of HTML
 containing various view and add links for WikiWords based on the content of
 our current page resource.
 
-We then generate an edit URL (because it's easier to do here than in the
-template), and we wrap up a number of arguments in a dictionary and return
+We then generate an edit URL because it's easier to do here than in the
+template, and we wrap up a number of arguments in a dictionary and return
 it.
 
 The arguments we wrap into a dictionary include ``page``, ``content``, and
@@ -138,15 +215,23 @@ callable.  In the ``view_wiki`` view callable, we unconditionally return a
 The ``add_page`` view function
 ------------------------------
 
-The ``add_page`` function will be configured to respond when the context
-resource is a Wiki and the :term:`view name` is ``add_page``.  We'll provide
-it with a ``@view_config`` decorator which names the string ``add_page`` as
-its :term:`view name` (via name=), the class ``tutorial.models.Wiki`` as its
-context, and the renderer named ``templates/edit.pt``.  This means that when
-a Wiki resource is the context, and a :term:`view name` named ``add_page``
+Here is the code for the ``add_page`` view function and its decorator:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 35-50
+   :lineno-start: 35
+   :linenos:
+   :language: python
+
+The ``add_page`` function is configured to respond when the context resource
+is a Wiki and the :term:`view name` is ``add_page``.  We provide it with a
+``@view_config`` decorator which names the string ``add_page`` as its
+:term:`view name` (via ``name=``), the class ``tutorial.models.Wiki`` as its
+context, and the renderer named ``templates/edit.pt``.  This means that when a
+Wiki resource is the context, and a :term:`view name` named ``add_page``
 exists as the result of traversal, this view will be used.  We inform
-:app:`Pyramid` this view will use the ``templates/edit.pt`` template file as
-a ``renderer``.  We share the same template between add and edit views, thus
+:app:`Pyramid` this view will use the ``templates/edit.pt`` template file as a
+``renderer``.  We share the same template between add and edit views, thus
 ``edit.pt`` instead of ``add.pt``.
 
 The ``add_page`` function will be invoked when a user clicks on a WikiWord
@@ -159,7 +244,7 @@ Page resource).
 The request :term:`subpath` in :app:`Pyramid` is the sequence of names that
 are found *after* the :term:`view name` in the URL segments given in the
 ``PATH_INFO`` of the WSGI request as the result of :term:`traversal`.  If our
-add view is invoked via, e.g. ``http://localhost:6543/add_page/SomeName``,
+add view is invoked via, e.g., ``http://localhost:6543/add_page/SomeName``,
 the :term:`subpath` will be a tuple: ``('SomeName',)``.
 
 The add view takes the zeroth element of the subpath (the wiki page name),
@@ -169,14 +254,14 @@ we're trying to add.
 If the view rendering is *not* a result of a form submission (if the
 expression ``'form.submitted' in request.params`` is ``False``), the view
 renders a template.  To do so, it generates a "save url" which the template
-use as the form post URL during rendering.  We're lazy here, so we're trying
+uses as the form post URL during rendering.  We're lazy here, so we're trying
 to use the same template (``templates/edit.pt``) for the add view as well as
 the page edit view.  To do so, we create a dummy Page resource object in
 order to satisfy the edit form's desire to have *some* page object exposed as
 ``page``, and we'll render the template to a response.
 
 If the view rendering *is* a result of a form submission (if the expression
-``'form.submitted' in request.params`` is ``True``), we scrape the page body
+``'form.submitted' in request.params`` is ``True``), we grab the page body
 from the form data, create a Page object using the name in the subpath and
 the page body, and save it into "our context" (the Wiki) using the
 ``__setitem__`` method of the context. We then redirect back to the
@@ -185,8 +270,16 @@ the page body, and save it into "our context" (the Wiki) using the
 The ``edit_page`` view function
 -------------------------------
 
-The ``edit_page`` function will be configured to respond when the context is
-a Page resource and the :term:`view name` is ``edit_page``.  We'll provide it
+Here is the code for the ``edit_page`` view function and its decorator:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 52-60
+   :lineno-start: 52
+   :linenos:
+   :language: python
+
+The ``edit_page`` function is configured to respond when the context is
+a Page resource and the :term:`view name` is ``edit_page``.  We provide it
 with a ``@view_config`` decorator which names the string ``edit_page`` as its
 :term:`view name` (via ``name=``), the class ``tutorial.models.Page`` as its
 context, and the renderer named ``templates/edit.pt``.  This means that when
@@ -211,110 +304,95 @@ If the view execution *is* a result of a form submission (if the expression
 attribute of the page context.  It then redirects to the default view of the
 context (the page), which will always be the ``view_page`` view.
 
-Viewing the Result of all Our Edits to ``views.py``
-===================================================
+Adding templates
+================
 
-The result of all of our edits to ``views.py`` will leave it looking like
-this:
+The ``view_page``, ``add_page`` and ``edit_page`` views that we've added
+reference a :term:`template`.  Each template is a :term:`Chameleon`
+:term:`ZPT` template.  These templates will live in the ``templates``
+directory of our tutorial package.  Chameleon templates must have a ``.pt``
+extension to be recognized as such.
 
-.. literalinclude:: src/views/tutorial/views.py
-   :linenos:
-   :language: python
+The ``view.pt`` template
+------------------------
 
-Adding Templates
-================
+Create ``tutorial/templates/view.pt`` and add the following
+content:
+
+.. literalinclude:: src/views/tutorial/templates/view.pt
+   :linenos:
+   :language: html
 
-Most view callables we've added expected to be rendered via a
-:term:`template`.  The default templating systems in :app:`Pyramid` are
-:term:`Chameleon` and :term:`Mako`.  Chameleon is a variant of :term:`ZPT`,
-which is an XML-based templating language.  Mako is a non-XML-based
-templating language.  Because we had to pick one, we chose Chameleon for this
-tutorial.
+This template is used by ``view_page()`` for displaying a single
+wiki page. It includes:
 
-The templates we create will live in the ``templates`` directory of our
-tutorial package.  Chameleon templates must have a ``.pt`` extension to be
-recognized as such.
+- A ``div`` element that is replaced with the ``content`` value provided by
+  the view (lines 36-38).  ``content`` contains HTML, so the ``structure``
+  keyword is used to prevent escaping it (i.e., changing ">" to "&gt;", etc.)
+- A link that points at the "edit" URL which invokes the ``edit_page`` view
+  for the page being viewed (lines 40-42).
 
-The ``view.pt`` Template
+The ``edit.pt`` template
 ------------------------
 
-The ``view.pt`` template is used for viewing a single Page.  It is used by
-the ``view_page`` view function.  It should have a div that is "structure
-replaced" with the ``content`` value provided by the view.  It should also
-have a link on the rendered page that points at the "edit" URL (the URL which
-invokes the ``edit_page`` view for the page being viewed).
+Create ``tutorial/templates/edit.pt`` and add the following content:
 
-Once we're done with the ``view.pt`` template, it will look a lot like
-the below:
+.. literalinclude:: src/views/tutorial/templates/edit.pt
+   :linenos:
+   :language: html
 
-.. literalinclude:: src/views/tutorial/templates/view.pt
-   :language: xml
-
-.. note:: The names available for our use in a template are always those that
-   are present in the dictionary returned by the view callable.  But our
-   templates make use of a ``request`` object that none of our tutorial views
-   return in their dictionary.  This value appears as if "by magic".
-   However, ``request`` is one of several names that are available "by
-   default" in a template when a template renderer is used.  See
-   :ref:`chameleon_template_renderers` for more information about other names
-   that are available by default in a template when a template is used as a
-   renderer.
-
-The ``edit.pt`` Template
-------------------------
+This template is used by ``add_page()`` and ``edit_page()`` for adding and
+editing a wiki page.  It displays a page containing a form that includes:
 
-The ``edit.pt`` template is used for adding and editing a Page.  It is used
-by the ``add_page`` and ``edit_page`` view functions.  It should display a
-page containing a form that POSTs back to the "save_url" argument supplied by
-the view.  The form should have a "body" textarea field (the page data), and
-a submit button that has the name "form.submitted".  The textarea in the form
-should be filled with any existing page data when it is rendered.
+- A 10 row by 60 column ``textarea`` field named ``body`` that is filled
+  with any existing page data when it is rendered (line 45).
+- A submit button that has the name ``form.submitted`` (line 48).
 
-Once we're done with the ``edit.pt`` template, it will look a lot like the
-below:
+The form POSTs back to the ``save_url`` argument supplied by the view (line
+43).  The view will use the ``body`` and ``form.submitted`` values.
 
-.. literalinclude:: src/views/tutorial/templates/edit.pt
-   :language: xml
+.. note:: Our templates use a ``request`` object that none of our tutorial
+   views return in their dictionary. ``request`` is one of several names that
+   are available "by default" in a template when a template renderer is used.
+   See :ref:`renderer_system_values` for information about other names that
+   are available by default when a template is used as a renderer.
 
-Static Assets
+
+Static assets
 -------------
 
-Our templates name a single static asset named ``pylons.css``.  We don't need
-to create this file within our package's ``static`` directory because it was
-provided at the time we created the project. This file is a little too long to
-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>`_.
+Our templates name static assets, including CSS and images.  We don't need
+to create these files within our package's ``static`` directory because they
+were provided at the time we created the project.
 
-This CSS file will be accessed via
-e.g. ``http://localhost:6543/static/pylons.css`` by virtue of the call to
+As an example, the CSS file will be accessed via
+``http://localhost:6543/static/theme.css`` by virtue of the call to the
 ``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 or by using the convenience
-method ``static_url`` e.g. ``request.static_url('{{package}}:static/foo.css')``
-within templates.
+method ``static_url``, e.g.,
+``request.static_url('<package>:static/foo.css')`` within templates.
+
 
-Viewing the Application in a Browser
+Viewing the application in a browser
 ====================================
 
-We can finally examine our application in a
-browser.  The views we'll try are as follows:
+We can finally examine our application in a browser (See
+:ref:`wiki-start-the-application`).  Launch a browser and visit
+each of the following URLs, checking that the result is as expected:
 
-- Visiting ``http://localhost:6543/`` in a browser invokes the ``view_wiki``
-  view.  This always redirects to the ``view_page`` view of the ``FrontPage``
-  Page resource.
+- http://localhost:6543/ invokes the ``view_wiki`` view.  This always
+  redirects to the ``view_page`` view of the ``FrontPage`` Page resource.
 
-- Visiting ``http://localhost:6543/FrontPage/`` in a browser invokes
-  the ``view_page`` view of the front page resource.  This is
-  because it's the *default view* (a view without a ``name``) for Page
-  resources.
+- http://localhost:6543/FrontPage/ invokes the ``view_page`` view of the front
+  page resource.  This is because it's the :term:`default view` (a view
+  without a ``name``) for Page resources.
 
-- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser
-  invokes the edit view for the ``FrontPage`` Page resource.
+- http://localhost:6543/FrontPage/edit_page invokes the edit view for the
+  ``FrontPage`` Page resource.
 
-- Visiting ``http://localhost:6543/add_page/SomePageName`` in a
-  browser invokes the add view for a Page.
+- http://localhost:6543/add_page/SomePageName invokes the add view for a Page.
 
-- To generate an error, visit ``http://localhost:6543/add_page`` which
-  will generate an ``IndexError`` for the expression
-  ``request.subpath[0]``.  You'll see an interactive traceback
-  facility provided by :term:`WebError`.
+- To generate an error, visit http://localhost:6543/add_page which will
+  generate an ``IndexErrorr: tuple index out of range`` error. You'll see an
+  interactive traceback facility provided by :term:`pyramid_debugtoolbar`.
diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst
new file mode 100644
index 000000000..f2a02176b
--- /dev/null
+++ b/docs/tutorials/wiki/design.rst
@@ -0,0 +1,151 @@
+.. _wiki_design:
+
+======
+Design
+======
+
+Following is a quick overview of the design of our wiki application, to help
+us understand the changes that we will be making as we work through the
+tutorial.
+
+Overall
+-------
+
+We choose to use :term:`reStructuredText` markup in the wiki text. Translation
+from reStructuredText to HTML is provided by the widely used ``docutils``
+Python module.  We will add this module in the dependency list on the project
+``setup.py`` file.
+
+Models
+------
+
+The root resource named ``Wiki`` will be a mapping of wiki page
+names to page resources.  The page resources will be instances
+of a *Page* class and they store the text content.
+
+URLs like ``/PageName`` will be traversed using  Wiki[
+*PageName* ] => page, and the context that results is the page
+resource of an existing page.
+
+To add a page to the wiki, a new instance of the page resource
+is created and its name and reference are added to the Wiki
+mapping.
+
+A page named ``FrontPage`` containing the text *This is the front page*, will
+be created when the storage is initialized, and will be used as the wiki home
+page.
+
+Views
+-----
+
+There will be three views to handle the normal operations of adding,
+editing, and viewing wiki pages, plus one view for the wiki front page.
+Two templates will be used, one for viewing, and one for both adding
+and editing wiki pages.
+
+The default templating systems in :app:`Pyramid` are
+:term:`Chameleon` and :term:`Mako`.  Chameleon is a variant of
+:term:`ZPT`, which is an XML-based templating language.  Mako is a
+non-XML-based templating language.  Because we had to pick one,
+we chose Chameleon for this tutorial.
+
+Security
+--------
+
+We'll eventually be adding security to our application.  The components we'll
+use to do this are below.
+
+- USERS, a dictionary mapping :term:`userids <userid>` to their
+  corresponding passwords.
+
+- GROUPS, a dictionary mapping :term:`userids <userid>` to a
+  list of groups to which they belong.
+
+- ``groupfinder``, an *authorization callback* that looks up USERS and
+  GROUPS.  It will be provided in a new ``security.py`` file.
+
+- An :term:`ACL` is attached to the root :term:`resource`.  Each row below
+  details an :term:`ACE`:
+
+  +----------+----------------+----------------+
+  | Action   | Principal      | Permission     |
+  +==========+================+================+
+  | Allow    | Everyone       | View           |
+  +----------+----------------+----------------+
+  | Allow    | group:editors  | Edit           |
+  +----------+----------------+----------------+
+
+- Permission declarations are added to the views to assert the security
+  policies as each request is handled.
+
+Two additional views and one template will handle the login and
+logout tasks.
+
+Summary
+-------
+
+The URL, context, actions, template and permission associated to each view are
+listed in the following table:
+
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| URL                  |  View       |  Context        |  Action               |  Template  | Permission |
+|                      |             |                 |                       |            |            |
++======================+=============+=================+=======================+============+============+
+| /                    |  view_wiki  |  Wiki           |  Redirect to          |            |            |
+|                      |             |                 |  /FrontPage           |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /PageName            |  view_page  |  Page           |  Display existing     |  view.pt   |  view      |
+|                      |  [1]_       |                 |  page [2]_            |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |                       |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /PageName/edit_page  |  edit_page  |  Page           |  Display edit form    |  edit.pt   |  edit      |
+|                      |             |                 |  with existing        |            |            |
+|                      |             |                 |  content.             |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted, redirect  |            |            |
+|                      |             |                 |  to /PageName         |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /add_page/PageName   |  add_page   |  Wiki           |  Create the page      |  edit.pt   |  edit      |
+|                      |             |                 |  *PageName* in        |            |            |
+|                      |             |                 |  storage,  display    |            |            |
+|                      |             |                 |  the edit form        |            |            |
+|                      |             |                 |  without content.     |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted,           |            |            |
+|                      |             |                 |  redirect to          |            |            |
+|                      |             |                 |  /PageName            |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /login               |  login      |  Wiki,          |  Display login form.  |  login.pt  |            |
+|                      |             |  Forbidden [3]_ |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted,           |            |            |
+|                      |             |                 |  authenticate.        |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  - If authentication  |            |            |
+|                      |             |                 |    succeeds,          |            |            |
+|                      |             |                 |    redirect to the    |            |            |
+|                      |             |                 |    page that we       |            |            |
+|                      |             |                 |    came from.         |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  - If authentication  |            |            |
+|                      |             |                 |    fails, display     |            |            |
+|                      |             |                 |    login form with    |            |            |
+|                      |             |                 |    "login failed"     |            |            |
+|                      |             |                 |    message.           |            |            |
+|                      |             |                 |                       |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /logout              |  logout     |  Wiki           |  Redirect to          |            |            |
+|                      |             |                 |  /FrontPage           |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+
+.. [1] This is the default view for a Page context
+       when there is no view name.
+.. [2] Pyramid will return a default 404 Not Found page
+       if the page *PageName* does not exist yet.
+.. [3] ``pyramid.exceptions.Forbidden`` is reached when a
+       user tries to invoke a view that is
+       not authorized by the authorization policy.
diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst
index ed0af222f..c3037f396 100644
--- a/docs/tutorials/wiki/distributing.rst
+++ b/docs/tutorials/wiki/distributing.rst
@@ -1,42 +1,41 @@
+.. _wiki_distributing_your_application:
+
 =============================
 Distributing Your Application
 =============================
 
-Once your application works properly, you can create a "tarball" from
-it by using the ``setup.py sdist`` command.  The following commands
-assume your current working directory is the ``tutorial`` package
-we've created and that the parent directory of the ``tutorial``
-package is a virtualenv representing a :app:`Pyramid` environment.
+Once your application works properly, you can create a "tarball" from it by
+using the ``setup.py sdist`` command.  The following commands assume your
+current working directory is the ``tutorial`` package we've created and that
+the parent directory of the ``tutorial`` package is a virtual environment
+representing a :app:`Pyramid` environment.
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
-   $ ../bin/python setup.py sdist
+   $ $VENV/bin/python setup.py sdist
 
 On Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   c:\pyramidtut> ..\Scripts\python setup.py sdist
+   c:\pyramidtut> %VENV%\Scripts\python setup.py sdist
 
 The output of such a command will be something like:
 
 .. code-block:: text
 
    running sdist
-   # .. more output ..
+   # more output
    creating dist
-   tar -cf dist/tutorial-0.1.tar tutorial-0.1
-   gzip -f9 dist/tutorial-0.1.tar
-   removing 'tutorial-0.1' (and everything under it)
-
-Note that this command creates a tarball in the "dist" subdirectory
-named ``tutorial-0.1.tar.gz``.  You can send this file to your friends
-to show them your cool new application.  They should be able to
-install it by pointing the ``easy_install`` command directly at it.
-Or you can upload it to `PyPI <http://pypi.python.org>`_ and share it
-with the rest of the world, where it can be downloaded via
-``easy_install`` remotely like any other package people download from
-PyPI.
-
+   Creating tar archive
+   removing 'tutorial-0.0' (and everything under it)
+
+Note that this command creates a tarball in the "dist" subdirectory named
+``tutorial-0.0.tar.gz``.  You can send this file to your friends to show them
+your cool new application.  They should be able to install it by pointing the
+``pip install .`` command directly at it. Or you can upload it to `PyPI
+<http://pypi.python.org>`_ and share it with the rest of the world, where it
+can be downloaded via ``pip install`` remotely like any other package people
+download from PyPI.
diff --git a/docs/tutorials/wiki/index.rst b/docs/tutorials/wiki/index.rst
index 3edc6ba04..7808c7623 100644
--- a/docs/tutorials/wiki/index.rst
+++ b/docs/tutorials/wiki/index.rst
@@ -3,21 +3,22 @@
 ZODB + Traversal Wiki Tutorial
 ==============================
 
-This tutorial introduces a :term:`traversal` -based :app:`Pyramid`
-application to a developer familiar with Python.  It will be most familiar to
-developers with previous :term:`Zope` experience.  When we're done with the
-tutorial, the developer will have created a basic Wiki application with
+This tutorial introduces a :term:`ZODB` and :term:`traversal`-based
+:app:`Pyramid` application to a developer familiar with Python.  It will be
+most familiar to developers with previous :term:`Zope` experience.  When the
+is finished, the developer will have created a basic Wiki application with
 authentication.
 
 For cut and paste purposes, the source code for all stages of this
-tutorial can be browsed at
-`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/
-<http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/>`_.
+tutorial can be browsed on GitHub at `docs/tutorials/wiki/src
+<https://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src>`_,
+which corresponds to the same location if you have Pyramid sources.
 
 .. toctree::
    :maxdepth: 2
 
    background
+   design
    installation
    basiclayout
    definingmodels
@@ -25,4 +26,3 @@ tutorial can be browsed at
    authorization
    tests
    distributing
-
diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index 30fb67441..dbf995595 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -1,269 +1,394 @@
+.. _wiki_installation:
+
 ============
 Installation
 ============
 
-For the most part, the installation process for this tutorial
-duplicates the steps described in :ref:`installing_chapter` and
-:ref:`project_narr`, however it also explains how to install
-additional libraries for tutorial purposes.
+Before you begin
+----------------
+
+This tutorial assumes that you have already followed the steps in
+:ref:`installing_chapter`, except **do not create a virtual environment or
+install Pyramid**.  Thereby you will satisfy the following requirements.
+
+* A Python interpreter is installed on your operating system.
+* You've satisfied the :ref:`requirements-for-installing-packages`.
+
 
-Preparation
-========================
+Create directory to contain the project
+---------------------------------------
 
-Please take the following steps to prepare for the tutorial.  The
-steps to prepare for the tutorial are slightly different depending on
-whether you're using UNIX or Windows.
+We need a workspace for our project files.
 
-Preparation, UNIX
------------------
+On UNIX
+^^^^^^^
 
-#. If you don't already have a Python 2.6 interpreter installed on
-   your system, obtain, install, or find `Python 2.6
-   <http://python.org/download/releases/2.6.6/>`_ for your system.
+.. code-block:: bash
 
-#. Make sure the Python development headers are installed on your system.  If
-   you've installed Python from source, these will already be installed.  If
-   you're using a system Python, you may have to install a ``python-dev``
-   package (e.g. ``apt-get python-dev``).  The headers are not required for
-   Pyramid itself, just for dependencies of the tutorial.
+    $ mkdir ~/pyramidtut
 
-#. Install the latest `setuptools` into the Python you
-   obtained/installed/found in the step above: download `ez_setup.py
-   <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.6 installation:
+On Windows
+^^^^^^^^^^
 
-   .. code-block:: text
+.. code-block:: doscon
 
-    $ /path/to/my/Python-2.6/bin/python ez_setup.py
+   c:\> mkdir pyramidtut
 
-#. Use that Python's `bin/easy_install` to install `virtualenv`:
 
-   .. code-block:: text
+Create and use a virtual Python environment
+-------------------------------------------
 
-    $ /path/to/my/Python-2.6/bin/easy_install virtualenv
+Next let's create a virtual environment workspace for our project.  We will use
+the ``VENV`` environment variable instead of the absolute path of the virtual
+environment.
 
-#. Use that Python's virtualenv to make a workspace:
+On UNIX
+^^^^^^^
 
-   .. code-block:: text
+.. code-block:: bash
 
-     $ path/to/my/Python-2.6/bin/virtualenv --no-site-packages \
-               pyramidtut
+   $ export VENV=~/pyramidtut
+   $ python3 -m venv $VENV
 
-#. Switch to the ``pyramidtut`` directory:
+On Windows
+^^^^^^^^^^
 
-   .. code-block:: text
+.. code-block:: doscon
 
-     $ cd pyramidtut
+   c:\> set VENV=c:\pyramidtut
 
-#. (Optional) Consider using ``source bin/activate`` to make your
-   shell environment wired to use the virtualenv.
+Each version of Python uses different paths, so you will need to adjust the
+path to the command for your Python version.
 
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct
-   dependencies installed:
+Python 2.7:
 
-   .. code-block:: text
+.. code-block:: doscon
 
-     $ bin/easy_install pyramid
+   c:\> c:\Python27\Scripts\virtualenv %VENV%
 
-#. Use ``easy_install`` to install ``docutils``, ``repoze.tm2``,
-   ``repoze.zodbconn``, ``nose`` and ``coverage``:
+Python 3.5:
 
-   .. code-block:: text
+.. code-block:: doscon
 
-     $ bin/easy_install docutils repoze.tm2 repoze.zodbconn \
-               nose coverage
+   c:\> c:\Python35\Scripts\python -m venv %VENV%
 
-Preparation, Windows
---------------------
 
-#. Install, or find `Python 2.6
-   <http://python.org/download/releases/2.6.6/>`_ for your system.
+Upgrade ``pip`` and ``setuptools`` in the virtual environment
+-------------------------------------------------------------
 
-#. Install the latest `setuptools` into the Python you
-   obtained/installed/found in the step above: download `ez_setup.py
-   <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.6 installation using a
-   command prompt:
+On UNIX
+^^^^^^^
 
-   .. code-block:: text
+.. code-block:: bash
 
-    c:\> c:\Python26\python ez_setup.py
+    $ $VENV/bin/pip install --upgrade pip setuptools
 
-#. Use that Python's `bin/easy_install` to install `virtualenv`:
+On Windows
+^^^^^^^^^^
 
-   .. code-block:: text
+.. code-block:: doscon
 
-    c:\> c:\Python26\Scripts\easy_install virtualenv
+   c:\> %VENV%\Scripts\pip install --upgrade pip setuptools
 
-#. Use that Python's virtualenv to make a workspace:
 
-   .. code-block:: text
+Install Pyramid into the virtual Python environment
+---------------------------------------------------
 
-     c:\> c:\Python26\Scripts\virtualenv --no-site-packages pyramidtut
+On UNIX
+^^^^^^^
 
-#. Switch to the ``pyramidtut`` directory:
+.. code-block:: bash
 
-   .. code-block:: text
+   $ $VENV/bin/pip install pyramid
 
-     c:\> cd pyramidtut
+On Windows
+^^^^^^^^^^
 
-#. (Optional) Consider using ``bin\activate.bat`` to make your shell
-   environment wired to use the virtualenv.
+.. code-block:: doscon
 
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct
-   dependencies installed:
+   c:\> %VENV%\Scripts\pip install pyramid
 
-   .. code-block:: text
+Change directory to your virtual Python environment
+---------------------------------------------------
 
-     c:\pyramidtut> Scripts\easy_install pyramid
+Change directory to the ``pyramidtut`` directory, which is both your workspace
+and your virtual environment.
 
-#. Use ``easy_install`` to install ``docutils``, ``repoze.tm2``,
-   ``repoze.zodbconn``, ``nose`` and ``coverage``:
+On UNIX
+^^^^^^^
 
-   .. code-block:: text
+.. code-block:: bash
 
-     c:\pyramidtut> Scripts\easy_install docutils repoze.tm2 ^
-           repoze.zodbconn nose coverage
+   $ cd pyramidtut
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\> cd pyramidtut
 
 .. _making_a_project:
 
-Making a Project
-================
+Making a project
+----------------
 
-Your next step is to create a project.  :app:`Pyramid` supplies a
-variety of scaffolds to generate sample projects.  For this tutorial,
-we will use the :term:`ZODB` -oriented scaffold named ``pyramid_zodb``.
+Your next step is to create a project.  For this tutorial, we will use
+the :term:`scaffold` named ``zodb``, which generates an application
+that uses :term:`ZODB` and :term:`traversal`.
 
-The below instructions assume your current working directory is the
-"virtualenv" named "pyramidtut".
+:app:`Pyramid` supplies a variety of scaffolds to generate sample projects. We
+will use ``pcreate``, a script that comes with Pyramid, to create our project
+using a scaffold.
 
-On UNIX:
+By passing ``zodb`` into the ``pcreate`` command, the script creates the files
+needed to use ZODB. By passing in our application name ``tutorial``, the script
+inserts that application name into all the required files.
 
-.. code-block:: text
+The below instructions assume your current working directory is "pyramidtut".
 
-  $ bin/paster create -t pyramid_zodb tutorial
+On UNIX
+^^^^^^^
 
-On Windows:
+.. code-block:: bash
 
-.. code-block:: text
+   $ $VENV/bin/pcreate -s zodb tutorial
 
-   c:\pyramidtut> Scripts\paster create -t pyramid_zodb tutorial
+On Windows
+^^^^^^^^^^
 
-.. note:: If you are using Windows, the ``pyramid_zodb`` Paster scaffold
-   doesn't currently deal gracefully with installation into a location
-   that contains spaces in the path.  If you experience startup
-   problems, try putting both the virtualenv and the project into
-   directories that do not contain spaces in their paths.
+.. code-block:: doscon
 
-Installing the Project in "Development Mode"
-============================================
+   c:\pyramidtut> %VENV%\Scripts\pcreate -s zodb tutorial
 
-In order to do development on the project easily, you must "register"
-the project as a development egg in your workspace using the
-``setup.py develop`` command.  In order to do so, cd to the "tutorial"
-directory you created in :ref:`making_a_project`, and run the
-"setup.py develop" command using virtualenv Python interpreter.
+.. note:: If you are using Windows, the ``zodb`` scaffold may not deal
+   gracefully with installation into a location that contains spaces in the
+   path. If you experience startup problems, try putting both the virtual
+   environment and the project into directories that do not contain spaces in
+   their paths.
 
-On UNIX:
 
-.. code-block:: text
+.. _installing_project_in_dev_mode_zodb:
 
-  $ cd tutorial
-  $ ../bin/python setup.py develop
+Installing the project in development mode
+------------------------------------------
 
-On Windows:
+In order to do development on the project easily, you must "register" the
+project as a development egg in your workspace using the ``pip install -e .``
+command. In order to do so, change directory to the ``tutorial`` directory that
+you created in :ref:`making_a_project`, and run the ``pip install -e .``
+command using the virtual environment Python interpreter.
 
-.. code-block:: text
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ cd tutorial
+   $ $VENV/bin/pip install -e .
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\pyramidtut> cd tutorial
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e .
+
+The console will show ``pip`` checking for packages and installing missing
+packages. Success executing this command will show a line like the following:
+
+.. code-block:: bash
+
+   Successfully installed BTrees-4.2.0 Chameleon-2.24 Mako-1.0.4 \
+   MarkupSafe-0.23 Pygments-2.1.3 ZConfig-3.1.0 ZEO-4.2.0b1 ZODB-4.2.0 \
+   ZODB3-3.11.0 mock-2.0.0 pbr-1.8.1 persistent-4.1.1 pyramid-chameleon-0.3 \
+   pyramid-debugtoolbar-2.4.2 pyramid-mako-1.0.2 pyramid-tm-0.12.1 \
+   pyramid-zodbconn-0.7 six-1.10.0 transaction-1.4.4 tutorial waitress-0.8.10 \
+   zc.lockfile-1.1.0 zdaemon-4.1.0 zodbpickle-0.6.0 zodburi-2.0
+
+
+.. _install-testing-requirements_zodb:
+
+Install testing requirements
+----------------------------
+
+In order to run tests, we need to install the testing requirements. This is
+done through our project's ``setup.py`` file, in the ``tests_require`` and
+``extras_require`` stanzas, and by issuing the command below for your
+operating system.
+
+.. literalinclude:: src/installation/setup.py
+   :language: python
+   :linenos:
+   :lineno-start: 22
+   :lines: 22-26
+
+.. literalinclude:: src/installation/setup.py
+   :language: python
+   :linenos:
+   :lineno-start: 45
+   :lines: 45-47
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ $VENV/bin/pip install -e ".[testing]"
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e ".[testing]"
 
-  C:\pyramidtut> cd tutorial
-  C:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
 
 .. _running_tests:
 
-Running the Tests
-=================
+Run the tests
+-------------
 
-After you've installed the project in development mode, you may run
-the tests for the project.
+After you've installed the project in development mode as well as the testing
+requirements, you may run the tests for the project.
 
-On UNIX:
+On UNIX
+^^^^^^^
 
-.. code-block:: text
+.. code-block:: bash
 
-  $ ../bin/python setup.py test -q
+   $ $VENV/bin/py.test tutorial/tests.py -q
 
-On Windows:
+On Windows
+^^^^^^^^^^
 
-.. code-block:: text
+.. code-block:: doscon
+
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial\tests.py -q
+
+For a successful test run, you should see output that ends like this:
+
+.. code-block:: bash
+
+   .
+   1 passed in 0.24 seconds
+
+
+Expose test coverage information
+--------------------------------
+
+You can run the ``py.test`` command to see test coverage information. This
+runs the tests in the same way that ``py.test`` does, but provides additional
+"coverage" information, exposing which lines of your project are covered by the
+tests.
+
+We've already installed the ``pytest-cov`` package into our virtual
+environment, so we can run the tests with coverage.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test --cov=tutorial --cov-report=term-missing tutorial/tests.py
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
 
-  c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
+       --cov-report=term-missing tutorial\tests.py
 
-Starting the Application
-========================
+If successful, you will see output something like this:
+
+.. code-block:: bash
+
+   ======================== test session starts ========================
+   platform Python 3.5.1, pytest-2.9.1, py-1.4.31, pluggy-0.3.1
+   rootdir: /Users/stevepiercy/projects/pyramidtut/tutorial, inifile:
+   plugins: cov-2.2.1
+   collected 1 items
+
+   tutorial/tests.py .
+   ------------------ coverage: platform Python 3.5.1 ------------------
+   Name                   Stmts   Miss  Cover   Missing
+   ----------------------------------------------------
+   tutorial/__init__.py      12      7    42%   7-8, 14-18
+   tutorial/models.py        10      6    40%   9-14
+   tutorial/tests.py         12      0   100%
+   tutorial/views.py          4      0   100%
+   ----------------------------------------------------
+   TOTAL                     38     13    66%
+
+   ===================== 1 passed in 0.31 seconds ======================
+
+Our package doesn't quite have 100% test coverage.
+
+
+.. _wiki-start-the-application:
+
+Start the application
+---------------------
 
 Start the application.
 
-On UNIX:
+On UNIX
+^^^^^^^
 
-.. code-block:: text
+.. code-block:: bash
 
-  $ ../bin/paster serve development.ini --reload
+   $ $VENV/bin/pserve development.ini --reload
 
-On Windows:
+On Windows
+^^^^^^^^^^
 
-.. code-block:: text
+.. code-block:: doscon
 
-  c:\pyramidtut\tutorial> ..\Scripts\paster serve development.ini --reload
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload
 
-Exposing Test Coverage Information
-==================================
+.. note::
 
-You can run the ``nosetests`` command to see test coverage
-information.  This runs the tests in the same way that ``setup.py
-test`` does but provides additional "coverage" information, exposing
-which lines of your project are "covered" (or not covered) by the
-tests.
+   Your OS firewall, if any, may pop up a dialog asking for authorization
+   to allow python to accept incoming network connections.
 
-On UNIX:
+If successful, you will see something like this on your console:
 
 .. code-block:: text
 
-  $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
+    Starting subprocess with file monitor
+    Starting server in PID 95736.
+    serving on http://127.0.0.1:6543
 
-On Windows:
+This means the server is ready to accept requests.
 
-.. code-block:: text
 
-  c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial ^
-       --cover-erase --with-coverage
+Visit the application in a browser
+----------------------------------
 
-Looks like the code in the ``pyramid_zodb`` scaffold for ZODB projects is
-missing some test coverage, particularly in the file named
-``models.py``.
+In a browser, visit http://localhost:6543/. You will see the generated
+application's default page.
 
-Visit the Application in a Browser
-==================================
+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
+:ref:`debug_toolbar`.  It allows you to get information about your
+application while you develop.
 
-In a browser, visit `http://localhost:6543/ <http://localhost:6543>`_.
-You will see the generated application's default page.
 
-Decisions the ``pyramid_zodb`` Scaffold Has Made For You
-========================================================
+Decisions the ``zodb`` scaffold has made for you
+------------------------------------------------
 
-Creating a project using the ``pyramid_zodb`` scaffold makes the following
+Creating a project using the ``zodb`` scaffold makes the following
 assumptions:
 
-- you are willing to use :term:`ZODB` as persistent storage
-
-- you are willing to use :term:`traversal` to map URLs to code.
+- You are willing to use :term:`ZODB` as persistent storage.
 
-- you want to use imperative code plus a :term:`scan` to perform
-  configuration.
+- You are willing to use :term:`traversal` to map URLs to code.
 
 .. note::
 
-   :app:`Pyramid` supports any persistent storage mechanism (e.g. a SQL
-   database or filesystem files, etc).  :app:`Pyramid` also supports an
-   additional mechanism to map URLs to code (:term:`URL dispatch`).  However,
-   for the purposes of this tutorial, we'll only be using traversal and ZODB.
-
+   :app:`Pyramid` supports any persistent storage mechanism (e.g., a SQL
+   database or filesystem files).  It also supports an additional
+   mechanism to map URLs to code (:term:`URL dispatch`).  However, for the
+   purposes of this tutorial, we'll only be using traversal and ZODB.
diff --git a/docs/tutorials/wiki/src/authorization/CHANGES.txt b/docs/tutorials/wiki/src/authorization/CHANGES.txt
index e14f633ab..35a34f332 100644
--- a/docs/tutorials/wiki/src/authorization/CHANGES.txt
+++ b/docs/tutorials/wiki/src/authorization/CHANGES.txt
@@ -1,5 +1,4 @@
 0.0
 ---
 
-- Initial version
-
+-  Initial version
diff --git a/docs/tutorials/wiki/src/authorization/README.txt b/docs/tutorials/wiki/src/authorization/README.txt
index d41f7f90f..dcb3605b8 100644
--- a/docs/tutorials/wiki/src/authorization/README.txt
+++ b/docs/tutorials/wiki/src/authorization/README.txt
@@ -1,4 +1,12 @@
 tutorial README
+==================
 
+Getting Started
+---------------
 
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki/src/authorization/development.ini b/docs/tutorials/wiki/src/authorization/development.ini
index 1ba746d0e..6bf4b198e 100644
--- a/docs/tutorials/wiki/src/authorization/development.ini
+++ b/docs/tutorials/wiki/src/authorization/development.ini
@@ -1,34 +1,44 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = true
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = true
-default_locale_name = en
-zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
-
-[pipeline:main]
-pipeline =
-    egg:WebError#evalerror
-    egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
-    tutorial
-
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_zodbconn
+    pyramid_tm
+
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
-host = 0.0.0.0
+use = egg:waitress#main
+host = 127.0.0.1
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
-keys = root
+keys = root, tutorial
 
 [handlers]
 keys = console
@@ -40,6 +50,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
@@ -47,6 +62,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/authorization/production.ini b/docs/tutorials/wiki/src/authorization/production.ini
index 5c47ade9b..4e9892e7b 100644
--- a/docs/tutorials/wiki/src/authorization/production.ini
+++ b/docs/tutorials/wiki/src/authorization/production.ini
@@ -1,45 +1,36 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = false
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = false
-default_locale_name = en
-zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
-[filter:weberror]
-use = egg:WebError#error_catcher
-debug = false
-;error_log = 
-;show_exceptions_in_wsgi_errors = true
-;smtp_server = localhost
-;error_email = janitor@example.com
-;smtp_username = janitor
-;smtp_password = "janitor's password"
-;from_address = paste@localhost
-;error_subject_prefix = "Pyramid Error"
-;smtp_use_tls =
-;error_message =
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_tm
+    pyramid_zodbconn
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
-[pipeline:main]
-pipeline =
-    weberror
-    egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
-    tutorial
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
+use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial
@@ -66,6 +57,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/authorization/setup.cfg b/docs/tutorials/wiki/src/authorization/setup.cfg
deleted file mode 100644
index 3d7ea6e23..000000000
--- a/docs/tutorials/wiki/src/authorization/setup.cfg
+++ /dev/null
@@ -1,28 +0,0 @@
-[nosetests]
-match=^test
-nocapture=1
-cover-package=tutorial
-with-coverage=1
-cover-erase=1
-
-[compile_catalog]
-directory = tutorial/locale
-domain = tutorial
-statistics = true
-
-[extract_messages]
-add_comments = TRANSLATORS:
-output_file = tutorial/locale/tutorial.pot
-width = 80
-
-[init_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-
-[update_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-previous = true
-
diff --git a/docs/tutorials/wiki/src/authorization/setup.py b/docs/tutorials/wiki/src/authorization/setup.py
index adfa70c9f..beeed75c9 100644
--- a/docs/tutorials/wiki/src/authorization/setup.py
+++ b/docs/tutorials/wiki/src/authorization/setup.py
@@ -3,30 +3,39 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
-    'repoze.zodbconn',
-    'repoze.tm2>=1.0b1', # default_commit_veto
-    'repoze.retry',
+    'pyramid_chameleon',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
+    'pyramid_zodbconn',
+    'transaction',
     'ZODB3',
-    'WebError',
+    'waitress',
     'docutils',
     ]
 
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
+
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Intended Audience :: Developers",
-        "Framework :: Pylons",
-        "Programming Language :: Python",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
       author='',
       author_email='',
       url='',
@@ -34,13 +43,12 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
+      extras_require={
+          'testing': tests_require,
+      },
       install_requires=requires,
-      tests_require=requires,
-      test_suite="tutorial",
-      entry_points = """\
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-      paster_plugins=['pyramid'],
       )
-
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki/src/authorization/tutorial/__init__.py
index f7dab5f47..39b94abd1 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/authorization/tutorial/__init__.py
@@ -1,31 +1,27 @@
-from repoze.zodbconn.finder import PersistentApplicationFinder
-
 from pyramid.config import Configurator
+from pyramid_zodbconn import get_connection
+
 from pyramid.authentication import AuthTktAuthenticationPolicy
 from pyramid.authorization import ACLAuthorizationPolicy
 
-from tutorial.models import appmaker
-from tutorial.security import groupfinder
+from .models import appmaker
+from .security import groupfinder
+
+def root_factory(request):
+    conn = get_connection(request)
+    return appmaker(conn.root())
+
 
 def main(global_config, **settings):
-    """ This function returns a WSGI application.
-    
-    It is usually called by the PasteDeploy framework during 
-    ``paster serve``.
+    """ This function returns a Pyramid WSGI application.
     """
-    authn_policy = AuthTktAuthenticationPolicy(secret='sosecret',
-                                               callback=groupfinder)
+    authn_policy = AuthTktAuthenticationPolicy(
+        'sosecret', callback=groupfinder, hashalg='sha512')
     authz_policy = ACLAuthorizationPolicy()
-    zodb_uri = settings.get('zodb_uri', False)
-    if zodb_uri is False:
-        raise ValueError("No 'zodb_uri' in application configuration.")
-
-    finder = PersistentApplicationFinder(zodb_uri, appmaker)
-    def get_root(request):
-        return finder(request.environ)
-    config = Configurator(root_factory=get_root, settings=settings,
-                          authentication_policy=authn_policy,
-                          authorization_policy=authz_policy)
-    config.add_static_view('static', 'tutorial:static')
-    config.scan('tutorial')
+    config = Configurator(root_factory=root_factory, settings=settings)
+    config.set_authentication_policy(authn_policy)
+    config.set_authorization_policy(authz_policy)
+    config.include('pyramid_chameleon')
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.scan()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/login.py b/docs/tutorials/wiki/src/authorization/tutorial/login.py
deleted file mode 100644
index 463db71a6..000000000
--- a/docs/tutorials/wiki/src/authorization/tutorial/login.py
+++ /dev/null
@@ -1,45 +0,0 @@
-from pyramid.httpexceptions import HTTPFound
-
-from pyramid.security import remember
-from pyramid.security import forget
-from pyramid.view import view_config
-from pyramid.url import resource_url
-
-from tutorial.security import USERS
-
-@view_config(context='tutorial.models.Wiki', name='login',
-             renderer='templates/login.pt')
-@view_config(context='pyramid.exceptions.Forbidden',
-             renderer='templates/login.pt')
-def login(request):
-    login_url = resource_url(request.context, request, 'login')
-    referrer = request.url
-    if referrer == login_url:
-        referrer = '/' # never use the login form itself as came_from
-    came_from = request.params.get('came_from', referrer)
-    message = ''
-    login = ''
-    password = ''
-    if 'form.submitted' in request.params:
-        login = request.params['login']
-        password = request.params['password']
-        if USERS.get(login) == password:
-            headers = remember(request, login)
-            return HTTPFound(location = came_from,
-                             headers = headers)
-        message = 'Failed login'
-
-    return dict(
-        message = message,
-        url = request.application_url + '/login',
-        came_from = came_from,
-        login = login,
-        password = password,
-        )
-    
-@view_config(context='tutorial.models.Wiki', name='logout')
-def logout(request):
-    headers = forget(request)
-    return HTTPFound(location = resource_url(request.context, request),
-                     headers = headers)
-    
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/models.py b/docs/tutorials/wiki/src/authorization/tutorial/models.py
index 0a31c38be..38fdd2dfc 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/models.py
+++ b/docs/tutorials/wiki/src/authorization/tutorial/models.py
@@ -1,8 +1,10 @@
 from persistent import Persistent
 from persistent.mapping import PersistentMapping
 
-from pyramid.security import Allow
-from pyramid.security import Everyone
+from pyramid.security import (
+    Allow,
+    Everyone,
+    )
 
 class Wiki(PersistentMapping):
     __name__ = None
@@ -15,7 +17,7 @@ class Page(Persistent):
         self.data = data
 
 def appmaker(zodb_root):
-    if not 'app_root' in zodb_root:
+    if 'app_root' not in zodb_root:
         app_root = Wiki()
         frontpage = Page('This is the front page')
         app_root['FrontPage'] = frontpage
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/security.py b/docs/tutorials/wiki/src/authorization/tutorial/security.py
index cfd13071e..d88c9c71f 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/security.py
+++ b/docs/tutorials/wiki/src/authorization/tutorial/security.py
@@ -5,4 +5,3 @@ GROUPS = {'editor':['group:editors']}
 def groupfinder(userid, request):
     if userid in USERS:
         return GROUPS.get(userid, [])
-
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/favicon.ico b/docs/tutorials/wiki/src/authorization/tutorial/static/favicon.ico
deleted file mode 100644
index 71f837c9e..000000000
--- a/docs/tutorials/wiki/src/authorization/tutorial/static/favicon.ico
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/footerbg.png b/docs/tutorials/wiki/src/authorization/tutorial/static/footerbg.png
deleted file mode 100644
index 1fbc873da..000000000
--- a/docs/tutorials/wiki/src/authorization/tutorial/static/footerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/headerbg.png b/docs/tutorials/wiki/src/authorization/tutorial/static/headerbg.png
deleted file mode 100644
index 0596f2020..000000000
--- a/docs/tutorials/wiki/src/authorization/tutorial/static/headerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/ie6.css b/docs/tutorials/wiki/src/authorization/tutorial/static/ie6.css
deleted file mode 100644
index b7c8493d8..000000000
--- a/docs/tutorials/wiki/src/authorization/tutorial/static/ie6.css
+++ /dev/null
@@ -1,8 +0,0 @@
-* html img,
-* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
-this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
-this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
-);}
-#wrap{display:table;height:100%}
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/middlebg.png b/docs/tutorials/wiki/src/authorization/tutorial/static/middlebg.png
deleted file mode 100644
index 2369cfb7d..000000000
--- a/docs/tutorials/wiki/src/authorization/tutorial/static/middlebg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/pylons.css b/docs/tutorials/wiki/src/authorization/tutorial/static/pylons.css
deleted file mode 100644
index fd1914d8d..000000000
--- a/docs/tutorials/wiki/src/authorization/tutorial/static/pylons.css
+++ /dev/null
@@ -1,65 +0,0 @@
-html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */
-vertical-align:baseline;background:transparent;}
-body{line-height:1;}
-ol,ul{list-style:none;}
-blockquote,q{quotes:none;}
-blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;}
-:focus{outline:0;}
-ins{text-decoration:none;}
-del{text-decoration:line-through;}
-table{border-collapse:collapse;border-spacing:0;}
-sub{vertical-align:sub;font-size:smaller;line-height:normal;}
-sup{vertical-align:super;font-size:smaller;line-height:normal;}
-ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;}
-ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;}
-li{display:list-item;}
-ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;}
-ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;}
-ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;}
-.hidden{display:none;}
-p{line-height:1.5em;}
-h1{font-size:1.75em;line-height:1.7em;font-family:helvetica,verdana;}
-h2{font-size:1.5em;line-height:1.7em;font-family:helvetica,verdana;}
-h3{font-size:1.25em;line-height:1.7em;font-family:helvetica,verdana;}
-h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;}
-html,body{width:100%;height:100%;}
-body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;}
-a{color:#1b61d6;text-decoration:none;}
-a:hover{color:#e88f00;text-decoration:underline;}
-body h1,
-body h2,
-body h3,
-body h4,
-body h5,
-body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;}
-#wrap{min-height:100%;}
-#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;}
-#header{background:#000000;top:0;font-size:14px;}
-#footer{bottom:0;background:#000000 url(footerbg.png) repeat-x 0 top;position:relative;margin-top:-40px;clear:both;}
-.header,.footer{width:750px;margin-right:auto;margin-left:auto;}
-.wrapper{width:100%}
-#top,#top-small,#bottom{width:100%;}
-#top{color:#000000;height:230px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#top-small{color:#000000;height:60px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#bottom{color:#222;background-color:#ffffff;}
-.top,.top-small,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;}
-.top{padding-top:40px;}
-.top-small{padding-top:10px;}
-#middle{width:100%;height:100px;background:url(middlebg.png) repeat-x;border-top:2px solid #ffffff;border-bottom:2px solid #b2b2b2;}
-.app-welcome{margin-top:25px;}
-.app-name{color:#000000;font-weight:bold;}
-.bottom{padding-top:50px;}
-#left{width:350px;float:left;padding-right:25px;}
-#right{width:350px;float:right;padding-left:25px;}
-.align-left{text-align:left;}
-.align-right{text-align:right;}
-.align-center{text-align:center;}
-ul.links{margin:0;padding:0;}
-ul.links li{list-style-type:none;font-size:14px;}
-form{border-style:none;}
-fieldset{border-style:none;}
-input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;}
-input[type=text],input[type=password]{width:205px;}
-input[type=submit]{background-color:#ddd;font-weight:bold;}
-/*Opera Fix*/
-body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;}
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki/src/authorization/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki/src/authorization/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/pyramid-small.png b/docs/tutorials/wiki/src/authorization/tutorial/static/pyramid-small.png
deleted file mode 100644
index a5bc0ade7..000000000
--- a/docs/tutorials/wiki/src/authorization/tutorial/static/pyramid-small.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/pyramid.png b/docs/tutorials/wiki/src/authorization/tutorial/static/pyramid.png
index 347e05549..4ab837be9 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/static/pyramid.png
+++ b/docs/tutorials/wiki/src/authorization/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/theme.css b/docs/tutorials/wiki/src/authorization/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki/src/authorization/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/static/transparent.gif b/docs/tutorials/wiki/src/authorization/tutorial/static/transparent.gif
deleted file mode 100644
index 0341802e5..000000000
--- a/docs/tutorials/wiki/src/authorization/tutorial/static/transparent.gif
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt
index f9da6c414..823fa8972 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt
+++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt
@@ -1,62 +1,72 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
-      xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>${page.__name__} - Pyramid tutorial wiki (based on
-      TurboGears 20-Minute Wiki)</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon"
-        href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/pylons.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/ie6.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top-small">
-      <div class="top-small align-center">
-        <div>
-          <img width="220" height="50" alt="pyramid"
-        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>${page.__name__} - Pyramid tutorial wiki (based on
+    TurboGears 20-Minute Wiki)</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <p tal:condition="logged_in" class="pull-right">
+                <a href="${request.application_url}/logout">Logout</a>
+              </p>
+              <p>
+                  Editing <strong><span tal:replace="page.__name__">
+                  Page Name Goes Here</span></strong>
+              </p>
+              <p>You can return to the
+                <a href="${request.application_url}">FrontPage</a>.
+              </p>
+              <form action="${save_url}" method="post">
+                <div class="form-group">
+                  <textarea class="form-control" name="body" tal:content="page.data" rows="10" cols="60"></textarea>
+                </div>
+                <div class="form-group">
+                  <button type="submit" name="form.submitted" value="Save" class="btn btn-default">Save</button>
+                </div>
+              </form>
+            </div>
+          </div>
         </div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-right">
-        <div id="left" class="app-welcome align-left">
-          Editing <b><span tal:replace="page.__name__">Page Name
-            Goes Here</span></b><br/>
-          You can return to the
-          <a href="${request.application_url}">FrontPage</a>.<br/>
-        </div>
-        <div id="right" class="app-welcome align-right">
-          <span tal:condition="logged_in">
-              <a href="${request.application_url}/logout">Logout</a>
-          </span>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
         </div>
       </div>
     </div>
-    <div id="bottom">
-      <div class="bottom">
-        <form action="${save_url}" method="post">
-          <textarea name="body" tal:content="page.data" rows="10"
-                    cols="60"/><br/>
-          <input type="submit" name="form.submitted" value="Save"/>
-        </form>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer"
-         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
 </html>
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/login.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/login.pt
index 64e592ea9..4a938e9bb 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/templates/login.pt
+++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/login.pt
@@ -1,58 +1,74 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
-      xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>Login - Pyramid tutorial wiki (based on TurboGears
-    20-Minute Wiki)</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon"
-        href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/pylons.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/ie6.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top-small">
-      <div class="top-small align-center">
-        <div>
-          <img width="220" height="50" alt="pyramid"
-        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>Login - Pyramid tutorial wiki (based on
+    TurboGears 20-Minute Wiki)</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <p>
+                <strong>
+                  Login
+                </strong><br>
+                <span tal:replace="message"></span>
+              </p>
+              <form action="${url}" method="post">
+                <input type="hidden" name="came_from" value="${came_from}">
+                <div class="form-group">
+                  <label for="login">Username</label>
+                  <input type="text" name="login" value="${login}">
+                </div>
+                <div class="form-group">
+                  <label for="password">Password</label>
+                  <input type="password" name="password" value="${password}">
+                </div>
+                <div class="form-group">
+                  <button type="submit" name="form.submitted" value="Log In" class="btn btn-default">Log In</button>
+                </div>
+              </form>
+            </div>
+          </div>
         </div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-right">
-        <div id="left" class="app-welcome align-left">
-          <b>Login</b><br/>
-          <span tal:replace="message"/>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
         </div>
-        <div id="right" class="app-welcome align-right"></div>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <form action="${url}" method="post">
-          <input type="hidden" name="came_from" value="${came_from}"/>
-          <input type="text" name="login" value="${login}"/><br/>
-          <input type="password" name="password"
-                 value="${password}"/><br/>
-          <input type="submit" name="form.submitted" value="Log In"/>
-        </form>
       </div>
     </div>
-  </div>
-  <div id="footer">
-    <div class="footer"
-         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
 </html>
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt
index d98420680..f8cbe2e2c 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt
@@ -1,75 +1,67 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>The Pyramid Web Application Development Framework</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon" href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
-  <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton|Nobile:regular,i,b,bi&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top">
-      <div class="top align-center">
-        <div><img src="${request.static_url('tutorial:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-center">
-        <p class="app-welcome">
-          Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web application development framework.
-        </p>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div id="left" class="align-right">
-          <h2>Search documentation</h2>
-          <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/dev/search.html">
-                <input type="text" id="q" name="q" value="" />
-                <input type="submit" id="x" value="Go" />
-            </form>
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>ZODB Scaffold for The Pyramid Web Framework</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">ZODB scaffold</span></h1>
+              <p class="lead">Welcome to <span class="font-normal">${project}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7</span>.</p>
+            </div>
+          </div>
         </div>
-        <div id="right" class="align-left">
-          <h2>Pyramid links</h2>
-          <ul class="links">
-            <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#narrative-documentation">Narrative Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#api-documentation">API Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#tutorials">Tutorials</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#change-history">Change History</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#sample-applications">Sample Applications</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#support-and-development">Support and Development</a>
-            </li>
-            <li>
-              <a href="irc://irc.freenode.net#pyramid">IRC Channel</a>
-            </li>
+        <div class="row">
+          <div class="links">
+            <ul>
+              <li class="current-version">Generated by v1.7</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
+              <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
+              <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
+              <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
             </ul>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
         </div>
       </div>
     </div>
-  </div>
-  <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
 </html>
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/view.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/view.pt
index d207a0c23..fa35d758d 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/templates/view.pt
+++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/view.pt
@@ -1,65 +1,72 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
-      xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>${page.__name__} - Pyramid tutorial wiki (based on
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>${page.__name__} - Pyramid tutorial wiki (based on
     TurboGears 20-Minute Wiki)</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon"
-        href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/pylons.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/ie6.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top-small">
-      <div class="top-small align-center">
-        <div>
-          <img width="220" height="50" alt="pyramid"
-        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <p tal:condition="logged_in" class="pull-right">
+                <a href="${request.application_url}/logout">Logout</a>
+              </p>
+              <div tal:replace="structure content">
+                Page text goes here.
+              </div>
+              <p>
+                <a tal:attributes="href edit_url" href="">
+                  Edit this page
+                </a>
+              </p>
+              <p>
+                  Viewing <strong><span tal:replace="page.__name__">
+                  Page Name Goes Here</span></strong>
+              </p>
+              <p>You can return to the
+                <a href="${request.application_url}">FrontPage</a>.
+              </p>
+            </div>
+          </div>
         </div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-right">
-        <div id="left" class="app-welcome align-left">
-          Viewing <b><span tal:replace="page.__name__">Page Name
-            Goes Here</span></b><br/>
-          You can return to the
-          <a href="${request.application_url}">FrontPage</a>.<br/>
-        </div>
-        <div id="right" class="app-welcome align-right">
-          <span tal:condition="logged_in">
-            <a href="${request.application_url}/logout">Logout</a>
-          </span>
-        </div>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div tal:replace="structure content">
-          Page text goes here.
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
         </div>
-        <p>
-          <a tal:attributes="href edit_url" href="">
-            Edit this page
-          </a>
-        </p>
       </div>
     </div>
-  </div>
-  <div id="footer">
-    <div class="footer"
-         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
 </html>
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/tests.py b/docs/tutorials/wiki/src/authorization/tutorial/tests.py
index aaf753816..40f3c47af 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/authorization/tutorial/tests.py
@@ -2,123 +2,16 @@ import unittest
 
 from pyramid import testing
 
-class PageModelTests(unittest.TestCase):
 
-    def _getTargetClass(self):
-        from tutorial.models import Page
-        return Page
+class ViewTests(unittest.TestCase):
+    def setUp(self):
+        self.config = testing.setUp()
 
-    def _makeOne(self, data=u'some data'):
-        return self._getTargetClass()(data=data)
+    def tearDown(self):
+        testing.tearDown()
 
-    def test_constructor(self):
-        instance = self._makeOne()
-        self.assertEqual(instance.data, u'some data')
-        
-class WikiModelTests(unittest.TestCase):
-
-    def _getTargetClass(self):
-        from tutorial.models import Wiki
-        return Wiki
-
-    def _makeOne(self):
-        return self._getTargetClass()()
-
-    def test_it(self):
-        wiki = self._makeOne()
-        self.assertEqual(wiki.__parent__, None)
-        self.assertEqual(wiki.__name__, None)
-
-class AppmakerTests(unittest.TestCase):
-    def _callFUT(self, zodb_root):
-        from tutorial.models import appmaker
-        return appmaker(zodb_root)
-
-    def test_it(self):
-        root = {}
-        self._callFUT(root)
-        self.assertEqual(root['app_root']['FrontPage'].data,
-                         'This is the front page')
-
-class ViewWikiTests(unittest.TestCase):
-    def test_it(self):
-        from tutorial.views import view_wiki
-        context = testing.DummyResource()
-        request = testing.DummyRequest()
-        response = view_wiki(context, request)
-        self.assertEqual(response.location, 'http://example.com/FrontPage')
-
-class ViewPageTests(unittest.TestCase):
-    def _callFUT(self, context, request):
-        from tutorial.views import view_page
-        return view_page(context, request)
-
-    def test_it(self):
-        wiki = testing.DummyResource()
-        wiki['IDoExist'] = testing.DummyResource()
-        context = testing.DummyResource(data='Hello CruelWorld IDoExist')
-        context.__parent__ = wiki
-        context.__name__ = 'thepage'
-        request = testing.DummyRequest()
-        info = self._callFUT(context, request)
-        self.assertEqual(info['page'], context)
-        self.assertEqual(
-            info['content'], 
-            '<div class="document">\n'
-            '<p>Hello <a href="http://example.com/add_page/CruelWorld">'
-            'CruelWorld</a> '
-            '<a href="http://example.com/IDoExist/">'
-            'IDoExist</a>'
-            '</p>\n</div>\n')
-        self.assertEqual(info['edit_url'],
-                         'http://example.com/thepage/edit_page')
-        
-    
-class AddPageTests(unittest.TestCase):
-    def _callFUT(self, context, request):
-        from tutorial.views import add_page
-        return add_page(context, request)
-
-    def test_it_notsubmitted(self):
-        from pyramid.url import resource_url
-        context = testing.DummyResource()
-        request = testing.DummyRequest()
-        request.subpath = ['AnotherPage']
-        info = self._callFUT(context, request)
-        self.assertEqual(info['page'].data,'')
-        self.assertEqual(info['save_url'],
-                         resource_url(
-                             context, request, 'add_page', 'AnotherPage'))
-        
-    def test_it_submitted(self):
-        context = testing.DummyResource()
-        request = testing.DummyRequest({'form.submitted':True,
-                                        'body':'Hello yo!'})
-        request.subpath = ['AnotherPage']
-        self._callFUT(context, request)
-        page = context['AnotherPage']
-        self.assertEqual(page.data, 'Hello yo!')
-        self.assertEqual(page.__name__, 'AnotherPage')
-        self.assertEqual(page.__parent__, context)
-
-class EditPageTests(unittest.TestCase):
-    def _callFUT(self, context, request):
-        from tutorial.views import edit_page
-        return edit_page(context, request)
-
-    def test_it_notsubmitted(self):
-        from pyramid.url import resource_url
-        context = testing.DummyResource()
+    def test_my_view(self):
+        from .views import my_view
         request = testing.DummyRequest()
-        info = self._callFUT(context, request)
-        self.assertEqual(info['page'], context)
-        self.assertEqual(info['save_url'],
-                         resource_url(context, request, 'edit_page'))
-        
-    def test_it_submitted(self):
-        context = testing.DummyResource()
-        request = testing.DummyRequest({'form.submitted':True,
-                                        'body':'Hello yo!'})
-        response = self._callFUT(context, request)
-        self.assertEqual(response.location, 'http://example.com/')
-        self.assertEqual(context.data, 'Hello yo!')
+        info = my_view(request)
+        self.assertEqual(info['project'], 'tutorial')
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/views.py b/docs/tutorials/wiki/src/authorization/tutorial/views.py
index a83e17de4..c271d2cc1 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/views.py
+++ b/docs/tutorials/wiki/src/authorization/tutorial/views.py
@@ -2,21 +2,31 @@ from docutils.core import publish_parts
 import re
 
 from pyramid.httpexceptions import HTTPFound
-from pyramid.url import resource_url
-from pyramid.view import view_config
-from pyramid.security import authenticated_userid
 
-from tutorial.models import Page
+from pyramid.view import (
+    view_config,
+    forbidden_view_config,
+    )
+
+from pyramid.security import (
+    remember,
+    forget,
+    )
+
+
+from .security import USERS
+from .models import Page
 
 # regular expression used to find WikiWords
 wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")
 
-@view_config(context='tutorial.models.Wiki', permission='view')
+@view_config(context='.models.Wiki',
+             permission='view')
 def view_wiki(context, request):
-    return HTTPFound(location=resource_url(context, request, 'FrontPage'))
+    return HTTPFound(location=request.resource_url(context, 'FrontPage'))
 
-@view_config(context='tutorial.models.Page',
-             renderer='templates/view.pt', permission='view')
+@view_config(context='.models.Page', renderer='templates/view.pt',
+             permission='view')
 def view_page(context, request):
     wiki = context.__parent__
 
@@ -24,53 +34,83 @@ def view_page(context, request):
         word = match.group(1)
         if word in wiki:
             page = wiki[word]
-            view_url = resource_url(page, request)
+            view_url = request.resource_url(page)
             return '<a href="%s">%s</a>' % (view_url, word)
         else:
-            add_url = request.application_url + '/add_page/' + word 
+            add_url = request.application_url + '/add_page/' + word
             return '<a href="%s">%s</a>' % (add_url, word)
 
     content = publish_parts(context.data, writer_name='html')['html_body']
     content = wikiwords.sub(check, content)
-    edit_url = resource_url(context, request, 'edit_page')
+    edit_url = request.resource_url(context, 'edit_page')
 
-    logged_in = authenticated_userid(request)
+    return dict(page=context, content=content, edit_url=edit_url,
+                logged_in=request.authenticated_userid)
 
-    return dict(page = context, content = content, edit_url = edit_url,
-                logged_in = logged_in)
-
-@view_config(name='add_page', context='tutorial.models.Wiki',
+@view_config(name='add_page', context='.models.Wiki',
              renderer='templates/edit.pt',
              permission='edit')
 def add_page(context, request):
-    name = request.subpath[0]
+    pagename = request.subpath[0]
     if 'form.submitted' in request.params:
         body = request.params['body']
         page = Page(body)
-        page.__name__ = name
+        page.__name__ = pagename
         page.__parent__ = context
-        context[name] = page
-        return HTTPFound(location = resource_url(page, request))
-    save_url = resource_url(context, request, 'add_page', name)
+        context[pagename] = page
+        return HTTPFound(location=request.resource_url(page))
+    save_url = request.resource_url(context, 'add_page', pagename)
     page = Page('')
-    page.__name__ = name
+    page.__name__ = pagename
     page.__parent__ = context
 
-    logged_in = authenticated_userid(request)
-
-    return dict(page = page, save_url = save_url, logged_in = logged_in)
+    return dict(page=page, save_url=save_url,
+                logged_in=request.authenticated_userid)
 
-@view_config(name='edit_page', context='tutorial.models.Page',
+@view_config(name='edit_page', context='.models.Page',
              renderer='templates/edit.pt',
              permission='edit')
 def edit_page(context, request):
     if 'form.submitted' in request.params:
         context.data = request.params['body']
-        return HTTPFound(location = resource_url(context, request))
+        return HTTPFound(location=request.resource_url(context))
+
+    return dict(page=context,
+                save_url=request.resource_url(context, 'edit_page'),
+                logged_in=request.authenticated_userid)
+
+@view_config(context='.models.Wiki', name='login',
+             renderer='templates/login.pt')
+@forbidden_view_config(renderer='templates/login.pt')
+def login(request):
+    login_url = request.resource_url(request.context, 'login')
+    referrer = request.url
+    if referrer == login_url:
+        referrer = '/'  # never use the login form itself as came_from
+    came_from = request.params.get('came_from', referrer)
+    message = ''
+    login = ''
+    password = ''
+    if 'form.submitted' in request.params:
+        login = request.params['login']
+        password = request.params['password']
+        if USERS.get(login) == password:
+            headers = remember(request, login)
+            return HTTPFound(location=came_from,
+                             headers=headers)
+        message = 'Failed login'
+
+    return dict(
+        message=message,
+        url=request.application_url + '/login',
+        came_from=came_from,
+        login=login,
+        password=password,
+    )
 
-    logged_in = authenticated_userid(request)
 
-    return dict(page = context,
-                save_url = resource_url(context, request, 'edit_page'),
-                logged_in = logged_in)
-    
+@view_config(context='.models.Wiki', name='logout')
+def logout(request):
+    headers = forget(request)
+    return HTTPFound(location=request.resource_url(request.context),
+                     headers=headers)
diff --git a/docs/tutorials/wiki/src/basiclayout/README.txt b/docs/tutorials/wiki/src/basiclayout/README.txt
index d41f7f90f..dcb3605b8 100644
--- a/docs/tutorials/wiki/src/basiclayout/README.txt
+++ b/docs/tutorials/wiki/src/basiclayout/README.txt
@@ -1,4 +1,12 @@
 tutorial README
+==================
 
+Getting Started
+---------------
 
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki/src/basiclayout/development.ini b/docs/tutorials/wiki/src/basiclayout/development.ini
index 555010bed..6bf4b198e 100644
--- a/docs/tutorials/wiki/src/basiclayout/development.ini
+++ b/docs/tutorials/wiki/src/basiclayout/development.ini
@@ -1,34 +1,44 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = true
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = true
-default_locale_name = en
-zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
-
-[pipeline:main]
-pipeline =
-    egg:WebError#evalerror
-    egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
-    tutorial
-
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_zodbconn
+    pyramid_tm
+
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
-host = 0.0.0.0
+use = egg:waitress#main
+host = 127.0.0.1
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
-keys = root
+keys = root, tutorial
 
 [handlers]
 keys = console
@@ -40,6 +50,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
@@ -47,6 +62,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/basiclayout/production.ini b/docs/tutorials/wiki/src/basiclayout/production.ini
index 5c47ade9b..4e9892e7b 100644
--- a/docs/tutorials/wiki/src/basiclayout/production.ini
+++ b/docs/tutorials/wiki/src/basiclayout/production.ini
@@ -1,45 +1,36 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = false
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = false
-default_locale_name = en
-zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
-[filter:weberror]
-use = egg:WebError#error_catcher
-debug = false
-;error_log = 
-;show_exceptions_in_wsgi_errors = true
-;smtp_server = localhost
-;error_email = janitor@example.com
-;smtp_username = janitor
-;smtp_password = "janitor's password"
-;from_address = paste@localhost
-;error_subject_prefix = "Pyramid Error"
-;smtp_use_tls =
-;error_message =
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_tm
+    pyramid_zodbconn
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
-[pipeline:main]
-pipeline =
-    weberror
-    egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
-    tutorial
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
+use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial
@@ -66,6 +57,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/basiclayout/setup.cfg b/docs/tutorials/wiki/src/basiclayout/setup.cfg
deleted file mode 100644
index 23b2ad983..000000000
--- a/docs/tutorials/wiki/src/basiclayout/setup.cfg
+++ /dev/null
@@ -1,27 +0,0 @@
-[nosetests]
-match=^test
-nocapture=1
-cover-package=tutorial
-with-coverage=1
-cover-erase=1
-
-[compile_catalog]
-directory = tutorial/locale
-domain = tutorial
-statistics = true
-
-[extract_messages]
-add_comments = TRANSLATORS:
-output_file = tutorial/locale/tutorial.pot
-width = 80
-
-[init_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-
-[update_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-previous = true
diff --git a/docs/tutorials/wiki/src/basiclayout/setup.py b/docs/tutorials/wiki/src/basiclayout/setup.py
index 2d540d65b..46b395568 100644
--- a/docs/tutorials/wiki/src/basiclayout/setup.py
+++ b/docs/tutorials/wiki/src/basiclayout/setup.py
@@ -3,28 +3,38 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
-    'repoze.zodbconn',
-    'repoze.tm2>=1.0b1', # default_commit_veto
-    'repoze.retry',
+    'pyramid_chameleon',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
+    'pyramid_zodbconn',
+    'transaction',
     'ZODB3',
-    'WebError',
+    'waitress',
+    ]
+
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
     ]
 
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Programming Language :: Python",
-        "Framework :: Pylons",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
       author='',
       author_email='',
       url='',
@@ -32,13 +42,12 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      install_requires = requires,
-      tests_require= requires,
-      test_suite="tutorial",
-      entry_points = """\
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-      paster_plugins=['pyramid'],
       )
-
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py
index 6a4093a3b..f2a86df47 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py
@@ -1,18 +1,18 @@
 from pyramid.config import Configurator
-from repoze.zodbconn.finder import PersistentApplicationFinder
-from tutorial.models import appmaker
+from pyramid_zodbconn import get_connection
+from .models import appmaker
+
+
+def root_factory(request):
+    conn = get_connection(request)
+    return appmaker(conn.root())
+
 
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
-    zodb_uri = settings.get('zodb_uri', False)
-    if zodb_uri is False:
-        raise ValueError("No 'zodb_uri' in application configuration.")
-
-    finder = PersistentApplicationFinder(zodb_uri, appmaker)
-    def get_root(request):
-        return finder(request.environ)
-    config = Configurator(root_factory=get_root, settings=settings)
-    config.add_static_view('static', 'tutorial:static')
-    config.scan('tutorial')
+    config = Configurator(root_factory=root_factory, settings=settings)
+    config.include('pyramid_chameleon')
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.scan()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/models.py b/docs/tutorials/wiki/src/basiclayout/tutorial/models.py
index 8dd0f5a49..e5aa3e9f7 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/models.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/models.py
@@ -1,10 +1,12 @@
 from persistent.mapping import PersistentMapping
 
+
 class MyModel(PersistentMapping):
     __parent__ = __name__ = None
 
+
 def appmaker(zodb_root):
-    if not 'app_root' in zodb_root:
+    if 'app_root' not in zodb_root:
         app_root = MyModel()
         zodb_root['app_root'] = app_root
         import transaction
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/favicon.ico b/docs/tutorials/wiki/src/basiclayout/tutorial/static/favicon.ico
deleted file mode 100644
index 71f837c9e..000000000
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/static/favicon.ico
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/footerbg.png b/docs/tutorials/wiki/src/basiclayout/tutorial/static/footerbg.png
deleted file mode 100644
index 1fbc873da..000000000
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/static/footerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/headerbg.png b/docs/tutorials/wiki/src/basiclayout/tutorial/static/headerbg.png
deleted file mode 100644
index 0596f2020..000000000
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/static/headerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/ie6.css b/docs/tutorials/wiki/src/basiclayout/tutorial/static/ie6.css
deleted file mode 100644
index b7c8493d8..000000000
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/static/ie6.css
+++ /dev/null
@@ -1,8 +0,0 @@
-* html img,
-* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
-this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
-this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
-);}
-#wrap{display:table;height:100%}
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/middlebg.png b/docs/tutorials/wiki/src/basiclayout/tutorial/static/middlebg.png
deleted file mode 100644
index 2369cfb7d..000000000
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/static/middlebg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/pylons.css b/docs/tutorials/wiki/src/basiclayout/tutorial/static/pylons.css
deleted file mode 100644
index fd1914d8d..000000000
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/static/pylons.css
+++ /dev/null
@@ -1,65 +0,0 @@
-html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */
-vertical-align:baseline;background:transparent;}
-body{line-height:1;}
-ol,ul{list-style:none;}
-blockquote,q{quotes:none;}
-blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;}
-:focus{outline:0;}
-ins{text-decoration:none;}
-del{text-decoration:line-through;}
-table{border-collapse:collapse;border-spacing:0;}
-sub{vertical-align:sub;font-size:smaller;line-height:normal;}
-sup{vertical-align:super;font-size:smaller;line-height:normal;}
-ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;}
-ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;}
-li{display:list-item;}
-ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;}
-ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;}
-ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;}
-.hidden{display:none;}
-p{line-height:1.5em;}
-h1{font-size:1.75em;line-height:1.7em;font-family:helvetica,verdana;}
-h2{font-size:1.5em;line-height:1.7em;font-family:helvetica,verdana;}
-h3{font-size:1.25em;line-height:1.7em;font-family:helvetica,verdana;}
-h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;}
-html,body{width:100%;height:100%;}
-body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;}
-a{color:#1b61d6;text-decoration:none;}
-a:hover{color:#e88f00;text-decoration:underline;}
-body h1,
-body h2,
-body h3,
-body h4,
-body h5,
-body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;}
-#wrap{min-height:100%;}
-#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;}
-#header{background:#000000;top:0;font-size:14px;}
-#footer{bottom:0;background:#000000 url(footerbg.png) repeat-x 0 top;position:relative;margin-top:-40px;clear:both;}
-.header,.footer{width:750px;margin-right:auto;margin-left:auto;}
-.wrapper{width:100%}
-#top,#top-small,#bottom{width:100%;}
-#top{color:#000000;height:230px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#top-small{color:#000000;height:60px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#bottom{color:#222;background-color:#ffffff;}
-.top,.top-small,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;}
-.top{padding-top:40px;}
-.top-small{padding-top:10px;}
-#middle{width:100%;height:100px;background:url(middlebg.png) repeat-x;border-top:2px solid #ffffff;border-bottom:2px solid #b2b2b2;}
-.app-welcome{margin-top:25px;}
-.app-name{color:#000000;font-weight:bold;}
-.bottom{padding-top:50px;}
-#left{width:350px;float:left;padding-right:25px;}
-#right{width:350px;float:right;padding-left:25px;}
-.align-left{text-align:left;}
-.align-right{text-align:right;}
-.align-center{text-align:center;}
-ul.links{margin:0;padding:0;}
-ul.links li{list-style-type:none;font-size:14px;}
-form{border-style:none;}
-fieldset{border-style:none;}
-input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;}
-input[type=text],input[type=password]{width:205px;}
-input[type=submit]{background-color:#ddd;font-weight:bold;}
-/*Opera Fix*/
-body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;}
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki/src/basiclayout/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/pyramid-small.png b/docs/tutorials/wiki/src/basiclayout/tutorial/static/pyramid-small.png
deleted file mode 100644
index a5bc0ade7..000000000
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/static/pyramid-small.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/pyramid.png b/docs/tutorials/wiki/src/basiclayout/tutorial/static/pyramid.png
index 347e05549..4ab837be9 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/static/pyramid.png
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/theme.css b/docs/tutorials/wiki/src/basiclayout/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/static/transparent.gif b/docs/tutorials/wiki/src/basiclayout/tutorial/static/transparent.gif
deleted file mode 100644
index 0341802e5..000000000
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/static/transparent.gif
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt
index c24daa711..f8cbe2e2c 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt
@@ -1,75 +1,67 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>The Pyramid Web Application Development Framework</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon" href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
-  <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton|Nobile:regular,i,b,bi&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top">
-      <div class="top align-center">
-        <div><img src="${request.static_url('tutorial:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-center">
-        <p class="app-welcome">
-          Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web application development framework.
-        </p>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div id="left" class="align-right">
-          <h2>Search documentation</h2>
-          <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/dev/search.html">
-                <input type="text" id="q" name="q" value="" />
-                <input type="submit" id="x" value="Go" />
-            </form>
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>ZODB Scaffold for The Pyramid Web Framework</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">ZODB scaffold</span></h1>
+              <p class="lead">Welcome to <span class="font-normal">${project}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7</span>.</p>
+            </div>
+          </div>
         </div>
-        <div id="right" class="align-left">
-          <h2>Pyramid links</h2>
-          <ul class="links">
-            <li>
-              <a href="http://pylonsproject.org/">Pylons Website</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#narrative-documentation">Narrative Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#api-documentation">API Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#tutorials">Tutorials</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#change-history">Change History</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#sample-applications">Sample Applications</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#support-and-development">Support and Development</a>
-            </li>
-            <li>
-              <a href="irc://irc.freenode.net#pyramid">IRC Channel</a>
-            </li>
+        <div class="row">
+          <div class="links">
+            <ul>
+              <li class="current-version">Generated by v1.7</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
+              <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
+              <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
+              <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
             </ul>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
         </div>
       </div>
     </div>
-  </div>
-  <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
 </html>
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py b/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py
index 1f3c3bb4d..40f3c47af 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py
@@ -2,6 +2,7 @@ import unittest
 
 from pyramid import testing
 
+
 class ViewTests(unittest.TestCase):
     def setUp(self):
         self.config = testing.setUp()
@@ -10,8 +11,7 @@ class ViewTests(unittest.TestCase):
         testing.tearDown()
 
     def test_my_view(self):
-        from tutorial.views import my_view
+        from .views import my_view
         request = testing.DummyRequest()
         info = my_view(request)
         self.assertEqual(info['project'], 'tutorial')
-
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/views.py b/docs/tutorials/wiki/src/basiclayout/tutorial/views.py
index 157b9ac8f..628ce15ed 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/views.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/views.py
@@ -1,7 +1,7 @@
 from pyramid.view import view_config
-from tutorial.models import MyModel
+from .models import MyModel
 
-@view_config(context=MyModel,
-             renderer='tutorial:templates/mytemplate.pt')
+
+@view_config(context=MyModel, renderer='templates/mytemplate.pt')
 def my_view(request):
-    return {'project':'tutorial'}
+    return {'project': 'tutorial'}
diff --git a/docs/tutorials/wiki/src/installation/CHANGES.txt b/docs/tutorials/wiki/src/installation/CHANGES.txt
new file mode 100644
index 000000000..35a34f332
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/CHANGES.txt
@@ -0,0 +1,4 @@
+0.0
+---
+
+-  Initial version
diff --git a/docs/tutorials/wiki/src/installation/MANIFEST.in b/docs/tutorials/wiki/src/installation/MANIFEST.in
new file mode 100644
index 000000000..81beba1b1
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/MANIFEST.in
@@ -0,0 +1,2 @@
+include *.txt *.ini *.cfg *.rst
+recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/tutorials/wiki/src/installation/README.txt b/docs/tutorials/wiki/src/installation/README.txt
new file mode 100644
index 000000000..dcb3605b8
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/README.txt
@@ -0,0 +1,12 @@
+tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki/src/installation/development.ini b/docs/tutorials/wiki/src/installation/development.ini
new file mode 100644
index 000000000..6bf4b198e
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/development.ini
@@ -0,0 +1,65 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_zodbconn
+    pyramid_tm
+
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
+[server:main]
+use = egg:waitress#main
+host = 127.0.0.1
+port = 6543
+
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/installation/production.ini b/docs/tutorials/wiki/src/installation/production.ini
new file mode 100644
index 000000000..4e9892e7b
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/production.ini
@@ -0,0 +1,60 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_tm
+    pyramid_zodbconn
+
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
+
+###
+# wsgi server configuration
+###
+
+[server:main]
+use = egg:waitress#main
+host = 0.0.0.0
+port = 6543
+
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_tutorial]
+level = WARN
+handlers =
+qualname = tutorial
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/installation/setup.py b/docs/tutorials/wiki/src/installation/setup.py
new file mode 100644
index 000000000..46b395568
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/setup.py
@@ -0,0 +1,53 @@
+import os
+
+from setuptools import setup, find_packages
+
+here = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
+
+requires = [
+    'pyramid',
+    'pyramid_chameleon',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
+    'pyramid_zodbconn',
+    'transaction',
+    'ZODB3',
+    'waitress',
+    ]
+
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
+
+setup(name='tutorial',
+      version='0.0',
+      description='tutorial',
+      long_description=README + '\n\n' + CHANGES,
+      classifiers=[
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
+      author='',
+      author_email='',
+      url='',
+      keywords='web pylons pyramid',
+      packages=find_packages(),
+      include_package_data=True,
+      zip_safe=False,
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
+      [paste.app_factory]
+      main = tutorial:main
+      """,
+      )
diff --git a/docs/tutorials/wiki/src/installation/tutorial/__init__.py b/docs/tutorials/wiki/src/installation/tutorial/__init__.py
new file mode 100644
index 000000000..f2a86df47
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/tutorial/__init__.py
@@ -0,0 +1,18 @@
+from pyramid.config import Configurator
+from pyramid_zodbconn import get_connection
+from .models import appmaker
+
+
+def root_factory(request):
+    conn = get_connection(request)
+    return appmaker(conn.root())
+
+
+def main(global_config, **settings):
+    """ This function returns a Pyramid WSGI application.
+    """
+    config = Configurator(root_factory=root_factory, settings=settings)
+    config.include('pyramid_chameleon')
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.scan()
+    return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki/src/installation/tutorial/models.py b/docs/tutorials/wiki/src/installation/tutorial/models.py
new file mode 100644
index 000000000..e5aa3e9f7
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/tutorial/models.py
@@ -0,0 +1,14 @@
+from persistent.mapping import PersistentMapping
+
+
+class MyModel(PersistentMapping):
+    __parent__ = __name__ = None
+
+
+def appmaker(zodb_root):
+    if 'app_root' not in zodb_root:
+        app_root = MyModel()
+        zodb_root['app_root'] = app_root
+        import transaction
+        transaction.commit()
+    return zodb_root['app_root']
diff --git a/docs/tutorials/wiki/src/installation/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki/src/installation/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki/src/installation/tutorial/static/pyramid.png b/docs/tutorials/wiki/src/installation/tutorial/static/pyramid.png
new file mode 100644
index 000000000..4ab837be9
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki/src/installation/tutorial/static/theme.css b/docs/tutorials/wiki/src/installation/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki/src/installation/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/installation/tutorial/templates/mytemplate.pt
new file mode 100644
index 000000000..f8cbe2e2c
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/tutorial/templates/mytemplate.pt
@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>ZODB Scaffold for The Pyramid Web Framework</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">ZODB scaffold</span></h1>
+              <p class="lead">Welcome to <span class="font-normal">${project}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7</span>.</p>
+            </div>
+          </div>
+        </div>
+        <div class="row">
+          <div class="links">
+            <ul>
+              <li class="current-version">Generated by v1.7</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
+              <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
+              <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
+              <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
+            </ul>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki/src/installation/tutorial/tests.py b/docs/tutorials/wiki/src/installation/tutorial/tests.py
new file mode 100644
index 000000000..40f3c47af
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/tutorial/tests.py
@@ -0,0 +1,17 @@
+import unittest
+
+from pyramid import testing
+
+
+class ViewTests(unittest.TestCase):
+    def setUp(self):
+        self.config = testing.setUp()
+
+    def tearDown(self):
+        testing.tearDown()
+
+    def test_my_view(self):
+        from .views import my_view
+        request = testing.DummyRequest()
+        info = my_view(request)
+        self.assertEqual(info['project'], 'tutorial')
diff --git a/docs/tutorials/wiki/src/installation/tutorial/views.py b/docs/tutorials/wiki/src/installation/tutorial/views.py
new file mode 100644
index 000000000..628ce15ed
--- /dev/null
+++ b/docs/tutorials/wiki/src/installation/tutorial/views.py
@@ -0,0 +1,7 @@
+from pyramid.view import view_config
+from .models import MyModel
+
+
+@view_config(context=MyModel, renderer='templates/mytemplate.pt')
+def my_view(request):
+    return {'project': 'tutorial'}
diff --git a/docs/tutorials/wiki/src/models/CHANGES.txt b/docs/tutorials/wiki/src/models/CHANGES.txt
index ffa255da8..35a34f332 100644
--- a/docs/tutorials/wiki/src/models/CHANGES.txt
+++ b/docs/tutorials/wiki/src/models/CHANGES.txt
@@ -1,4 +1,4 @@
 0.0
 ---
 
-- Initial version
+-  Initial version
diff --git a/docs/tutorials/wiki/src/models/README.txt b/docs/tutorials/wiki/src/models/README.txt
index d41f7f90f..dcb3605b8 100644
--- a/docs/tutorials/wiki/src/models/README.txt
+++ b/docs/tutorials/wiki/src/models/README.txt
@@ -1,4 +1,12 @@
 tutorial README
+==================
 
+Getting Started
+---------------
 
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki/src/models/development.ini b/docs/tutorials/wiki/src/models/development.ini
index 1ba746d0e..6bf4b198e 100644
--- a/docs/tutorials/wiki/src/models/development.ini
+++ b/docs/tutorials/wiki/src/models/development.ini
@@ -1,34 +1,44 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = true
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = true
-default_locale_name = en
-zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
-
-[pipeline:main]
-pipeline =
-    egg:WebError#evalerror
-    egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
-    tutorial
-
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_zodbconn
+    pyramid_tm
+
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
-host = 0.0.0.0
+use = egg:waitress#main
+host = 127.0.0.1
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
-keys = root
+keys = root, tutorial
 
 [handlers]
 keys = console
@@ -40,6 +50,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
@@ -47,6 +62,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/models/production.ini b/docs/tutorials/wiki/src/models/production.ini
index 5c47ade9b..4e9892e7b 100644
--- a/docs/tutorials/wiki/src/models/production.ini
+++ b/docs/tutorials/wiki/src/models/production.ini
@@ -1,45 +1,36 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = false
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = false
-default_locale_name = en
-zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
-[filter:weberror]
-use = egg:WebError#error_catcher
-debug = false
-;error_log = 
-;show_exceptions_in_wsgi_errors = true
-;smtp_server = localhost
-;error_email = janitor@example.com
-;smtp_username = janitor
-;smtp_password = "janitor's password"
-;from_address = paste@localhost
-;error_subject_prefix = "Pyramid Error"
-;smtp_use_tls =
-;error_message =
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_tm
+    pyramid_zodbconn
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
-[pipeline:main]
-pipeline =
-    weberror
-    egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
-    tutorial
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
+use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial
@@ -66,6 +57,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/models/setup.cfg b/docs/tutorials/wiki/src/models/setup.cfg
deleted file mode 100644
index 3d7ea6e23..000000000
--- a/docs/tutorials/wiki/src/models/setup.cfg
+++ /dev/null
@@ -1,28 +0,0 @@
-[nosetests]
-match=^test
-nocapture=1
-cover-package=tutorial
-with-coverage=1
-cover-erase=1
-
-[compile_catalog]
-directory = tutorial/locale
-domain = tutorial
-statistics = true
-
-[extract_messages]
-add_comments = TRANSLATORS:
-output_file = tutorial/locale/tutorial.pot
-width = 80
-
-[init_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-
-[update_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-previous = true
-
diff --git a/docs/tutorials/wiki/src/models/setup.py b/docs/tutorials/wiki/src/models/setup.py
index 2d540d65b..46b395568 100644
--- a/docs/tutorials/wiki/src/models/setup.py
+++ b/docs/tutorials/wiki/src/models/setup.py
@@ -3,28 +3,38 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
-    'repoze.zodbconn',
-    'repoze.tm2>=1.0b1', # default_commit_veto
-    'repoze.retry',
+    'pyramid_chameleon',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
+    'pyramid_zodbconn',
+    'transaction',
     'ZODB3',
-    'WebError',
+    'waitress',
+    ]
+
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
     ]
 
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Programming Language :: Python",
-        "Framework :: Pylons",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
       author='',
       author_email='',
       url='',
@@ -32,13 +42,12 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      install_requires = requires,
-      tests_require= requires,
-      test_suite="tutorial",
-      entry_points = """\
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-      paster_plugins=['pyramid'],
       )
-
diff --git a/docs/tutorials/wiki/src/models/tutorial/__init__.py b/docs/tutorials/wiki/src/models/tutorial/__init__.py
index 73fc81d23..f2a86df47 100644
--- a/docs/tutorials/wiki/src/models/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/models/tutorial/__init__.py
@@ -1,19 +1,18 @@
 from pyramid.config import Configurator
-from repoze.zodbconn.finder import PersistentApplicationFinder
-from tutorial.models import appmaker
+from pyramid_zodbconn import get_connection
+from .models import appmaker
+
+
+def root_factory(request):
+    conn = get_connection(request)
+    return appmaker(conn.root())
+
 
 def main(global_config, **settings):
-    """ This function returns a WSGI application.
+    """ This function returns a Pyramid WSGI application.
     """
-    zodb_uri = settings.get('zodb_uri', False)
-    if zodb_uri is False:
-        raise ValueError("No 'zodb_uri' in application configuration.")
-
-    finder = PersistentApplicationFinder(zodb_uri, appmaker)
-    def get_root(request):
-        return finder(request.environ)
-    config = Configurator(root_factory=get_root, settings=settings)
-    config.add_static_view('static', 'tutorial:static')
-    config.scan('tutorial')
+    config = Configurator(root_factory=root_factory, settings=settings)
+    config.include('pyramid_chameleon')
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki/src/models/tutorial/models.py b/docs/tutorials/wiki/src/models/tutorial/models.py
index 9761856c6..aa907aee5 100644
--- a/docs/tutorials/wiki/src/models/tutorial/models.py
+++ b/docs/tutorials/wiki/src/models/tutorial/models.py
@@ -10,7 +10,7 @@ class Page(Persistent):
         self.data = data
 
 def appmaker(zodb_root):
-    if not 'app_root' in zodb_root:
+    if 'app_root' not in zodb_root:
         app_root = Wiki()
         frontpage = Page('This is the front page')
         app_root['FrontPage'] = frontpage
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/favicon.ico b/docs/tutorials/wiki/src/models/tutorial/static/favicon.ico
deleted file mode 100644
index 71f837c9e..000000000
--- a/docs/tutorials/wiki/src/models/tutorial/static/favicon.ico
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/footerbg.png b/docs/tutorials/wiki/src/models/tutorial/static/footerbg.png
deleted file mode 100644
index 1fbc873da..000000000
--- a/docs/tutorials/wiki/src/models/tutorial/static/footerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/headerbg.png b/docs/tutorials/wiki/src/models/tutorial/static/headerbg.png
deleted file mode 100644
index 0596f2020..000000000
--- a/docs/tutorials/wiki/src/models/tutorial/static/headerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/ie6.css b/docs/tutorials/wiki/src/models/tutorial/static/ie6.css
deleted file mode 100644
index b7c8493d8..000000000
--- a/docs/tutorials/wiki/src/models/tutorial/static/ie6.css
+++ /dev/null
@@ -1,8 +0,0 @@
-* html img,
-* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
-this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
-this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
-);}
-#wrap{display:table;height:100%}
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/middlebg.png b/docs/tutorials/wiki/src/models/tutorial/static/middlebg.png
deleted file mode 100644
index 2369cfb7d..000000000
--- a/docs/tutorials/wiki/src/models/tutorial/static/middlebg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/pylons.css b/docs/tutorials/wiki/src/models/tutorial/static/pylons.css
deleted file mode 100644
index a9f49cc85..000000000
--- a/docs/tutorials/wiki/src/models/tutorial/static/pylons.css
+++ /dev/null
@@ -1,65 +0,0 @@
-html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */
-vertical-align:baseline;background:transparent;}
-body{line-height:1;}
-ol,ul{list-style:none;}
-blockquote,q{quotes:none;}
-blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;}
-:focus{outline:0;}
-ins{text-decoration:none;}
-del{text-decoration:line-through;}
-table{border-collapse:collapse;border-spacing:0;}
-sub{vertical-align:sub;font-size:smaller;line-height:normal;}
-sup{vertical-align:super;font-size:smaller;line-height:normal;}
-ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;}
-ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;}
-li{display:list-item;}
-ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;}
-ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;}
-ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;}
-.hidden{display:none;}
-p{line-height:1.5em;}
-h1{font-size:1.75em;line-height:1.7em;font-family:helvetica,verdana;}
-h2{font-size:1.5em;line-height:1.7em;font-family:helvetica,verdana;}
-h3{font-size:1.25em;line-height:1.7em;font-family:helvetica,verdana;}
-h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;}
-html,body{width:100%;height:100%;}
-body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;}
-a{color:#1b61d6;text-decoration:none;}
-a:hover{color:#e88f00;text-decoration:underline;}
-body h1,
-body h2,
-body h3,
-body h4,
-body h5,
-body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;}
-#wrap{min-height:100%;}
-#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;}
-#header{background:#000000;top:0;font-size:14px;}
-#footer{bottom:0;background:#000000 url(footerbg.png) repeat-x 0 top;position:relative;margin-top:-40px;clear:both;}
-.header,.footer{width:750px;margin-right:auto;margin-left:auto;}
-.wrapper{width:100%}
-#top,#top-small,#bottom{width:100%;}
-#top{color:#000000;height:230px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#top-small{color:#000000;height:60px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#bottom{color:#222;background-color:#ffffff;}
-.top,.top-snall,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;}
-.top{padding-top:40px;}
-.top-small{padding-top:10px;}
-#middle{width:100%;height:100px;background:url(middlebg.png) repeat-x;border-top:2px solid #ffffff;border-bottom:2px solid #b2b2b2;}
-.app-welcome{margin-top:25px;}
-.app-name{color:#000000;font-weight:bold;}
-.bottom{padding-top:50px;}
-#left{width:350px;float:left;padding-right:25px;}
-#right{width:350px;float:right;padding-left:25px;}
-.align-left{text-align:left;}
-.align-right{text-align:right;}
-.align-center{text-align:center;}
-ul.links{margin:0;padding:0;}
-ul.links li{list-style-type:none;font-size:14px;}
-form{border-style:none;}
-fieldset{border-style:none;}
-input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;}
-input[type=text],input[type=password]{width:205px;}
-input[type=submit]{background-color:#ddd;font-weight:bold;}
-/*Opera Fix*/
-body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;}
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki/src/models/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki/src/models/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/pyramid-small.png b/docs/tutorials/wiki/src/models/tutorial/static/pyramid-small.png
deleted file mode 100644
index a5bc0ade7..000000000
--- a/docs/tutorials/wiki/src/models/tutorial/static/pyramid-small.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/pyramid.png b/docs/tutorials/wiki/src/models/tutorial/static/pyramid.png
index 347e05549..4ab837be9 100644
--- a/docs/tutorials/wiki/src/models/tutorial/static/pyramid.png
+++ b/docs/tutorials/wiki/src/models/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/theme.css b/docs/tutorials/wiki/src/models/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki/src/models/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki/src/models/tutorial/static/transparent.gif b/docs/tutorials/wiki/src/models/tutorial/static/transparent.gif
deleted file mode 100644
index 0341802e5..000000000
--- a/docs/tutorials/wiki/src/models/tutorial/static/transparent.gif
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt
index d98420680..f8cbe2e2c 100644
--- a/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt
@@ -1,75 +1,67 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>The Pyramid Web Application Development Framework</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon" href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
-  <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton|Nobile:regular,i,b,bi&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top">
-      <div class="top align-center">
-        <div><img src="${request.static_url('tutorial:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-center">
-        <p class="app-welcome">
-          Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web application development framework.
-        </p>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div id="left" class="align-right">
-          <h2>Search documentation</h2>
-          <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/dev/search.html">
-                <input type="text" id="q" name="q" value="" />
-                <input type="submit" id="x" value="Go" />
-            </form>
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>ZODB Scaffold for The Pyramid Web Framework</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">ZODB scaffold</span></h1>
+              <p class="lead">Welcome to <span class="font-normal">${project}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7</span>.</p>
+            </div>
+          </div>
         </div>
-        <div id="right" class="align-left">
-          <h2>Pyramid links</h2>
-          <ul class="links">
-            <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#narrative-documentation">Narrative Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#api-documentation">API Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#tutorials">Tutorials</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#change-history">Change History</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#sample-applications">Sample Applications</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#support-and-development">Support and Development</a>
-            </li>
-            <li>
-              <a href="irc://irc.freenode.net#pyramid">IRC Channel</a>
-            </li>
+        <div class="row">
+          <div class="links">
+            <ul>
+              <li class="current-version">Generated by v1.7</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
+              <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
+              <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
+              <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
             </ul>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
         </div>
       </div>
     </div>
-  </div>
-  <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
 </html>
diff --git a/docs/tutorials/wiki/src/models/tutorial/tests.py b/docs/tutorials/wiki/src/models/tutorial/tests.py
index 51c97a95d..40f3c47af 100644
--- a/docs/tutorials/wiki/src/models/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/models/tutorial/tests.py
@@ -2,50 +2,6 @@ import unittest
 
 from pyramid import testing
 
-class PageModelTests(unittest.TestCase):
-
-    def _getTargetClass(self):
-        from tutorial.models import Page
-        return Page
-
-    def _makeOne(self, data=u'some data'):
-        return self._getTargetClass()(data=data)
-
-    def test_constructor(self):
-        instance = self._makeOne()
-        self.assertEqual(instance.data, u'some data')
-        
-class WikiModelTests(unittest.TestCase):
-
-    def _getTargetClass(self):
-        from tutorial.models import Wiki
-        return Wiki
-
-    def _makeOne(self):
-        return self._getTargetClass()()
-
-    def test_it(self):
-        wiki = self._makeOne()
-        self.assertEqual(wiki.__parent__, None)
-        self.assertEqual(wiki.__name__, None)
-
-class AppmakerTests(unittest.TestCase):
-
-    def _callFUT(self, zodb_root):
-        from tutorial.models import appmaker
-        return appmaker(zodb_root)
-
-    def test_no_app_root(self):
-        root = {}
-        self._callFUT(root)
-        self.assertEqual(root['app_root']['FrontPage'].data,
-                         'This is the front page')
-
-    def test_w_app_root(self):
-        app_root = object()
-        root = {'app_root': app_root}
-        self._callFUT(root)
-        self.failUnless(root['app_root'] is app_root)
 
 class ViewTests(unittest.TestCase):
     def setUp(self):
@@ -55,7 +11,7 @@ class ViewTests(unittest.TestCase):
         testing.tearDown()
 
     def test_my_view(self):
-        from tutorial.views import my_view
+        from .views import my_view
         request = testing.DummyRequest()
         info = my_view(request)
         self.assertEqual(info['project'], 'tutorial')
diff --git a/docs/tutorials/wiki/src/models/tutorial/views.py b/docs/tutorials/wiki/src/models/tutorial/views.py
index 2346602c9..628ce15ed 100644
--- a/docs/tutorials/wiki/src/models/tutorial/views.py
+++ b/docs/tutorials/wiki/src/models/tutorial/views.py
@@ -1,5 +1,7 @@
 from pyramid.view import view_config
+from .models import MyModel
 
-@view_config(renderer='tutorial:templates/mytemplate.pt')
+
+@view_config(context=MyModel, renderer='templates/mytemplate.pt')
 def my_view(request):
-    return {'project':'tutorial'}
+    return {'project': 'tutorial'}
diff --git a/docs/tutorials/wiki/src/tests/CHANGES.txt b/docs/tutorials/wiki/src/tests/CHANGES.txt
new file mode 100644
index 000000000..35a34f332
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/CHANGES.txt
@@ -0,0 +1,4 @@
+0.0
+---
+
+-  Initial version
diff --git a/docs/tutorials/wiki/src/tests/MANIFEST.in b/docs/tutorials/wiki/src/tests/MANIFEST.in
new file mode 100644
index 000000000..81beba1b1
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/MANIFEST.in
@@ -0,0 +1,2 @@
+include *.txt *.ini *.cfg *.rst
+recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/tutorials/wiki/src/tests/README.txt b/docs/tutorials/wiki/src/tests/README.txt
new file mode 100644
index 000000000..dcb3605b8
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/README.txt
@@ -0,0 +1,12 @@
+tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki/src/tests/development.ini b/docs/tutorials/wiki/src/tests/development.ini
new file mode 100644
index 000000000..6bf4b198e
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/development.ini
@@ -0,0 +1,65 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_zodbconn
+    pyramid_tm
+
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
+[server:main]
+use = egg:waitress#main
+host = 127.0.0.1
+port = 6543
+
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/tests/production.ini b/docs/tutorials/wiki/src/tests/production.ini
new file mode 100644
index 000000000..4e9892e7b
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/production.ini
@@ -0,0 +1,60 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_tm
+    pyramid_zodbconn
+
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
+
+###
+# wsgi server configuration
+###
+
+[server:main]
+use = egg:waitress#main
+host = 0.0.0.0
+port = 6543
+
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_tutorial]
+level = WARN
+handlers =
+qualname = tutorial
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/tests/setup.py b/docs/tutorials/wiki/src/tests/setup.py
new file mode 100644
index 000000000..beeed75c9
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/setup.py
@@ -0,0 +1,54 @@
+import os
+
+from setuptools import setup, find_packages
+
+here = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
+
+requires = [
+    'pyramid',
+    'pyramid_chameleon',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
+    'pyramid_zodbconn',
+    'transaction',
+    'ZODB3',
+    'waitress',
+    'docutils',
+    ]
+
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
+
+setup(name='tutorial',
+      version='0.0',
+      description='tutorial',
+      long_description=README + '\n\n' + CHANGES,
+      classifiers=[
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
+      author='',
+      author_email='',
+      url='',
+      keywords='web pylons pyramid',
+      packages=find_packages(),
+      include_package_data=True,
+      zip_safe=False,
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
+      [paste.app_factory]
+      main = tutorial:main
+      """,
+      )
diff --git a/docs/tutorials/wiki/src/tests/tutorial/__init__.py b/docs/tutorials/wiki/src/tests/tutorial/__init__.py
new file mode 100644
index 000000000..39b94abd1
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/__init__.py
@@ -0,0 +1,27 @@
+from pyramid.config import Configurator
+from pyramid_zodbconn import get_connection
+
+from pyramid.authentication import AuthTktAuthenticationPolicy
+from pyramid.authorization import ACLAuthorizationPolicy
+
+from .models import appmaker
+from .security import groupfinder
+
+def root_factory(request):
+    conn = get_connection(request)
+    return appmaker(conn.root())
+
+
+def main(global_config, **settings):
+    """ This function returns a Pyramid WSGI application.
+    """
+    authn_policy = AuthTktAuthenticationPolicy(
+        'sosecret', callback=groupfinder, hashalg='sha512')
+    authz_policy = ACLAuthorizationPolicy()
+    config = Configurator(root_factory=root_factory, settings=settings)
+    config.set_authentication_policy(authn_policy)
+    config.set_authorization_policy(authz_policy)
+    config.include('pyramid_chameleon')
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.scan()
+    return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki/src/tests/tutorial/models.py b/docs/tutorials/wiki/src/tests/tutorial/models.py
new file mode 100644
index 000000000..38fdd2dfc
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/models.py
@@ -0,0 +1,29 @@
+from persistent import Persistent
+from persistent.mapping import PersistentMapping
+
+from pyramid.security import (
+    Allow,
+    Everyone,
+    )
+
+class Wiki(PersistentMapping):
+    __name__ = None
+    __parent__ = None
+    __acl__ = [ (Allow, Everyone, 'view'),
+                (Allow, 'group:editors', 'edit') ]
+
+class Page(Persistent):
+    def __init__(self, data):
+        self.data = data
+
+def appmaker(zodb_root):
+    if 'app_root' not in zodb_root:
+        app_root = Wiki()
+        frontpage = Page('This is the front page')
+        app_root['FrontPage'] = frontpage
+        frontpage.__name__ = 'FrontPage'
+        frontpage.__parent__ = app_root
+        zodb_root['app_root'] = app_root
+        import transaction
+        transaction.commit()
+    return zodb_root['app_root']
diff --git a/docs/tutorials/wiki/src/tests/tutorial/security.py b/docs/tutorials/wiki/src/tests/tutorial/security.py
new file mode 100644
index 000000000..d88c9c71f
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/security.py
@@ -0,0 +1,7 @@
+USERS = {'editor':'editor',
+          'viewer':'viewer'}
+GROUPS = {'editor':['group:editors']}
+
+def groupfinder(userid, request):
+    if userid in USERS:
+        return GROUPS.get(userid, [])
diff --git a/docs/tutorials/wiki/src/tests/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki/src/tests/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki/src/tests/tutorial/static/pyramid.png b/docs/tutorials/wiki/src/tests/tutorial/static/pyramid.png
new file mode 100644
index 000000000..4ab837be9
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki/src/tests/tutorial/static/theme.css b/docs/tutorials/wiki/src/tests/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki/src/tests/tutorial/templates/edit.pt b/docs/tutorials/wiki/src/tests/tutorial/templates/edit.pt
new file mode 100644
index 000000000..823fa8972
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/templates/edit.pt
@@ -0,0 +1,72 @@
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>${page.__name__} - Pyramid tutorial wiki (based on
+    TurboGears 20-Minute Wiki)</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <p tal:condition="logged_in" class="pull-right">
+                <a href="${request.application_url}/logout">Logout</a>
+              </p>
+              <p>
+                  Editing <strong><span tal:replace="page.__name__">
+                  Page Name Goes Here</span></strong>
+              </p>
+              <p>You can return to the
+                <a href="${request.application_url}">FrontPage</a>.
+              </p>
+              <form action="${save_url}" method="post">
+                <div class="form-group">
+                  <textarea class="form-control" name="body" tal:content="page.data" rows="10" cols="60"></textarea>
+                </div>
+                <div class="form-group">
+                  <button type="submit" name="form.submitted" value="Save" class="btn btn-default">Save</button>
+                </div>
+              </form>
+            </div>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki/src/tests/tutorial/templates/login.pt b/docs/tutorials/wiki/src/tests/tutorial/templates/login.pt
new file mode 100644
index 000000000..4a938e9bb
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/templates/login.pt
@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>Login - Pyramid tutorial wiki (based on
+    TurboGears 20-Minute Wiki)</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <p>
+                <strong>
+                  Login
+                </strong><br>
+                <span tal:replace="message"></span>
+              </p>
+              <form action="${url}" method="post">
+                <input type="hidden" name="came_from" value="${came_from}">
+                <div class="form-group">
+                  <label for="login">Username</label>
+                  <input type="text" name="login" value="${login}">
+                </div>
+                <div class="form-group">
+                  <label for="password">Password</label>
+                  <input type="password" name="password" value="${password}">
+                </div>
+                <div class="form-group">
+                  <button type="submit" name="form.submitted" value="Log In" class="btn btn-default">Log In</button>
+                </div>
+              </form>
+            </div>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt
new file mode 100644
index 000000000..f8cbe2e2c
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt
@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>ZODB Scaffold for The Pyramid Web Framework</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">ZODB scaffold</span></h1>
+              <p class="lead">Welcome to <span class="font-normal">${project}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7</span>.</p>
+            </div>
+          </div>
+        </div>
+        <div class="row">
+          <div class="links">
+            <ul>
+              <li class="current-version">Generated by v1.7</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
+              <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
+              <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
+              <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
+            </ul>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki/src/tests/tutorial/templates/view.pt b/docs/tutorials/wiki/src/tests/tutorial/templates/view.pt
new file mode 100644
index 000000000..fa35d758d
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/templates/view.pt
@@ -0,0 +1,72 @@
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>${page.__name__} - Pyramid tutorial wiki (based on
+    TurboGears 20-Minute Wiki)</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <p tal:condition="logged_in" class="pull-right">
+                <a href="${request.application_url}/logout">Logout</a>
+              </p>
+              <div tal:replace="structure content">
+                Page text goes here.
+              </div>
+              <p>
+                <a tal:attributes="href edit_url" href="">
+                  Edit this page
+                </a>
+              </p>
+              <p>
+                  Viewing <strong><span tal:replace="page.__name__">
+                  Page Name Goes Here</span></strong>
+              </p>
+              <p>You can return to the
+                <a href="${request.application_url}">FrontPage</a>.
+              </p>
+            </div>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki/src/tests/tutorial/tests.py b/docs/tutorials/wiki/src/tests/tutorial/tests.py
index 0ce5ea718..04beaea44 100644
--- a/docs/tutorials/wiki/src/tests/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/tests/tutorial/tests.py
@@ -5,7 +5,7 @@ from pyramid import testing
 class PageModelTests(unittest.TestCase):
 
     def _getTargetClass(self):
-        from tutorial.models import Page
+        from .models import Page
         return Page
 
     def _makeOne(self, data=u'some data'):
@@ -18,7 +18,7 @@ class PageModelTests(unittest.TestCase):
 class WikiModelTests(unittest.TestCase):
 
     def _getTargetClass(self):
-        from tutorial.models import Wiki
+        from .models import Wiki
         return Wiki
 
     def _makeOne(self):
@@ -30,8 +30,9 @@ class WikiModelTests(unittest.TestCase):
         self.assertEqual(wiki.__name__, None)
 
 class AppmakerTests(unittest.TestCase):
+
     def _callFUT(self, zodb_root):
-        from tutorial.models import appmaker
+        from .models import appmaker
         return appmaker(zodb_root)
 
     def test_it(self):
@@ -42,7 +43,7 @@ class AppmakerTests(unittest.TestCase):
 
 class ViewWikiTests(unittest.TestCase):
     def test_it(self):
-        from tutorial.views import view_wiki
+        from .views import view_wiki
         context = testing.DummyResource()
         request = testing.DummyRequest()
         response = view_wiki(context, request)
@@ -50,7 +51,7 @@ class ViewWikiTests(unittest.TestCase):
 
 class ViewPageTests(unittest.TestCase):
     def _callFUT(self, context, request):
-        from tutorial.views import view_page
+        from .views import view_page
         return view_page(context, request)
 
     def test_it(self):
@@ -76,11 +77,10 @@ class ViewPageTests(unittest.TestCase):
 
 class AddPageTests(unittest.TestCase):
     def _callFUT(self, context, request):
-        from tutorial.views import add_page
+        from .views import add_page
         return add_page(context, request)
 
     def test_it_notsubmitted(self):
-        from pyramid.url import resource_url
         context = testing.DummyResource()
         request = testing.DummyRequest()
         request.subpath = ['AnotherPage']
@@ -88,7 +88,7 @@ class AddPageTests(unittest.TestCase):
         self.assertEqual(info['page'].data,'')
         self.assertEqual(
             info['save_url'],
-            resource_url(context, request, 'add_page', 'AnotherPage'))
+            request.resource_url(context, 'add_page', 'AnotherPage'))
 
     def test_it_submitted(self):
         context = testing.DummyResource()
@@ -103,17 +103,16 @@ class AddPageTests(unittest.TestCase):
 
 class EditPageTests(unittest.TestCase):
     def _callFUT(self, context, request):
-        from tutorial.views import edit_page
+        from .views import edit_page
         return edit_page(context, request)
 
     def test_it_notsubmitted(self):
-        from pyramid.url import resource_url
         context = testing.DummyResource()
         request = testing.DummyRequest()
         info = self._callFUT(context, request)
         self.assertEqual(info['page'], context)
         self.assertEqual(info['save_url'],
-                         resource_url(context, request, 'edit_page'))
+                         request.resource_url(context, 'edit_page'))
 
     def test_it_submitted(self):
         context = testing.DummyResource()
@@ -135,18 +134,16 @@ class FunctionalTests(unittest.TestCase):
     def setUp(self):
         import tempfile
         import os.path
-        from tutorial import main
+        from . import main
         self.tmpdir = tempfile.mkdtemp()
 
         dbpath = os.path.join( self.tmpdir, 'test.db')
-        from repoze.zodbconn.uri import db_from_uri
-        db = db_from_uri('file://' + dbpath)
-        settings = { 'zodb_uri' : None }
+        uri = 'file://' + dbpath
+        settings = { 'zodbconn.uri' : uri ,
+                     'pyramid.includes': ['pyramid_zodbconn', 'pyramid_tm'] }
 
         app = main({}, **settings)
-        from repoze.zodbconn.connector import Connector
-        app = Connector(app, db)
-        self.db = db
+        self.db = app.registry._zodb_databases['']
         from webtest import TestApp
         self.testapp = TestApp(app)
 
@@ -157,64 +154,68 @@ class FunctionalTests(unittest.TestCase):
 
     def test_root(self):
         res = self.testapp.get('/', status=302)
-        self.assertTrue(not res.body)
+        self.assertEqual(res.location, 'http://localhost/FrontPage')
 
     def test_FrontPage(self):
         res = self.testapp.get('/FrontPage', status=200)
-        self.assertTrue('FrontPage' in res.body)
+        self.assertTrue(b'FrontPage' in res.body)
 
     def test_unexisting_page(self):
         res = self.testapp.get('/SomePage', status=404)
-        self.assertTrue('Not Found' in res.body)
+        self.assertTrue(b'Not Found' in res.body)
+
+    def test_referrer_is_login(self):
+        res = self.testapp.get('/login', status=200)
+        self.assertTrue(b'name="came_from" value="/"' in res.body)
 
     def test_successful_log_in(self):
         res = self.testapp.get( self.viewer_login, status=302)
-        self.assertTrue(res.location == 'FrontPage')
+        self.assertEqual(res.location, 'http://localhost/FrontPage')
 
     def test_failed_log_in(self):
         res = self.testapp.get( self.viewer_wrong_login, status=200)
-        self.assertTrue('login' in res.body)
+        self.assertTrue(b'login' in res.body)
 
     def test_logout_link_present_when_logged_in(self):
         res = self.testapp.get( self.viewer_login, status=302)
         res = self.testapp.get('/FrontPage', status=200)
-        self.assertTrue('Logout' in res.body)
+        self.assertTrue(b'Logout' in res.body)
 
     def test_logout_link_not_present_after_logged_out(self):
         res = self.testapp.get( self.viewer_login, status=302)
         res = self.testapp.get('/FrontPage', status=200)
         res = self.testapp.get('/logout', status=302)
-        self.assertTrue('Logout' not in res.body)
+        self.assertTrue(b'Logout' not in res.body)
 
     def test_anonymous_user_cannot_edit(self):
         res = self.testapp.get('/FrontPage/edit_page', status=200)
-        self.assertTrue('Login' in res.body)
+        self.assertTrue(b'Login' in res.body)
 
     def test_anonymous_user_cannot_add(self):
         res = self.testapp.get('/add_page/NewPage', status=200)
-        self.assertTrue('Login' in res.body)
+        self.assertTrue(b'Login' in res.body)
 
     def test_viewer_user_cannot_edit(self):
         res = self.testapp.get( self.viewer_login, status=302)
         res = self.testapp.get('/FrontPage/edit_page', status=200)
-        self.assertTrue('Login' in res.body)
+        self.assertTrue(b'Login' in res.body)
 
     def test_viewer_user_cannot_add(self):
         res = self.testapp.get( self.viewer_login, status=302)
         res = self.testapp.get('/add_page/NewPage', status=200)
-        self.assertTrue('Login' in res.body)
+        self.assertTrue(b'Login' in res.body)
 
     def test_editors_member_user_can_edit(self):
         res = self.testapp.get( self.editor_login, status=302)
         res = self.testapp.get('/FrontPage/edit_page', status=200)
-        self.assertTrue('Editing' in res.body)
+        self.assertTrue(b'Editing' in res.body)
 
     def test_editors_member_user_can_add(self):
         res = self.testapp.get( self.editor_login, status=302)
         res = self.testapp.get('/add_page/NewPage', status=200)
-        self.assertTrue('Editing' in res.body)
+        self.assertTrue(b'Editing' in res.body)
 
     def test_editors_member_user_can_view(self):
         res = self.testapp.get( self.editor_login, status=302)
         res = self.testapp.get('/FrontPage', status=200)
-        self.assertTrue('FrontPage' in res.body)
+        self.assertTrue(b'FrontPage' in res.body)
diff --git a/docs/tutorials/wiki/src/tests/tutorial/views.py b/docs/tutorials/wiki/src/tests/tutorial/views.py
new file mode 100644
index 000000000..c271d2cc1
--- /dev/null
+++ b/docs/tutorials/wiki/src/tests/tutorial/views.py
@@ -0,0 +1,116 @@
+from docutils.core import publish_parts
+import re
+
+from pyramid.httpexceptions import HTTPFound
+
+from pyramid.view import (
+    view_config,
+    forbidden_view_config,
+    )
+
+from pyramid.security import (
+    remember,
+    forget,
+    )
+
+
+from .security import USERS
+from .models import Page
+
+# regular expression used to find WikiWords
+wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")
+
+@view_config(context='.models.Wiki',
+             permission='view')
+def view_wiki(context, request):
+    return HTTPFound(location=request.resource_url(context, 'FrontPage'))
+
+@view_config(context='.models.Page', renderer='templates/view.pt',
+             permission='view')
+def view_page(context, request):
+    wiki = context.__parent__
+
+    def check(match):
+        word = match.group(1)
+        if word in wiki:
+            page = wiki[word]
+            view_url = request.resource_url(page)
+            return '<a href="%s">%s</a>' % (view_url, word)
+        else:
+            add_url = request.application_url + '/add_page/' + word
+            return '<a href="%s">%s</a>' % (add_url, word)
+
+    content = publish_parts(context.data, writer_name='html')['html_body']
+    content = wikiwords.sub(check, content)
+    edit_url = request.resource_url(context, 'edit_page')
+
+    return dict(page=context, content=content, edit_url=edit_url,
+                logged_in=request.authenticated_userid)
+
+@view_config(name='add_page', context='.models.Wiki',
+             renderer='templates/edit.pt',
+             permission='edit')
+def add_page(context, request):
+    pagename = request.subpath[0]
+    if 'form.submitted' in request.params:
+        body = request.params['body']
+        page = Page(body)
+        page.__name__ = pagename
+        page.__parent__ = context
+        context[pagename] = page
+        return HTTPFound(location=request.resource_url(page))
+    save_url = request.resource_url(context, 'add_page', pagename)
+    page = Page('')
+    page.__name__ = pagename
+    page.__parent__ = context
+
+    return dict(page=page, save_url=save_url,
+                logged_in=request.authenticated_userid)
+
+@view_config(name='edit_page', context='.models.Page',
+             renderer='templates/edit.pt',
+             permission='edit')
+def edit_page(context, request):
+    if 'form.submitted' in request.params:
+        context.data = request.params['body']
+        return HTTPFound(location=request.resource_url(context))
+
+    return dict(page=context,
+                save_url=request.resource_url(context, 'edit_page'),
+                logged_in=request.authenticated_userid)
+
+@view_config(context='.models.Wiki', name='login',
+             renderer='templates/login.pt')
+@forbidden_view_config(renderer='templates/login.pt')
+def login(request):
+    login_url = request.resource_url(request.context, 'login')
+    referrer = request.url
+    if referrer == login_url:
+        referrer = '/'  # never use the login form itself as came_from
+    came_from = request.params.get('came_from', referrer)
+    message = ''
+    login = ''
+    password = ''
+    if 'form.submitted' in request.params:
+        login = request.params['login']
+        password = request.params['password']
+        if USERS.get(login) == password:
+            headers = remember(request, login)
+            return HTTPFound(location=came_from,
+                             headers=headers)
+        message = 'Failed login'
+
+    return dict(
+        message=message,
+        url=request.application_url + '/login',
+        came_from=came_from,
+        login=login,
+        password=password,
+    )
+
+
+@view_config(context='.models.Wiki', name='logout')
+def logout(request):
+    headers = forget(request)
+    return HTTPFound(location=request.resource_url(request.context),
+                     headers=headers)
diff --git a/docs/tutorials/wiki/src/views/CHANGES.txt b/docs/tutorials/wiki/src/views/CHANGES.txt
index 1544cf53b..35a34f332 100644
--- a/docs/tutorials/wiki/src/views/CHANGES.txt
+++ b/docs/tutorials/wiki/src/views/CHANGES.txt
@@ -1,3 +1,4 @@
-0.1
+0.0
+---
 
-  Initial version
+-  Initial version
diff --git a/docs/tutorials/wiki/src/views/README.txt b/docs/tutorials/wiki/src/views/README.txt
index d41f7f90f..dcb3605b8 100644
--- a/docs/tutorials/wiki/src/views/README.txt
+++ b/docs/tutorials/wiki/src/views/README.txt
@@ -1,4 +1,12 @@
 tutorial README
+==================
 
+Getting Started
+---------------
 
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki/src/views/development.ini b/docs/tutorials/wiki/src/views/development.ini
index 555010bed..6bf4b198e 100644
--- a/docs/tutorials/wiki/src/views/development.ini
+++ b/docs/tutorials/wiki/src/views/development.ini
@@ -1,34 +1,44 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = true
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = true
-default_locale_name = en
-zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
-
-[pipeline:main]
-pipeline =
-    egg:WebError#evalerror
-    egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
-    tutorial
-
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_zodbconn
+    pyramid_tm
+
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
-host = 0.0.0.0
+use = egg:waitress#main
+host = 127.0.0.1
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
-keys = root
+keys = root, tutorial
 
 [handlers]
 keys = console
@@ -40,6 +50,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
@@ -47,6 +62,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/views/production.ini b/docs/tutorials/wiki/src/views/production.ini
index 5c47ade9b..4e9892e7b 100644
--- a/docs/tutorials/wiki/src/views/production.ini
+++ b/docs/tutorials/wiki/src/views/production.ini
@@ -1,45 +1,36 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = false
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = false
-default_locale_name = en
-zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
-[filter:weberror]
-use = egg:WebError#error_catcher
-debug = false
-;error_log = 
-;show_exceptions_in_wsgi_errors = true
-;smtp_server = localhost
-;error_email = janitor@example.com
-;smtp_username = janitor
-;smtp_password = "janitor's password"
-;from_address = paste@localhost
-;error_subject_prefix = "Pyramid Error"
-;smtp_use_tls =
-;error_message =
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_tm
+    pyramid_zodbconn
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+tm.attempts = 3
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
-[pipeline:main]
-pipeline =
-    weberror
-    egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
-    tutorial
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
+use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial
@@ -66,6 +57,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/views/setup.cfg b/docs/tutorials/wiki/src/views/setup.cfg
deleted file mode 100644
index 3d7ea6e23..000000000
--- a/docs/tutorials/wiki/src/views/setup.cfg
+++ /dev/null
@@ -1,28 +0,0 @@
-[nosetests]
-match=^test
-nocapture=1
-cover-package=tutorial
-with-coverage=1
-cover-erase=1
-
-[compile_catalog]
-directory = tutorial/locale
-domain = tutorial
-statistics = true
-
-[extract_messages]
-add_comments = TRANSLATORS:
-output_file = tutorial/locale/tutorial.pot
-width = 80
-
-[init_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-
-[update_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-previous = true
-
diff --git a/docs/tutorials/wiki/src/views/setup.py b/docs/tutorials/wiki/src/views/setup.py
index daa5e5eb1..beeed75c9 100644
--- a/docs/tutorials/wiki/src/views/setup.py
+++ b/docs/tutorials/wiki/src/views/setup.py
@@ -3,30 +3,39 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
-    'repoze.zodbconn',
-    'repoze.tm2>=1.0b1', # default_commit_veto
-    'repoze.retry',
+    'pyramid_chameleon',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
+    'pyramid_zodbconn',
+    'transaction',
     'ZODB3',
-    'WebError',
+    'waitress',
     'docutils',
     ]
 
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
+
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Intended Audience :: Developers",
-        "Framework :: Pylons",
-        "Programming Language :: Python",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
       author='',
       author_email='',
       url='',
@@ -34,12 +43,12 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
+      extras_require={
+          'testing': tests_require,
+      },
       install_requires=requires,
-      tests_require=requires,
-      test_suite="tutorial",
-      entry_points = """\
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-      paster_plugins=['pyramid'],
       )
diff --git a/docs/tutorials/wiki/src/views/tutorial/__init__.py b/docs/tutorials/wiki/src/views/tutorial/__init__.py
index 04a01fead..f2a86df47 100644
--- a/docs/tutorials/wiki/src/views/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/views/tutorial/__init__.py
@@ -1,18 +1,18 @@
 from pyramid.config import Configurator
-from repoze.zodbconn.finder import PersistentApplicationFinder
-from tutorial.models import appmaker
+from pyramid_zodbconn import get_connection
+from .models import appmaker
+
+
+def root_factory(request):
+    conn = get_connection(request)
+    return appmaker(conn.root())
+
 
 def main(global_config, **settings):
-    """ This function returns a WSGI application.
+    """ This function returns a Pyramid WSGI application.
     """
-    zodb_uri = settings.get('zodb_uri', False)
-    if zodb_uri is False:
-        raise ValueError("No 'zodb_uri' in application configuration.")
-
-    finder = PersistentApplicationFinder(zodb_uri, appmaker)
-    def get_root(request):
-        return finder(request.environ)
-    config = Configurator(root_factory=get_root, settings=settings)
-    config.add_static_view('static', 'tutorial:static')
-    config.scan('tutorial')
+    config = Configurator(root_factory=root_factory, settings=settings)
+    config.include('pyramid_chameleon')
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.scan()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki/src/views/tutorial/models.py b/docs/tutorials/wiki/src/views/tutorial/models.py
index 9761856c6..aa907aee5 100644
--- a/docs/tutorials/wiki/src/views/tutorial/models.py
+++ b/docs/tutorials/wiki/src/views/tutorial/models.py
@@ -10,7 +10,7 @@ class Page(Persistent):
         self.data = data
 
 def appmaker(zodb_root):
-    if not 'app_root' in zodb_root:
+    if 'app_root' not in zodb_root:
         app_root = Wiki()
         frontpage = Page('This is the front page')
         app_root['FrontPage'] = frontpage
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/favicon.ico b/docs/tutorials/wiki/src/views/tutorial/static/favicon.ico
deleted file mode 100644
index 71f837c9e..000000000
--- a/docs/tutorials/wiki/src/views/tutorial/static/favicon.ico
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/footerbg.png b/docs/tutorials/wiki/src/views/tutorial/static/footerbg.png
deleted file mode 100644
index 1fbc873da..000000000
--- a/docs/tutorials/wiki/src/views/tutorial/static/footerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/headerbg.png b/docs/tutorials/wiki/src/views/tutorial/static/headerbg.png
deleted file mode 100644
index 0596f2020..000000000
--- a/docs/tutorials/wiki/src/views/tutorial/static/headerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/ie6.css b/docs/tutorials/wiki/src/views/tutorial/static/ie6.css
deleted file mode 100644
index b7c8493d8..000000000
--- a/docs/tutorials/wiki/src/views/tutorial/static/ie6.css
+++ /dev/null
@@ -1,8 +0,0 @@
-* html img,
-* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
-this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
-this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
-);}
-#wrap{display:table;height:100%}
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/middlebg.png b/docs/tutorials/wiki/src/views/tutorial/static/middlebg.png
deleted file mode 100644
index 2369cfb7d..000000000
--- a/docs/tutorials/wiki/src/views/tutorial/static/middlebg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/pylons.css b/docs/tutorials/wiki/src/views/tutorial/static/pylons.css
deleted file mode 100644
index fd1914d8d..000000000
--- a/docs/tutorials/wiki/src/views/tutorial/static/pylons.css
+++ /dev/null
@@ -1,65 +0,0 @@
-html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */
-vertical-align:baseline;background:transparent;}
-body{line-height:1;}
-ol,ul{list-style:none;}
-blockquote,q{quotes:none;}
-blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;}
-:focus{outline:0;}
-ins{text-decoration:none;}
-del{text-decoration:line-through;}
-table{border-collapse:collapse;border-spacing:0;}
-sub{vertical-align:sub;font-size:smaller;line-height:normal;}
-sup{vertical-align:super;font-size:smaller;line-height:normal;}
-ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;}
-ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;}
-li{display:list-item;}
-ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;}
-ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;}
-ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;}
-.hidden{display:none;}
-p{line-height:1.5em;}
-h1{font-size:1.75em;line-height:1.7em;font-family:helvetica,verdana;}
-h2{font-size:1.5em;line-height:1.7em;font-family:helvetica,verdana;}
-h3{font-size:1.25em;line-height:1.7em;font-family:helvetica,verdana;}
-h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;}
-html,body{width:100%;height:100%;}
-body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;}
-a{color:#1b61d6;text-decoration:none;}
-a:hover{color:#e88f00;text-decoration:underline;}
-body h1,
-body h2,
-body h3,
-body h4,
-body h5,
-body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;}
-#wrap{min-height:100%;}
-#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;}
-#header{background:#000000;top:0;font-size:14px;}
-#footer{bottom:0;background:#000000 url(footerbg.png) repeat-x 0 top;position:relative;margin-top:-40px;clear:both;}
-.header,.footer{width:750px;margin-right:auto;margin-left:auto;}
-.wrapper{width:100%}
-#top,#top-small,#bottom{width:100%;}
-#top{color:#000000;height:230px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#top-small{color:#000000;height:60px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#bottom{color:#222;background-color:#ffffff;}
-.top,.top-small,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;}
-.top{padding-top:40px;}
-.top-small{padding-top:10px;}
-#middle{width:100%;height:100px;background:url(middlebg.png) repeat-x;border-top:2px solid #ffffff;border-bottom:2px solid #b2b2b2;}
-.app-welcome{margin-top:25px;}
-.app-name{color:#000000;font-weight:bold;}
-.bottom{padding-top:50px;}
-#left{width:350px;float:left;padding-right:25px;}
-#right{width:350px;float:right;padding-left:25px;}
-.align-left{text-align:left;}
-.align-right{text-align:right;}
-.align-center{text-align:center;}
-ul.links{margin:0;padding:0;}
-ul.links li{list-style-type:none;font-size:14px;}
-form{border-style:none;}
-fieldset{border-style:none;}
-input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;}
-input[type=text],input[type=password]{width:205px;}
-input[type=submit]{background-color:#ddd;font-weight:bold;}
-/*Opera Fix*/
-body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;}
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki/src/views/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki/src/views/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/pyramid-small.png b/docs/tutorials/wiki/src/views/tutorial/static/pyramid-small.png
deleted file mode 100644
index a5bc0ade7..000000000
--- a/docs/tutorials/wiki/src/views/tutorial/static/pyramid-small.png
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/pyramid.png b/docs/tutorials/wiki/src/views/tutorial/static/pyramid.png
index 347e05549..4ab837be9 100644
--- a/docs/tutorials/wiki/src/views/tutorial/static/pyramid.png
+++ b/docs/tutorials/wiki/src/views/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/theme.css b/docs/tutorials/wiki/src/views/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki/src/views/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki/src/views/tutorial/static/transparent.gif b/docs/tutorials/wiki/src/views/tutorial/static/transparent.gif
deleted file mode 100644
index 0341802e5..000000000
--- a/docs/tutorials/wiki/src/views/tutorial/static/transparent.gif
+++ /dev/null
diff --git a/docs/tutorials/wiki/src/views/tutorial/templates/edit.pt b/docs/tutorials/wiki/src/views/tutorial/templates/edit.pt
index 6dbb0edde..b23f45d56 100644
--- a/docs/tutorials/wiki/src/views/tutorial/templates/edit.pt
+++ b/docs/tutorials/wiki/src/views/tutorial/templates/edit.pt
@@ -1,58 +1,69 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
-      xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>${page.__name__} - Pyramid tutorial wiki (based on
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>${page.__name__} - Pyramid tutorial wiki (based on
     TurboGears 20-Minute Wiki)</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon"
-        href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/pylons.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/ie6.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top-small">
-      <div class="top-small align-center">
-        <div>
-          <img width="220" height="50" alt="pyramid"
-        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <p>
+                  Editing <strong><span tal:replace="page.__name__">
+                  Page Name Goes Here</span></strong>
+              </p>
+              <p>You can return to the
+                <a href="${request.application_url}">FrontPage</a>.
+              </p>
+              <form action="${save_url}" method="post">
+                <div class="form-group">
+                  <textarea class="form-control" name="body" tal:content="page.data" rows="10" cols="60"></textarea>
+                </div>
+                <div class="form-group">
+                  <button type="submit" name="form.submitted" value="Save" class="btn btn-default">Save</button>
+                </div>
+              </form>
+            </div>
+          </div>
         </div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-right">
-        <div id="left" class="app-welcome align-left">
-          Editing <b><span tal:replace="page.__name__">Page Name Goes
-            Here</span></b><br/>
-          You can return to the
-          <a href="${request.application_url}">FrontPage</a>.<br/>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
         </div>
-        <div id="right" class="app-welcome align-right"></div>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <form action="${save_url}" method="post">
-          <textarea name="body" tal:content="page.data" rows="10"
-                    cols="60"/><br/>
-          <input type="submit" name="form.submitted" value="Save"/>
-        </form>
       </div>
     </div>
-  </div>
-  <div id="footer">
-    <div class="footer"
-         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
 </html>
diff --git a/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt
index d98420680..f8cbe2e2c 100644
--- a/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt
@@ -1,75 +1,67 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>The Pyramid Web Application Development Framework</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon" href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
-  <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton|Nobile:regular,i,b,bi&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top">
-      <div class="top align-center">
-        <div><img src="${request.static_url('tutorial:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-center">
-        <p class="app-welcome">
-          Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web application development framework.
-        </p>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div id="left" class="align-right">
-          <h2>Search documentation</h2>
-          <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/dev/search.html">
-                <input type="text" id="q" name="q" value="" />
-                <input type="submit" id="x" value="Go" />
-            </form>
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>ZODB Scaffold for The Pyramid Web Framework</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">ZODB scaffold</span></h1>
+              <p class="lead">Welcome to <span class="font-normal">${project}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7</span>.</p>
+            </div>
+          </div>
         </div>
-        <div id="right" class="align-left">
-          <h2>Pyramid links</h2>
-          <ul class="links">
-            <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#narrative-documentation">Narrative Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#api-documentation">API Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#tutorials">Tutorials</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#change-history">Change History</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#sample-applications">Sample Applications</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#support-and-development">Support and Development</a>
-            </li>
-            <li>
-              <a href="irc://irc.freenode.net#pyramid">IRC Channel</a>
-            </li>
+        <div class="row">
+          <div class="links">
+            <ul>
+              <li class="current-version">Generated by v1.7</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
+              <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
+              <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
+              <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
             </ul>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
         </div>
       </div>
     </div>
-  </div>
-  <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
 </html>
diff --git a/docs/tutorials/wiki/src/views/tutorial/templates/view.pt b/docs/tutorials/wiki/src/views/tutorial/templates/view.pt
index 537ae3a15..93580658b 100644
--- a/docs/tutorials/wiki/src/views/tutorial/templates/view.pt
+++ b/docs/tutorials/wiki/src/views/tutorial/templates/view.pt
@@ -1,61 +1,69 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
-      xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>${page.__name__} - Pyramid tutorial wiki (based on
-      TurboGears 20-Minute Wiki)</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon"
-        href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/pylons.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/ie6.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top-small">
-      <div class="top-small align-center">
-        <div>
-          <img width="220" height="50" alt="pyramid"
-        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
+<!DOCTYPE html>
+<html lang="${request.locale_name}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="${request.static_url('tutorial:static/pyramid-16x16.png')}">
+
+    <title>${page.__name__} - Pyramid tutorial wiki (based on
+    TurboGears 20-Minute Wiki)</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="${request.static_url('tutorial:static/theme.css')}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="${request.static_url('tutorial:static/pyramid.png')}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+              <div tal:replace="structure content">
+                Page text goes here.
+              </div>
+              <p>
+                <a tal:attributes="href edit_url" href="">
+                  Edit this page
+                </a>
+              </p>
+              <p>
+                  Viewing <strong><span tal:replace="page.__name__">
+                  Page Name Goes Here</span></strong>
+              </p>
+              <p>You can return to the
+                <a href="${request.application_url}">FrontPage</a>.
+              </p>
+            </div>
+          </div>
         </div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-right">
-        <div id="left" class="app-welcome align-left">
-          Viewing <b><span tal:replace="page.__name__">Page Name Goes
-          Here</span></b><br/>
-          You can return to the
-          <a href="${request.application_url}">FrontPage</a>.<br/>
-        </div>
-        <div id="right" class="app-welcome align-right"></div>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div tal:replace="structure content">
-          Page text goes here.
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
         </div>
-        <p>
-          <a tal:attributes="href edit_url" href="">
-            Edit this page
-          </a>
-        </p>
       </div>
     </div>
-  </div>
-  <div id="footer">
-    <div class="footer"
-         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
 </html>
diff --git a/docs/tutorials/wiki/src/views/tutorial/tests.py b/docs/tutorials/wiki/src/views/tutorial/tests.py
index 28e424884..40f3c47af 100644
--- a/docs/tutorials/wiki/src/views/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/views/tutorial/tests.py
@@ -2,126 +2,16 @@ import unittest
 
 from pyramid import testing
 
-class PageModelTests(unittest.TestCase):
 
-    def _getTargetClass(self):
-        from tutorial.models import Page
-        return Page
+class ViewTests(unittest.TestCase):
+    def setUp(self):
+        self.config = testing.setUp()
 
-    def _makeOne(self, data=u'some data'):
-        return self._getTargetClass()(data=data)
+    def tearDown(self):
+        testing.tearDown()
 
-    def test_constructor(self):
-        instance = self._makeOne()
-        self.assertEqual(instance.data, u'some data')
-        
-class WikiModelTests(unittest.TestCase):
-
-    def _getTargetClass(self):
-        from tutorial.models import Wiki
-        return Wiki
-
-    def _makeOne(self):
-        return self._getTargetClass()()
-
-    def test_it(self):
-        wiki = self._makeOne()
-        self.assertEqual(wiki.__parent__, None)
-        self.assertEqual(wiki.__name__, None)
-
-class AppmakerTests(unittest.TestCase):
-    def _callFUT(self, zodb_root):
-        from tutorial.models import appmaker
-        return appmaker(zodb_root)
-
-    def test_it(self):
-        root = {}
-        self._callFUT(root)
-        self.assertEqual(root['app_root']['FrontPage'].data,
-                         'This is the front page')
-
-class ViewWikiTests(unittest.TestCase):
-    def test_it(self):
-        from tutorial.views import view_wiki
-        context = testing.DummyResource()
-        request = testing.DummyRequest()
-        response = view_wiki(context, request)
-        self.assertEqual(response.location, 'http://example.com/FrontPage')
-
-class ViewPageTests(unittest.TestCase):
-    def _callFUT(self, context, request):
-        from tutorial.views import view_page
-        return view_page(context, request)
-
-    def test_it(self):
-        wiki = testing.DummyResource()
-        wiki['IDoExist'] = testing.DummyResource()
-        context = testing.DummyResource(data='Hello CruelWorld IDoExist')
-        context.__parent__ = wiki
-        context.__name__ = 'thepage'
-        request = testing.DummyRequest()
-        info = self._callFUT(context, request)
-        self.assertEqual(info['page'], context)
-        self.assertEqual(
-            info['content'], 
-            '<div class="document">\n'
-            '<p>Hello <a href="http://example.com/add_page/CruelWorld">'
-            'CruelWorld</a> '
-            '<a href="http://example.com/IDoExist/">'
-            'IDoExist</a>'
-            '</p>\n</div>\n')
-        self.assertEqual(info['edit_url'],
-                         'http://example.com/thepage/edit_page')
-        
-    
-class AddPageTests(unittest.TestCase):
-    def _callFUT(self, context, request):
-        from tutorial.views import add_page
-        return add_page(context, request)
-
-    def test_it_notsubmitted(self):
-        from pyramid.url import resource_url
-        context = testing.DummyResource()
-        request = testing.DummyRequest()
-        request.subpath = ['AnotherPage']
-        info = self._callFUT(context, request)
-        self.assertEqual(info['page'].data,'')
-        self.assertEqual(
-            info['save_url'],
-            resource_url(context, request, 'add_page', 'AnotherPage'))
-        
-    def test_it_submitted(self):
-        context = testing.DummyResource()
-        request = testing.DummyRequest({'form.submitted':True,
-                                        'body':'Hello yo!'})
-        request.subpath = ['AnotherPage']
-        self._callFUT(context, request)
-        page = context['AnotherPage']
-        self.assertEqual(page.data, 'Hello yo!')
-        self.assertEqual(page.__name__, 'AnotherPage')
-        self.assertEqual(page.__parent__, context)
-
-class EditPageTests(unittest.TestCase):
-    def _callFUT(self, context, request):
-        from tutorial.views import edit_page
-        return edit_page(context, request)
-
-    def test_it_notsubmitted(self):
-        from pyramid.url import resource_url
-        context = testing.DummyResource()
+    def test_my_view(self):
+        from .views import my_view
         request = testing.DummyRequest()
-        info = self._callFUT(context, request)
-        self.assertEqual(info['page'], context)
-        self.assertEqual(info['save_url'],
-                         resource_url(context, request, 'edit_page'))
-        
-    def test_it_submitted(self):
-        context = testing.DummyResource()
-        request = testing.DummyRequest({'form.submitted':True,
-                                        'body':'Hello yo!'})
-        response = self._callFUT(context, request)
-        self.assertEqual(response.location, 'http://example.com/')
-        self.assertEqual(context.data, 'Hello yo!')
-        
-        
-        
+        info = my_view(request)
+        self.assertEqual(info['project'], 'tutorial')
diff --git a/docs/tutorials/wiki/src/views/tutorial/views.py b/docs/tutorials/wiki/src/views/tutorial/views.py
index 42420f2fe..61517c31d 100644
--- a/docs/tutorials/wiki/src/views/tutorial/views.py
+++ b/docs/tutorials/wiki/src/views/tutorial/views.py
@@ -2,20 +2,18 @@ from docutils.core import publish_parts
 import re
 
 from pyramid.httpexceptions import HTTPFound
-from pyramid.url import resource_url
 from pyramid.view import view_config
 
-from tutorial.models import Page
+from .models import Page
 
 # regular expression used to find WikiWords
 wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")
 
-@view_config(context='tutorial.models.Wiki')
+@view_config(context='.models.Wiki')
 def view_wiki(context, request):
-    return HTTPFound(location=resource_url(context, request, 'FrontPage'))
+    return HTTPFound(location=request.resource_url(context, 'FrontPage'))
 
-@view_config(context='tutorial.models.Page',
-             renderer='tutorial:templates/view.pt')
+@view_config(context='.models.Page', renderer='templates/view.pt')
 def view_page(context, request):
     wiki = context.__parent__
 
@@ -23,7 +21,7 @@ def view_page(context, request):
         word = match.group(1)
         if word in wiki:
             page = wiki[word]
-            view_url = resource_url(page, request)
+            view_url = request.resource_url(page)
             return '<a href="%s">%s</a>' % (view_url, word)
         else:
             add_url = request.application_url + '/add_page/' + word 
@@ -31,34 +29,32 @@ def view_page(context, request):
 
     content = publish_parts(context.data, writer_name='html')['html_body']
     content = wikiwords.sub(check, content)
-    edit_url = resource_url(context, request, 'edit_page')
+    edit_url = request.resource_url(context, 'edit_page')
     return dict(page = context, content = content, edit_url = edit_url)
 
-@view_config(name='add_page', context='tutorial.models.Wiki',
-             renderer='tutorial:templates/edit.pt')
+@view_config(name='add_page', context='.models.Wiki',
+             renderer='templates/edit.pt')
 def add_page(context, request):
-    name = request.subpath[0]
+    pagename = request.subpath[0]
     if 'form.submitted' in request.params:
         body = request.params['body']
         page = Page(body)
-        page.__name__ = name
+        page.__name__ = pagename
         page.__parent__ = context
-        context[name] = page
-        return HTTPFound(location = resource_url(page, request))
-    save_url = resource_url(context, request, 'add_page', name)
+        context[pagename] = page
+        return HTTPFound(location = request.resource_url(page))
+    save_url = request.resource_url(context, 'add_page', pagename)
     page = Page('')
-    page.__name__ = name
+    page.__name__ = pagename
     page.__parent__ = context
     return dict(page = page, save_url = save_url)
 
-@view_config(name='edit_page', context='tutorial.models.Page',
-             renderer='tutorial:templates/edit.pt')
+@view_config(name='edit_page', context='.models.Page',
+             renderer='templates/edit.pt')
 def edit_page(context, request):
     if 'form.submitted' in request.params:
         context.data = request.params['body']
-        return HTTPFound(location = resource_url(context, request))
+        return HTTPFound(location = request.resource_url(context))
 
-    return dict(page = context,
-                save_url = resource_url(context, request, 'edit_page'))
-    
-    
+    return dict(page=context,
+                save_url=request.resource_url(context, 'edit_page'))
diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst
index c843a0129..788ec595b 100644
--- a/docs/tutorials/wiki/tests.rst
+++ b/docs/tutorials/wiki/tests.rst
@@ -1,78 +1,75 @@
+.. _wiki_adding_tests:
+
 ============
 Adding Tests
 ============
 
-We will now add tests for the models and the views and a few functional
-tests in the ``tests.py``.  Tests ensure that an application works, and
-that it continues to work after some changes are made in the future.
+We will now add tests for the models and the views and a few functional tests
+in ``tests.py``.  Tests ensure that an application works, and that it
+continues to work when changes are made in the future.
 
-Testing the Models
-==================
+Test the models
+===============
 
-We write tests for the model
-classes and the appmaker.  Changing ``tests.py``, we'll write a separate test
-class for each model class, and we'll write a test class for the
-``appmaker``.
+We write tests for the ``model`` classes and the ``appmaker``.  Changing
+``tests.py``, we'll write a separate test class for each ``model`` class, and
+we'll write a test class for the ``appmaker``.
 
-To do so, we'll retain the ``tutorial.tests.ViewTests`` class provided as a
-result of the ``pyramid_zodb`` project generator.  We'll add three test
-classes: one for the ``Page`` model named ``PageModelTests``, one for the
-``Wiki`` model named ``WikiModelTests``, and one for the appmaker named
-``AppmakerTests``.
+To do so, we'll retain the ``tutorial.tests.ViewTests`` class that was
+generated as part of the ``zodb`` scaffold.  We'll add three test classes: one
+for the ``Page`` model named ``PageModelTests``, one for the ``Wiki`` model
+named ``WikiModelTests``, and one for the appmaker named ``AppmakerTests``.
 
-Testing the Views
-=================
+Test the views
+==============
 
 We'll modify our ``tests.py`` file, adding tests for each view function we
-added above.  As a result, we'll *delete* the ``ViewTests`` test in the file,
-and add four other test classes: ``ViewWikiTests``, ``ViewPageTests``,
-``AddPageTests``, and ``EditPageTests``.  These test the ``view_wiki``,
-``view_page``, ``add_page``, and ``edit_page`` views respectively.
-
+added previously.  As a result, we'll *delete* the ``ViewTests`` class that
+the ``zodb`` scaffold provided, and add four other test classes:
+``ViewWikiTests``, ``ViewPageTests``, ``AddPageTests``, and ``EditPageTests``.
+These test the ``view_wiki``, ``view_page``, ``add_page``, and ``edit_page``
+views.
 
 Functional tests
 ================
 
-We test the whole application, covering security aspects that are not
+We'll test the whole application, covering security aspects that are not
 tested in the unit tests, like logging in, logging out, checking that
 the ``viewer`` user cannot add or edit pages, but the ``editor`` user
 can, and so on.
 
-Viewing the results of all our edits to ``tests.py``
-====================================================
+View the results of all our edits to ``tests.py``
+=================================================
 
-Once we're done with the ``tests.py`` module, it will look a lot like the
-below:
+Open the ``tutorial/tests.py`` module, and edit it such that it appears as
+follows:
 
 .. literalinclude:: src/tests/tutorial/tests.py
    :linenos:
    :language: python
 
-Running the Tests
+Running the tests
 =================
 
-We can run these tests by using ``setup.py test`` in the same way we did in
-:ref:`running_tests`.  Assuming our shell's current working directory is the
-"tutorial" distribution directory:
+We can run these tests by using ``py.test`` similarly to how we did in
+:ref:`running_tests`. Our testing dependencies have already been satisfied,
+courtesy of the scaffold, so we can jump right to running tests.
 
 On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py test -q
+   $ $VENV/bin/py.test tutorial/tests.py -q
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial/tests.py -q
 
-The expected result looks something like:
+The expected result should look like the following:
 
 .. code-block:: text
 
-   .........
-   ----------------------------------------------------------------------
-   Ran 23 tests in 1.653s
-   
-   OK
+   ........................
+   24 passed in 2.46 seconds
diff --git a/docs/tutorials/wiki2/authentication.rst b/docs/tutorials/wiki2/authentication.rst
new file mode 100644
index 000000000..5447db861
--- /dev/null
+++ b/docs/tutorials/wiki2/authentication.rst
@@ -0,0 +1,312 @@
+.. _wiki2_adding_authentication:
+
+=====================
+Adding authentication
+=====================
+
+:app:`Pyramid` provides facilities for :term:`authentication` and
+:term:`authorization`. In this section we'll focus solely on the authentication
+APIs to add login and logout functionality to our wiki.
+
+We will implement authentication with the following steps:
+
+* Add an :term:`authentication policy` and a ``request.user`` computed property
+  (``security.py``).
+* Add routes for ``/login`` and ``/logout`` (``routes.py``).
+* Add login and logout views (``views/auth.py``).
+* Add a login template (``login.jinja2``).
+* Add "Login" and "Logout" links to every page based on the user's
+  authenticated state (``layout.jinja2``).
+* Make the existing views verify user state (``views/default.py``).
+* Redirect to ``/login`` when a user is denied access to any of the views that
+  require permission, instead of a default "403 Forbidden" page
+  (``views/auth.py``).
+
+
+Authenticating requests
+-----------------------
+
+The core of :app:`Pyramid` authentication is an :term:`authentication policy`
+which is used to identify authentication information from a ``request``,
+as well as handling the low-level login and logout operations required to
+track users across requests (via cookies, headers, or whatever else you can
+imagine).
+
+
+Add the authentication policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a new file ``tutorial/security.py`` with the following content:
+
+.. literalinclude:: src/authentication/tutorial/security.py
+   :linenos:
+   :language: python
+
+Here we've defined:
+
+* A new authentication policy named ``MyAuthenticationPolicy``, which is
+  subclassed from Pyramid's
+  :class:`pyramid.authentication.AuthTktAuthenticationPolicy`, which tracks the
+  :term:`userid` using a signed cookie (lines 7-11).
+* A ``get_user`` function, which can convert the ``unauthenticated_userid``
+  from the policy into a ``User`` object from our database (lines 13-17).
+* The ``get_user`` is registered on the request as ``request.user`` to be used
+  throughout our application as the authenticated ``User`` object for the
+  logged-in user (line 27).
+
+The logic in this file is a little bit interesting, so we'll go into detail
+about what's happening here:
+
+First, the default authentication policies all provide a method named
+``unauthenticated_userid`` which is responsible for the low-level parsing
+of the information in the request (cookies, headers, etc.). If a ``userid``
+is found, then it is returned from this method. This is named
+``unauthenticated_userid`` because, at the lowest level, it knows the value of
+the userid in the cookie, but it doesn't know if it's actually a user in our
+system (remember, anything the user sends to our app is untrusted).
+
+Second, our application should only care about ``authenticated_userid`` and
+``request.user``, which have gone through our application-specific process of
+validating that the user is logged in.
+
+In order to provide an ``authenticated_userid`` we need a verification step.
+That can happen anywhere, so we've elected to do it inside of the cached
+``request.user`` computed property. This is a convenience that makes
+``request.user`` the source of truth in our system. It is either ``None`` or
+a ``User`` object from our database. This is why the ``get_user`` function
+uses the ``unauthenticated_userid`` to check the database.
+
+
+Configure the app
+~~~~~~~~~~~~~~~~~
+
+Since we've added a new ``tutorial/security.py`` module, we need to include it.
+Open the file ``tutorial/__init__.py`` and edit the following lines:
+
+.. literalinclude:: src/authentication/tutorial/__init__.py
+   :linenos:
+   :emphasize-lines: 11
+   :language: python
+
+Our authentication policy is expecting a new setting, ``auth.secret``. Open
+the file ``development.ini`` and add the highlighted line below:
+
+.. literalinclude:: src/authentication/development.ini
+   :lines: 18-20
+   :emphasize-lines: 3
+   :lineno-match:
+   :language: ini
+
+Finally, best practices tell us to use a different secret for production, so
+open ``production.ini`` and add a different secret:
+
+.. literalinclude:: src/authentication/production.ini
+   :lines: 15-17
+   :emphasize-lines: 3
+   :lineno-match:
+   :language: ini
+
+
+Add permission checks
+~~~~~~~~~~~~~~~~~~~~~
+
+:app:`Pyramid` has full support for declarative authorization, which we'll
+cover in the next chapter. However, many people looking to get their feet wet
+are just interested in authentication with some basic form of home-grown
+authorization. We'll show below how to accomplish the simple security goals of
+our wiki, now that we can track the logged-in state of users.
+
+Remember our goals:
+
+* Allow only ``editor`` and ``basic`` logged-in users to create new pages.
+* Only allow ``editor`` users and the page creator (possibly a ``basic`` user)
+  to edit pages.
+
+Open the file ``tutorial/views/default.py`` and fix the following imports:
+
+.. literalinclude:: src/authentication/tutorial/views/default.py
+   :lines: 5-13
+   :lineno-match:
+   :emphasize-lines: 2,9
+   :language: python
+
+Change the two highlighted lines.
+
+In the same file, now edit the ``edit_page`` view function:
+
+.. literalinclude:: src/authentication/tutorial/views/default.py
+   :lines: 45-60
+   :lineno-match:
+   :emphasize-lines: 5-7
+   :language: python
+
+Only the highlighted lines need to be changed.
+
+If the user either is not logged in or the user is not the page's creator
+*and* not an ``editor``, then we raise ``HTTPForbidden``.
+
+In the same file, now edit the ``add_page`` view function:
+
+.. literalinclude:: src/authentication/tutorial/views/default.py
+   :lines: 62-76
+   :lineno-match:
+   :emphasize-lines: 3-5,13
+   :language: python
+
+Only the highlighted lines need to be changed.
+
+If the user either is not logged in or is not in the ``basic`` or ``editor``
+roles, then we raise ``HTTPForbidden``, which will return a "403 Forbidden"
+response to the user. However, we will hook this later to redirect to the login
+page. Also, now that we have ``request.user``, we no longer have to hard-code
+the creator as the ``editor`` user, so we can finally drop that hack.
+
+These simple checks should protect our views.
+
+
+Login, logout
+-------------
+
+Now that we've got the ability to detect logged-in users, we need to add the
+``/login`` and ``/logout`` views so that they can actually login and logout!
+
+
+Add routes for ``/login`` and ``/logout``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Go back to ``tutorial/routes.py`` and add these two routes as highlighted:
+
+.. literalinclude:: src/authentication/tutorial/routes.py
+   :lines: 3-6
+   :lineno-match:
+   :emphasize-lines: 2-3
+   :language: python
+
+.. note:: The preceding lines must be added *before* the following
+   ``view_page`` route definition:
+
+   .. literalinclude:: src/authentication/tutorial/routes.py
+      :lines: 6
+      :lineno-match:
+      :language: python
+
+   This is because ``view_page``'s route definition uses a catch-all
+   "replacement marker" ``/{pagename}`` (see :ref:`route_pattern_syntax`),
+   which will catch any route that was not already caught by any route
+   registered before it. Hence, for ``login`` and ``logout`` views to
+   have the opportunity of being matched (or "caught"), they must be above
+   ``/{pagename}``.
+
+
+Add login, logout, and forbidden views
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a new file ``tutorial/views/auth.py``, and add the following code to it:
+
+.. literalinclude:: src/authentication/tutorial/views/auth.py
+   :linenos:
+   :language: python
+
+This code adds three new views to the application:
+
+- The ``login`` view renders a login form and processes the post from the
+  login form, checking credentials against our ``users`` table in the database.
+
+  The check is done by first finding a ``User`` record in the database, then
+  using our ``user.check_password`` method to compare the hashed passwords.
+
+  If the credentials are valid, then we use our authentication policy to store
+  the user's id in the response using :meth:`pyramid.security.remember`.
+
+  Finally, the user is redirected back to either the page which they were
+  trying to access (``next``) or the front page as a fallback. This parameter
+  is used by our forbidden view, as explained below, to finish the login
+  workflow.
+
+- The ``logout`` view handles requests to ``/logout`` by clearing the
+  credentials using :meth:`pyramid.security.forget`, then redirecting them to
+  the front page.
+
+- The ``forbidden_view`` is registered using the
+  :class:`pyramid.view.forbidden_view_config` decorator. This is a special
+  :term:`exception view`, which is invoked when a
+  :class:`pyramid.httpexceptions.HTTPForbidden` exception is raised.
+
+  This view will handle a forbidden error by redirecting the user to
+  ``/login``. As a convenience, it also sets the ``next=`` query string to the
+  current URL (the one that is forbidding access). This way, if the user
+  successfully logs in, they will be sent back to the page which they had been
+  trying to access.
+
+
+Add the ``login.jinja2`` template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create ``tutorial/templates/login.jinja2`` with the following content:
+
+.. literalinclude:: src/authentication/tutorial/templates/login.jinja2
+   :language: html
+
+The above template is referenced in the login view that we just added in
+``tutorial/views/auth.py``.
+
+
+Add "Login" and "Logout" links
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Open ``tutorial/templates/layout.jinja2`` and add the following code as
+indicated by the highlighted lines.
+
+.. literalinclude:: src/authentication/tutorial/templates/layout.jinja2
+   :lines: 35-46
+   :lineno-match:
+   :emphasize-lines: 2-10
+   :language: html
+
+The ``request.user`` will be ``None`` if the user is not authenticated, or a
+``tutorial.models.User`` object if the user is authenticated. This check will
+make the logout link shown only when the user is logged in, and conversely the
+login link is only shown when the user is logged out.
+
+
+Viewing the application in a browser
+------------------------------------
+
+We can finally examine our application in a browser (See
+:ref:`wiki2-start-the-application`).  Launch a browser and visit each of the
+following URLs, checking that the result is as expected:
+
+- http://localhost:6543/ invokes the ``view_wiki`` view.  This always
+  redirects to the ``view_page`` view of the ``FrontPage`` page object.  It
+  is executable by any user.
+
+- http://localhost:6543/FrontPage invokes the ``view_page`` view of the
+  ``FrontPage`` page object. There is a "Login" link in the upper right corner
+  while the user is not authenticated, else it is a "Logout" link when the user
+  is authenticated.
+
+- http://localhost:6543/FrontPage/edit_page invokes the ``edit_page`` view for
+  the ``FrontPage`` page object.  It is executable by only the ``editor`` user.
+  If a different user (or the anonymous user) invokes it, then a login form
+  will be displayed. Supplying the credentials with the username ``editor`` and
+  password ``editor`` will display the edit page form.
+
+- http://localhost:6543/add_page/SomePageName invokes the ``add_page`` view for
+  a page. If the page already exists, then it redirects the user to the
+  ``edit_page`` view for the page object. It is executable by either the
+  ``editor`` or ``basic`` user.  If a different user (or the anonymous user)
+  invokes it, then a login form will be displayed. Supplying the credentials
+  with either the username ``editor`` and password ``editor``, or username
+  ``basic`` and password ``basic``, will display the edit page form.
+
+- http://localhost:6543/SomePageName/edit_page invokes the ``edit_page`` view
+  for an existing page, or generates an error if the page does not exist. It is
+  editable by the ``basic`` user if the page was created by that user in the
+  previous step. If, instead, the page was created by the ``editor`` user, then
+  the login page should be shown for the ``basic`` user.
+
+- After logging in (as a result of hitting an edit or add page and submitting
+  the login form with the ``editor`` credentials), we'll see a "Logout" link in
+  the upper right hand corner.  When we click it, we're logged out, redirected
+  back to the front page, and a "Login" link is shown in the upper right hand
+  corner.
diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index 76ce4b83f..234f40e3b 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -1,311 +1,263 @@
 .. _wiki2_adding_authorization:
 
 ====================
-Adding Authorization
+Adding authorization
 ====================
 
-Our application currently allows anyone with access to the server to
-view, edit, and add pages to our wiki.  For purposes of demonstration
-we'll change our application to allow only people whom possess a
-specific username (`editor`) to add and edit wiki pages but we'll
-continue allowing anyone with access to the server to view pages.
-:app:`Pyramid` provides facilities for :term:`authorization` and
-:term:`authentication`.  We'll make use of both features to provide security
-to our application.
-
-We will add an :term:`authentication policy` and an
-:term:`authorization policy` to our :term:`application
-registry`, add a ``security.py`` module, create a :term:`root factory`
-with an :term:`ACL`, and add :term:`permission` declarations to
-the ``edit_page`` and ``add_page`` views.
-
-Then we will add ``login`` and ``logout`` views, and modify the
-existing views to make them return a ``logged_in`` flag to the
-renderer.
-
-Finally, we will add a ``login.pt`` template and change the existing
-``view.pt`` and ``edit.pt`` to show a "Logout" link when not logged in.
-
-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
-``__init__.py`` file.  The objects generated by the root factory will be used
-as the :term:`context` of each request to our application.  We do this to
-allow :app:`Pyramid` declarative security to work properly.  The context
-object generated by the root factory during a request will be decorated with
-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 :app:`Pyramid`.
-
-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:
-
-.. literalinclude:: src/authorization/tutorial/models.py
-   :lines: 3-4,45-49
-   :linenos:
-   :language: python
+In the last chapter we built :term:`authentication` into our wiki. We also
+went one step further and used the ``request.user`` object to perform some
+explicit :term:`authorization` checks. This is fine for a lot of applications,
+but :app:`Pyramid` provides some facilities for cleaning this up and decoupling
+the constraints from the view function itself.
 
-The ``RootFactory`` class we've just added will be used by :app:`Pyramid` to
-construct a ``context`` object.  The context is attached to the request
-object passed to our view callables as the ``context`` attribute.
-
-The context object generated by our root factory will possess an ``__acl__``
-attribute that allows :data:`pyramid.security.Everyone` (a special principal)
-to view all pages, while allowing only a :term:`principal` named
-``group:editors`` to edit and add pages.  The ``__acl__`` attribute attached
-to a context is interpreted specially by :app:`Pyramid` as 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`` argument to
-   :meth:`pyramid.config.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`.
-
-Configuring an Authorization Policy
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For any :app:`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 need to import the new policies:
-
-.. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 2-3,8
-   :linenos:
-   :language: python
+We will implement access control with the following steps:
 
-Then, we'll add those policies to the configuration:
+* Update the :term:`authentication policy` to break down the :term:`userid`
+  into a list of :term:`principals <principal>` (``security.py``).
+* Define an :term:`authorization policy` for mapping users, resources and
+  permissions (``security.py``).
+* Add new :term:`resource` definitions that will be used as the :term:`context`
+  for the wiki pages (``routes.py``).
+* Add an :term:`ACL` to each resource (``routes.py``).
+* Replace the inline checks on the views with :term:`permission` declarations
+  (``views/default.py``).
 
-.. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 15-21
-   :linenos:
-   :language: python
 
-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
-``groupfinder`` function in the current directory's ``security.py`` file.  We
-haven't added that module yet, but we're about to.
+Add user principals
+-------------------
 
-We'll also change ``__init__.py``, adding a call to
-:meth:`pyramid.config.Configurator.add_view` that points at our ``login``
-:term:`view callable`.  This is also known as a :term:`forbidden view`:
+A :term:`principal` is a level of abstraction on top of the raw :term:`userid`
+that describes the user in terms of its capabilities, roles, or other
+identifiers that are easier to generalize. The permissions are then written
+against the principals without focusing on the exact user involved.
 
-.. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 25,41-43
-   :linenos:
-   :language: python
-
-A forbidden view configures our newly created login view to show up when
-:app:`Pyramid` detects that a view invocation can not be authorized.
+:app:`Pyramid` defines two builtin principals used in every application:
+:attr:`pyramid.security.Everyone` and :attr:`pyramid.security.Authenticated`.
+On top of these we have already mentioned the required principals for this
+application in the original design. The user has two possible roles: ``editor``
+or ``basic``. These will be prefixed by the string ``role:`` to avoid clashing
+with any other types of principals.
 
-A ``logout`` :term:`view callable` will allow users to log out later:
+Open the file ``tutorial/security.py`` and edit it as follows:
 
-.. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 26,34
+.. literalinclude:: src/authorization/tutorial/security.py
    :linenos:
+   :emphasize-lines: 3-6,17-24
    :language: python
 
-We'll also add ``permission`` arguments with the value ``edit`` to the
-``edit_page`` and ``add_page`` views.  This indicates that the view
-callables which these views reference cannot be invoked without the
-authenticated user possessing the ``edit`` permission with respect to the
-current context.
+Only the highlighted lines need to be added.
 
-.. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 37-40
-   :linenos:
-   :language: python
+Note that the role comes from the ``User`` object. We also add the ``user.id``
+as a principal for when we want to allow that exact user to edit pages which
+they have created.
 
-Adding these ``permission`` arguments causes Pyramid to make 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
-~~~~~~~~~~~~~~~~~~~~
+Add the authorization policy
+----------------------------
 
-When we're done configuring a root factory, adding an authorization policy,
-and adding views, your application's ``__init__.py`` will look like this:
+We already added the :term:`authorization policy` in the previous chapter
+because :app:`Pyramid` requires one when adding an
+:term:`authentication policy`. However, it was not used anywhere, so we'll
+mention it now.
 
-.. literalinclude:: src/authorization/tutorial/__init__.py
-   :linenos:
+In the file ``tutorial/security.py``, notice the following lines:
+
+.. literalinclude:: src/authorization/tutorial/security.py
+   :lines: 38-40
+   :lineno-match:
+   :emphasize-lines: 2
    :language: python
 
-Adding ``security.py``
+We're using the :class:`pyramid.authorization.ACLAuthorizationPolicy`, which
+will suffice for most applications. It uses the :term:`context` to define the
+mapping between a :term:`principal` and :term:`permission` for the current
+request via the ``__acl__``.
+
+
+Add resources and ACLs
 ----------------------
 
-Add a ``security.py`` module within your package (in the same directory as
-:file:`__init__.py`, :file:`views.py`, etc.) with the following content:
+Resources are the hidden gem of :app:`Pyramid`. You've made it!
 
-.. literalinclude:: src/authorization/tutorial/security.py
+Every URL in a web application represents a :term:`resource` (the "R" in
+Uniform Resource Locator). Often the resource is something in your data model,
+but it could also be an abstraction over many models.
+
+Our wiki has two resources:
+
+#. A ``NewPage``. Represents a potential ``Page`` that does not exist. Any
+   logged-in user, having either role of ``basic`` or ``editor``, can create
+   pages.
+
+#. A ``PageResource``. Represents a ``Page`` that is to be viewed or edited.
+   ``editor`` users, as well as the original creator of the ``Page``, may edit
+   the ``PageResource``. Anyone may view it.
+
+.. note::
+
+   The wiki data model is simple enough that the ``PageResource`` is mostly
+   redundant with our ``models.Page`` SQLAlchemy class. It is completely valid
+   to combine these into one class. However, for this tutorial, they are
+   explicitly separated to make clear the distinction between the parts about
+   which :app:`Pyramid` cares versus application-defined objects.
+
+There are many ways to define these resources, and they can even be grouped
+into collections with a hierarchy. However, we're keeping it simple here!
+
+Open the file ``tutorial/routes.py`` and edit the following lines:
+
+.. literalinclude:: src/authorization/tutorial/routes.py
    :linenos:
+   :emphasize-lines: 1-11,17-
    :language: python
 
-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).
-
-We've given the ``editor`` user membership to the ``group:editors`` by
-mapping him to this group in the ``GROUPS`` data structure (``GROUPS =
-{'editor':['group:editors']}``).  Since the ``groupfinder`` function
-consults the ``GROUPS`` data structure, this will mean that, as a
-result of the ACL attached to the root returned by the root factory,
-and the permission associated with the ``add_page`` and ``edit_page``
-views, the ``editor`` user should be able to add and edit pages.
-
-Adding Login and Logout Views
------------------------------
-
-We'll add a ``login`` view callable which renders a login form and
-processes the post from the login form, checking credentials.
-
-We'll also add a ``logout`` view callable to our application and
-provide a link to it.  This view will clear the credentials of the
-logged in user and redirect back to the front page.
-
-We'll add a different file (for presentation convenience) to add login
-and the logout view callables.  Add a file named ``login.py`` to your
-application (in the same directory as ``views.py``) with the following
-content:
-
-.. literalinclude:: src/authorization/tutorial/login.py
-   :linenos:
+The highlighted lines need to be edited or added.
+
+The ``NewPage`` class has an ``__acl__`` on it that returns a list of mappings
+from :term:`principal` to :term:`permission`. This defines *who* can do *what*
+with that :term:`resource`. In our case we want to allow only those users with
+the principals of either ``role:editor`` or ``role:basic`` to have the
+``create`` permission:
+
+.. literalinclude:: src/authorization/tutorial/routes.py
+   :lines: 30-38
+   :lineno-match:
+   :emphasize-lines: 5-9
    :language: python
 
-Changing Existing Views
------------------------
+The ``NewPage`` is loaded as the :term:`context` of the ``add_page`` route by
+declaring a ``factory`` on the route:
 
-Then we need to change each of our ``view_page``, ``edit_page`` and
-``add_page`` views in ``views.py`` to pass a "logged in" parameter to its
-template.  We'll add something like this to each view body:
+.. literalinclude:: src/authorization/tutorial/routes.py
+   :lines: 18-19
+   :lineno-match:
+   :emphasize-lines: 1-2
+   :language: python
 
-.. ignore-next-block
-.. code-block:: python
-   :linenos:
+The ``PageResource`` class defines the :term:`ACL` for a ``Page``. It uses an
+actual ``Page`` object to determine *who* can do *what* to the page.
 
-   from pyramid.security import authenticated_userid
-   logged_in = authenticated_userid(request)
+.. literalinclude:: src/authorization/tutorial/routes.py
+   :lines: 47-
+   :lineno-match:
+   :emphasize-lines: 5-10
+   :language: python
 
-We'll then change the return value of these views to pass the `resulting
-`logged_in`` value to the template, e.g.:
+The ``PageResource`` is loaded as the :term:`context` of the ``view_page`` and
+``edit_page`` routes by declaring a ``factory`` on the routes:
 
-.. ignore-next-block
-.. code-block:: python
-   :linenos:
+.. literalinclude:: src/authorization/tutorial/routes.py
+   :lines: 17-21
+   :lineno-match:
+   :emphasize-lines: 1,4-5
+   :language: python
 
-   return dict(page = context,
-               content = content,
-               logged_in = logged_in,
-               edit_url = edit_url)
 
-Adding the ``login.pt`` Template
---------------------------------
+Add view permissions
+--------------------
 
-Add a ``login.pt`` template to your templates directory.  It's
-referred to within the login view we just added to ``login.py``.
+At this point we've modified our application to load the ``PageResource``,
+including the actual ``Page`` model in the ``page_factory``. The
+``PageResource`` is now the :term:`context` for all ``view_page`` and
+``edit_page`` views. Similarly the ``NewPage`` will be the context for the
+``add_page`` view.
 
-.. literalinclude:: src/authorization/tutorial/templates/login.pt
-   :language: xml
+Open the file ``tutorial/views/default.py``.
 
-Change ``view.pt`` and ``edit.pt``
-----------------------------------
+First, you can drop a few imports that are no longer necessary:
+
+.. literalinclude:: src/authorization/tutorial/views/default.py
+   :lines: 5-7
+   :lineno-match:
+   :emphasize-lines: 1
+   :language: python
 
-We'll also need to change our ``edit.pt`` and ``view.pt`` templates to
-display a "Logout" link if someone is logged in.  This link will
-invoke the logout view.
+Edit the ``view_page`` view to declare the ``view`` permission, and remove the
+explicit checks within the view:
 
-To do so we'll add this to both templates within the ``<div id="right"
-class="app-welcome align-right">`` div:
+.. literalinclude:: src/authorization/tutorial/views/default.py
+   :lines: 18-23
+   :lineno-match:
+   :emphasize-lines: 1-2,4
+   :language: python
 
-.. code-block:: xml
+The work of loading the page has already been done in the factory, so we can
+just pull the ``page`` object out of the ``PageResource``, loaded as
+``request.context``. Our factory also guarantees we will have a ``Page``, as it
+raises the ``HTTPNotFound`` exception if no ``Page`` exists, again simplifying
+the view logic.
 
-   <span tal:condition="logged_in">
-      <a href="${request.application_url}/logout">Logout</a>
-   </span>
+Edit the ``edit_page`` view to declare the ``edit`` permission:
 
-Seeing Our Changes To ``views.py`` and our Templates
-----------------------------------------------------
+.. literalinclude:: src/authorization/tutorial/views/default.py
+   :lines: 38-42
+   :lineno-match:
+   :emphasize-lines: 1-2,4
+   :language: python
 
-Our ``views.py`` module will look something like this when we're done:
+Edit the ``add_page`` view to declare the ``create`` permission:
 
-.. literalinclude:: src/authorization/tutorial/views.py
-   :linenos:
+.. literalinclude:: src/authorization/tutorial/views/default.py
+   :lines: 52-56
+   :lineno-match:
+   :emphasize-lines: 1-2,4
    :language: python
 
-Our ``edit.pt`` template will look something like this when we're done:
+Note the ``pagename`` here is pulled off of the context instead of
+``request.matchdict``. The factory has done a lot of work for us to hide the
+actual route pattern.
 
-.. literalinclude:: src/authorization/tutorial/templates/edit.pt
-   :language: xml
+The ACLs defined on each :term:`resource` are used by the :term:`authorization
+policy` to determine if any :term:`principal` is allowed to have some
+:term:`permission`. If this check fails (for example, the user is not logged
+in) then an ``HTTPForbidden`` exception will be raised automatically. Thus
+we're able to drop those exceptions and checks from the views themselves.
+Rather we've defined them in terms of operations on a resource.
 
-Our ``view.pt`` template will look something like this when we're done:
+The final ``tutorial/views/default.py`` should look like the following:
 
-.. literalinclude:: src/authorization/tutorial/templates/view.pt
-   :language: xml
+.. literalinclude:: src/authorization/tutorial/views/default.py
+   :linenos:
+   :language: python
 
-Viewing the Application in a Browser
+Viewing the application in a browser
 ------------------------------------
 
-We can finally examine our application in a browser.  The views we'll
-try are as follows:
-
-- Visiting ``http://localhost:6543/`` in a browser invokes the
-  ``view_wiki`` view.  This always redirects to the ``view_page`` view
-  of the FrontPage page object.  It is executable by any user.
-
-- Visiting ``http://localhost:6543/FrontPage`` in a browser invokes
-  the ``view_page`` view of the FrontPage page object.
-
-- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser
-  invokes the edit view for the FrontPage object.  It is executable by
-  only the ``editor`` user.  If a different user (or the anonymous
-  user) invokes it, a login form will be displayed.  Supplying the
-  credentials with the username ``editor``, password ``editor`` will
-  display the edit page form.
-
-- Visiting ``http://localhost:6543/add_page/SomePageName`` in a
-  browser invokes the add view for a page.  It is executable by only
-  the ``editor`` user.  If a different user (or the anonymous user)
-  invokes it, a login form will be displayed.  Supplying the
-  credentials with the username ``editor``, password ``editor`` will
-  display the edit page form.
-
-- After logging in (as a result of hitting an edit or add page
-  and submitting the login form with the ``editor``
-  credentials), we'll see a Logout link in the upper right hand
-  corner.  When we click it, we're logged out, and redirected
-  back to the front page.
+We can finally examine our application in a browser (See
+:ref:`wiki2-start-the-application`).  Launch a browser and visit each of the
+following URLs, checking that the result is as expected:
+
+- http://localhost:6543/ invokes the ``view_wiki`` view.  This always
+  redirects to the ``view_page`` view of the ``FrontPage`` page object.  It
+  is executable by any user.
+
+- http://localhost:6543/FrontPage invokes the ``view_page`` view of the
+  ``FrontPage`` page object. There is a "Login" link in the upper right corner
+  while the user is not authenticated, else it is a "Logout" link when the user
+  is authenticated.
+
+- http://localhost:6543/FrontPage/edit_page invokes the ``edit_page`` view for
+  the ``FrontPage`` page object.  It is executable by only the ``editor`` user.
+  If a different user (or the anonymous user) invokes it, then a login form
+  will be displayed. Supplying the credentials with the username ``editor`` and
+  password ``editor`` will display the edit page form.
+
+- http://localhost:6543/add_page/SomePageName invokes the ``add_page`` view for
+  a page. If the page already exists, then it redirects the user to the
+  ``edit_page`` view for the page object. It is executable by either the
+  ``editor`` or ``basic`` user.  If a different user (or the anonymous user)
+  invokes it, then a login form will be displayed. Supplying the credentials
+  with either the username ``editor`` and password ``editor``, or username
+  ``basic`` and password ``basic``, will display the edit page form.
+
+- http://localhost:6543/SomePageName/edit_page invokes the ``edit_page`` view
+  for an existing page, or generates an error if the page does not exist. It is
+  editable by the ``basic`` user if the page was created by that user in the
+  previous step. If, instead, the page was created by the ``editor`` user, then
+  the login page should be shown for the ``basic`` user.
+
+- After logging in (as a result of hitting an edit or add page and submitting
+  the login form with the ``editor`` credentials), we'll see a "Logout" link in
+  the upper right hand corner.  When we click it, we're logged out, redirected
+  back to the front page, and a "Login" link is shown in the upper right hand
+  corner.
diff --git a/docs/tutorials/wiki2/background.rst b/docs/tutorials/wiki2/background.rst
index 880b5b219..ee7dfe36f 100644
--- a/docs/tutorials/wiki2/background.rst
+++ b/docs/tutorials/wiki2/background.rst
@@ -1,17 +1,22 @@
+.. _wiki2_background:
+
 ==========
 Background
 ==========
 
-This tutorial presents a :app:`Pyramid` application that uses
-technologies which will be familiar to someone with :term:`Pylons`
-experience.  It uses :term:`SQLAlchemy` as a persistence mechanism and
-:term:`url dispatch` to map URLs to code.  It can also be followed by
-people without any prior Python web framework experience.
+This version of the :app:`Pyramid` wiki tutorial presents a
+:app:`Pyramid` application that uses technologies which will be
+familiar to someone with SQL database experience.  It uses
+:term:`SQLAlchemy` as a persistence mechanism and :term:`URL dispatch` to map
+URLs to code.  It can also be followed by people without any prior
+Python web framework experience.
 
 To code along with this tutorial, the developer will need a UNIX
 machine with development tools (Mac OS X with XCode, any Linux or BSD
-variant, etc) *or* he will need a Windows system of any kind.
+variant, etc.) *or* a Windows system of any kind.
+
+.. note::
 
-This tutorial is targeted at :app:`Pyramid` version 1.0.
+  This tutorial runs on both Python 2 and 3 without modification.
 
 Have fun!
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index 6151e0e25..ce67bb9e3 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -1,189 +1,338 @@
+.. _wiki2_basic_layout:
+
 ============
 Basic Layout
 ============
 
-The starter files generated by the ``pyramid_routesalchemy`` 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.
-
-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 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
-
-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
-      :language: py
-
-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:
-
-   .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 14-15
-      :language: py
-
-The first positional ``add_view`` argument ``tutorial.views.my_view`` is the
-dotted name to a *function* we write (generated by the
-``pyramid_routesalchemy`` 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:
-
-   .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 16
-      :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``
----------------------------------
-
-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 ``pyramid_routesalchemy`` scaffold
-put the classes that implement our models.
-
-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
+package.  We use ``__init__.py`` both as a marker, indicating the directory in
+which it's contained is a package, and to contain application configuration
+code.
 
-Next we set up a SQLAlchemy "DBSession" object:
+Open ``tutorial/__init__.py``.  It should already contain the following:
 
-   .. literalinclude:: src/basiclayout/tutorial/models.py
-      :lines: 15-16
-      :linenos:
-      :language: py
+.. literalinclude:: src/basiclayout/tutorial/__init__.py
+  :linenos:
+  :language: py
 
-We also need to create a declarative ``Base`` object to use as a
-base class for our model:
+Let's go over this piece-by-piece. First we need some imports to support later
+code:
 
-   .. literalinclude:: src/basiclayout/tutorial/models.py
-      :lines: 17
-      :language: py
+.. literalinclude:: src/basiclayout/tutorial/__init__.py
+  :end-before: main
+  :linenos:
+  :lineno-match:
+  :language: py
+
+``__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:
+  :lineno-match:
+  :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.  (See :ref:`startup_chapter` for more about ``pserve``.)
+
+Next in ``main``, construct a :term:`Configurator` object:
+
+.. literalinclude:: src/basiclayout/tutorial/__init__.py
+  :lines: 7
+  :lineno-match:
+  :language: py
 
-To give a simple example of a  model class, we define one named ``MyModel``:
+``settings`` is passed to the ``Configurator`` as a keyword argument with the
+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``,
+``sqlalchemy.url``, and so on.
+
+Next include :term:`Jinja2` templating bindings so that we can use renderers
+with the ``.jinja2`` extension within our project.
+
+.. literalinclude:: src/basiclayout/tutorial/__init__.py
+  :lines: 8
+  :lineno-match:
+  :language: py
+
+Next include the the package ``models`` using a dotted Python path. The exact
+setup of the models will be covered later.
+
+.. literalinclude:: src/basiclayout/tutorial/__init__.py
+  :lines: 9
+  :lineno-match:
+  :language: py
+
+Next include the ``routes`` module using a dotted Python path. This module will
+be explained in the next section.
+
+.. literalinclude:: src/basiclayout/tutorial/__init__.py
+  :lines: 10
+  :lineno-match:
+  :language: py
+
+.. note::
+
+   Pyramid's :meth:`pyramid.config.Configurator.include` method is the primary
+   mechanism for extending the configurator and breaking your code into
+   feature-focused modules.
 
-   .. literalinclude:: src/basiclayout/tutorial/models.py
-      :pyobject: MyModel
-      :linenos:
-      :language: py
+``main`` next calls the ``scan`` method of the configurator
+(:meth:`pyramid.config.Configurator.scan`), 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, allowing one of our application URLs to be mapped to some
+code.
 
-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.
+.. literalinclude:: src/basiclayout/tutorial/__init__.py
+  :lines: 11
+  :lineno-match:
+  :language: py
 
-Next we define a function named ``populate`` which adds a single
-model instance into our SQL storage and commits a transaction:
+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/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.
+.. literalinclude:: src/basiclayout/tutorial/__init__.py
+  :lines: 12
+  :lineno-match:
+  :language: py
+
+
+Route declarations
+------------------
+
+Open the ``tutorials/routes.py`` file. It should already contain the following:
+
+.. literalinclude:: src/basiclayout/tutorial/routes.py
+  :linenos:
+  :language: py
+
+On line 2, we call :meth:`pyramid.config.Configurator.add_static_view` with
+three arguments: ``static`` (the name), ``static`` (the path), and
+``cache_max_age`` (a keyword argument).
+
+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.
+
+On line 3, the module registers 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 a ``pattern`` equaling ``/``, it is the
+route that will be matched when the URL ``/`` is visited, e.g.,
+``http://localhost:6543/``.
+
+
+View declarations via the ``views`` package
+-------------------------------------------
+
+The main function of a web framework is mapping each URL pattern to code (a
+:term:`view callable`) that is executed when the requested URL matches the
+corresponding :term:`route`. Our application uses the
+:meth:`pyramid.view.view_config` decorator to perform this mapping.
+
+Open ``tutorial/views/default.py`` in the ``views`` package.  It should already
+contain the following:
 
-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/views/default.py
+  :linenos:
+  :language: py
 
-   .. literalinclude:: src/basiclayout/tutorial/models.py
-      :pyobject: initialize_sql
-      :linenos:
-      :language: py
+The important part here is that the ``@view_config`` decorator associates the
+function it decorates (``my_view``) with a :term:`view configuration`,
+consisting of:
 
-Here is the complete source for ``models.py``:
+   * a ``route_name`` (``home``)
+   * a ``renderer``, which is a template from the ``templates`` subdirectory of
+     the package.
 
-   .. literalinclude:: src/basiclayout/tutorial/models.py
-      :linenos:
-      :language: py
+When the pattern associated with the ``home`` view is matched during a request,
+``my_view()`` will be executed.  ``my_view()`` returns a dictionary; the
+renderer will use the ``templates/mytemplate.jinja2`` template to create a
+response based on the values in the dictionary.
 
+Note that ``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 ``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`.
+
+The sample ``my_view()`` created by the scaffold uses a ``try:`` and
+``except:`` clause to detect if there is a problem accessing the project
+database and provide an alternate error response.  That response will include
+the text shown at the end of the file, which will be displayed in the browser
+to inform the user about possible actions to take to solve the problem.
+
+
+Content models with the ``models`` package
+------------------------------------------
+
+In an SQLAlchemy-based application, a *model* object is an object composed by
+querying the SQL database. The ``models`` package is where the ``alchemy``
+scaffold put the classes that implement our models.
+
+First, open ``tutorial/models/meta.py``, which should already contain the
+following:
+
+.. literalinclude:: src/basiclayout/tutorial/models/meta.py
+  :linenos:
+  :language: py
+
+``meta.py`` contains imports and support code for defining the models. We
+create a dictionary ``NAMING_CONVENTION`` as well for consistent naming of
+support objects like indices and constraints.
+
+.. literalinclude:: src/basiclayout/tutorial/models/meta.py
+  :end-before: metadata
+  :linenos:
+  :language: py
+
+Next we create a ``metadata`` object from the class
+:class:`sqlalchemy.schema.MetaData`, using ``NAMING_CONVENTION`` as the value
+for the ``naming_convention`` argument.
+
+A ``MetaData`` object represents the table and other schema definitions for a
+single database. We also need to create a declarative ``Base`` object to use as
+a base class for our models. Our models will inherit from this ``Base``, which
+will attach the tables to the ``metadata`` we created, and define our
+application's database schema.
+
+.. literalinclude:: src/basiclayout/tutorial/models/meta.py
+  :lines: 15-16
+  :lineno-match:
+  :linenos:
+  :language: py
+
+Next open ``tutorial/models/mymodel.py``, which should already contain the
+following:
+
+.. literalinclude:: src/basiclayout/tutorial/models/mymodel.py
+  :linenos:
+  :language: py
+
+Notice we've defined the ``models`` as a package to make it straightforward for
+defining models in separate modules. To give a simple example of a model class,
+we have defined one named ``MyModel`` in ``mymodel.py``:
+
+.. literalinclude:: src/basiclayout/tutorial/models/mymodel.py
+  :pyobject: MyModel
+  :lineno-match:
+  :linenos:
+  :language: py
+
+Our example model does not require an ``__init__`` method because SQLAlchemy
+supplies for us a default constructor, if one is not already present, which
+accepts keyword arguments of the same name as that of the mapped attributes.
+
+.. note:: Example usage of MyModel:
+
+   .. code-block:: python
+
+       johnny = MyModel(name="John Doe", value=10)
+
+The ``MyModel`` class has a ``__tablename__`` attribute.  This informs
+SQLAlchemy which table to use to store the data representing instances of this
+class.
+
+Finally, open ``tutorial/models/__init__.py``, which should already
+contain the following:
+
+.. literalinclude:: src/basiclayout/tutorial/models/__init__.py
+  :linenos:
+  :language: py
+
+Our ``models/__init__.py`` module defines the primary API we will use for
+configuring the database connections within our application, and it contains
+several functions we will cover below.
+
+As we mentioned above, the purpose of the ``models.meta.metadata`` object is to
+describe the schema of the database. This is done by defining models that
+inherit from the ``Base`` object attached to that ``metadata`` object. In
+Python, code is only executed if it is imported, and so to attach the
+``models`` table defined in ``mymodel.py`` to the ``metadata``, we must import
+it. If we skip this step, then later, when we run
+:meth:`sqlalchemy.schema.MetaData.create_all`, the table will not be created
+because the ``metadata`` object does not know about it!
+
+Another important reason to import all of the models is that, when defining
+relationships between models, they must all exist in order for SQLAlchemy to
+find and build those internal mappings. This is why, after importing all the
+models, we explicitly execute the function
+:func:`sqlalchemy.orm.configure_mappers`, once we are sure all the models have
+been defined and before we start creating connections.
+
+Next we define several functions for connecting to our database. The first and
+lowest level is the ``get_engine`` function. This creates an :term:`SQLAlchemy`
+database engine using :func:`sqlalchemy.engine_from_config` from the
+``sqlalchemy.``-prefixed settings in the ``development.ini`` file's
+``[app:main]`` section. This setting is a URI (something like ``sqlite://``).
+
+.. literalinclude:: src/basiclayout/tutorial/models/__init__.py
+  :pyobject: get_engine
+  :lineno-match:
+  :linenos:
+  :language: py
+
+The function ``get_session_factory`` accepts an :term:`SQLAlchemy` database
+engine, and creates a ``session_factory`` from the :term:`SQLAlchemy` class
+:class:`sqlalchemy.orm.session.sessionmaker`. This ``session_factory`` is then
+used for creating sessions bound to the database engine.
+
+.. literalinclude:: src/basiclayout/tutorial/models/__init__.py
+  :pyobject: get_session_factory
+  :lineno-match:
+  :linenos:
+  :language: py
+
+The function ``get_tm_session`` registers a database session with a transaction
+manager, and returns a ``dbsession`` object. With the transaction manager, our
+application will automatically issue a transaction commit after every request,
+unless an exception is raised, in which case the transaction will be aborted.
+
+.. literalinclude:: src/basiclayout/tutorial/models/__init__.py
+  :pyobject: get_tm_session
+  :lineno-match:
+  :linenos:
+  :language: py
+
+Finally, we define an ``includeme`` function, which is a hook for use with
+:meth:`pyramid.config.Configurator.include` to activate code in a Pyramid
+application add-on. It is the code that is executed above when we ran
+``config.include('.models')`` in our application's ``main`` function. This
+function will take the settings from the application, create an engine, and
+define a ``request.dbsession`` property, which we can use to do work on behalf
+of an incoming request to our application.
+
+.. literalinclude:: src/basiclayout/tutorial/models/__init__.py
+  :pyobject: includeme
+  :lineno-match:
+  :linenos:
+  :language: py
+
+That's about all there is to it regarding models, views, and initialization
+code in our stock application.
+
+The ``Index`` import and the ``Index`` object creation in ``mymodel.py`` is
+not required for this tutorial, and will be removed in the next step.
diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index 7aa2214fc..6520613ea 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -1,95 +1,263 @@
+.. _wiki2_defining_the_domain_model:
+
 =========================
 Defining the Domain Model
 =========================
 
-The first change we'll make to our stock paster-generated application will be
-to define a :term:`domain model` constructor representing a wiki page.  We'll
-do this inside our ``models.py`` file.
+The first change we'll make to our stock ``pcreate``-generated application will
+be to define a wiki page :term:`domain model`.
+
+.. note::
 
-The source code for this tutorial stage can be browsed at
-`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/models/
-<http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/models/>`_.
+  There is nothing special about the filename ``user.py`` or ``page.py`` except
+  that they are Python modules.  A project may have many models throughout its
+  codebase in arbitrarily named modules.  Modules implementing models often
+  have ``model`` in their names or they may live in a Python subpackage of
+  your application package named ``models`` (as we've done in this tutorial),
+  but this is only a convention and not a requirement.
 
-Making Edits to ``models.py``
------------------------------
 
-.. note::
+Declaring dependencies in our ``setup.py`` file
+===============================================
 
-  There is nothing automagically special about the filename
-  ``models.py``.  A project may have many models throughout its
-  codebase in arbitrarily-named files.  Files implementing models
-  often have ``model`` in their filenames (or they may live in a
-  Python subpackage of your application package named ``models``) ,
-  but this is only by convention.
+The models code in our application will depend on a package which is not a
+dependency of the original "tutorial" application.  The original "tutorial"
+application was generated by the ``pcreate`` command; it doesn't know about our
+custom application requirements.
 
-The first thing we want to do is remove the stock ``MyModel`` class from the
-generated ``models.py`` file.  The ``MyModel`` class is only a sample and
-we're not going to use it.
+We need to add a dependency, the ``bcrypt`` package, to our ``tutorial``
+package's ``setup.py`` file by assigning this dependency to the ``requires``
+parameter in the ``setup()`` function.
 
-Next, we'll remove the :class:`sqlalchemy.Unicode` import and replace it
-with :class:`sqlalchemy.Text`.
+Open ``tutorial/setup.py`` and edit it to look like the following:
 
-.. literalinclude:: src/models/tutorial/models.py
-   :lines: 5
+.. literalinclude:: src/models/setup.py
+   :linenos:
+   :emphasize-lines: 12
+   :language: python
+
+Only the highlighted line needs to be added.
+
+
+Running ``pip install -e .``
+============================
+
+Since a new software dependency was added, you will need to run ``pip install
+-e .`` again inside the root of the ``tutorial`` package to obtain and register
+the newly added dependency distribution.
+
+Make sure your current working directory is the root of the project (the
+directory in which ``setup.py`` lives) and execute the following command.
+
+On UNIX:
+
+.. code-block:: bash
+
+   $ cd tutorial
+   $ $VENV/bin/pip install -e .
+
+On Windows:
+
+.. code-block:: doscon
+
+   c:\pyramidtut> cd tutorial
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e .
+
+Success executing this command will end with a line to the console something
+like this::
+
+   Successfully installed bcrypt-2.0.0 cffi-1.5.2 pycparser-2.14 tutorial-0.0
+
+
+Remove ``mymodel.py``
+---------------------
+
+Let's delete the file ``tutorial/models/mymodel.py``. The ``MyModel`` class is
+only a sample and we're not going to use it.
+
+
+Add ``user.py``
+---------------
+
+Create a new file ``tutorial/models/user.py`` with the following contents:
+
+.. literalinclude:: src/models/tutorial/models/user.py
    :linenos:
    :language: py
 
-Then, we'll add a ``Page`` class.  Because this is a SQLAlchemy
-application, this class should inherit from an instance of
-:class:`sqlalchemy.ext.declarative.declarative_base`.  Declarative
-SQLAlchemy models are easier to use than directly-mapped ones.
+This is a very basic model for a user who can authenticate with our wiki.
+
+We discussed briefly in the previous chapter that our models will inherit from
+an SQLAlchemy :func:`sqlalchemy.ext.declarative.declarative_base`. This will
+attach the model to our schema.
+
+As you can see, our ``User`` class has a class-level attribute
+``__tablename__`` which equals the string ``users``. Our ``User`` class will
+also have class-level attributes named ``id``, ``name``, ``password_hash``,
+and ``role`` (all instances of :class:`sqlalchemy.schema.Column`). These will
+map to columns in the ``users`` table. The ``id`` attribute will be the primary
+key in the table. The ``name`` attribute will be a text column, each value of
+which needs to be unique within the column. The ``password_hash`` is a nullable
+text attribute that will contain a securely hashed password [1]_. Finally, the
+``role`` text attribute will hold the role of the user.
+
+There are two helper methods that will help us later when using the user
+objects. The first is ``set_password`` which will take a raw password and
+transform it using bcrypt_ into an irreversible representation, a process known
+as "hashing". The second method, ``check_password``, will allow us to compare
+the hashed value of the submitted password against the hashed value of the
+password stored in the user's record in the database. If the two hashed values
+match, then the submitted password is valid, and we can authenticate the user.
+
+We hash passwords so that it is impossible to decrypt them and use them to
+authenticate in the application. If we stored passwords foolishly in clear
+text, then anyone with access to the database could retrieve any password to
+authenticate as any user.
+
 
-.. literalinclude:: src/models/tutorial/models.py
-   :pyobject: Page
+Add ``page.py``
+---------------
+
+Create a new file ``tutorial/models/page.py`` with the following contents:
+
+.. literalinclude:: src/models/tutorial/models/page.py
    :linenos:
-   :language: python
+   :language: py
+
+As you can see, our ``Page`` class is very similar to the ``User`` defined
+above, except with attributes focused on storing information about a wiki page,
+including ``id``, ``name``, and ``data``. The only new construct introduced
+here is the ``creator_id`` column, which is a foreign key referencing the
+``users`` table. Foreign keys are very useful at the schema-level, but since we
+want to relate ``User`` objects with ``Page`` objects, we also define a
+``creator`` attribute as an ORM-level mapping between the two tables.
+SQLAlchemy will automatically populate this value using the foreign key
+referencing the user. Since the foreign key has ``nullable=False``, we are
+guaranteed that an instance of ``page`` will have a corresponding
+``page.creator``, which will be a ``User`` instance.
+
+
+Edit ``models/__init__.py``
+---------------------------
+
+Since we are using a package for our models, we also need to update our
+``__init__.py`` file to ensure that the models are attached to the metadata.
 
-As you can see, our ``Page`` class has 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``, ``name`` 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`` function to add a
-FrontPage object to our database at startup time.
-
-.. literalinclude:: src/models/tutorial/models.py
-   :pyobject: initialize_sql
+Open the ``tutorial/models/__init__.py`` file and edit it to look like
+the following:
+
+.. literalinclude:: src/models/tutorial/models/__init__.py
    :linenos:
-   :language: python
+   :language: py
+   :emphasize-lines: 8,9
 
-Here, we're using a slightly different binding syntax.  It is otherwise
-largely the same as the ``initialize_sql`` in the paster-generated
-``models.py``.
+Here we align our imports with the names of the models, ``Page`` and ``User``.
 
-Our ``DBSession`` assignment stays the same as the original generated
-``models.py``.
 
-Looking at the Result of all Our Edits to ``models.py``
--------------------------------------------------------
+Edit ``scripts/initializedb.py``
+--------------------------------
 
-The result of all of our edits to ``models.py`` will end up looking
-something like this:
+We haven't looked at the details of this file yet, but within the ``scripts``
+directory of your ``tutorial`` package is a file named ``initializedb.py``.
+Code in this file is executed whenever we run the ``initialize_tutorial_db``
+command, as we did in the installation step of this tutorial [2]_.
 
-.. literalinclude:: src/models/tutorial/models.py
+Since we've changed our model, we need to make changes to our
+``initializedb.py`` script.  In particular, we'll replace our import of
+``MyModel`` with those of ``User`` and ``Page``. We'll also change the very end
+of the script to create two ``User`` objects (``basic`` and ``editor``) as well
+as a ``Page``, rather than a ``MyModel``, and add them to our ``dbsession``.
+
+Open ``tutorial/scripts/initializedb.py`` and edit it to look like the
+following:
+
+.. literalinclude:: src/models/tutorial/scripts/initializedb.py
    :linenos:
    :language: python
+   :emphasize-lines: 18,44-57
+
+Only the highlighted lines need to be changed.
 
-Viewing the Application in a Browser
-------------------------------------
+
+Installing the project and re-initializing the database
+-------------------------------------------------------
+
+Because our model has changed, and in order to reinitialize the database, we
+need to rerun the ``initialize_tutorial_db`` command to pick up the changes
+we've made to both the models.py file and to the initializedb.py file. See
+:ref:`initialize_db_wiki2` for instructions.
+
+Success will look something like this:
+
+.. code-block:: bash
+
+   2016-04-09 02:49:51,711 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
+   2016-04-09 02:49:51,711 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
+   2016-04-09 02:49:51,712 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
+   2016-04-09 02:49:51,712 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
+   2016-04-09 02:49:51,713 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("pages")
+   2016-04-09 02:49:51,714 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-04-09 02:49:51,714 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("users")
+   2016-04-09 02:49:51,714 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-04-09 02:49:51,715 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
+   CREATE TABLE users (
+           id INTEGER NOT NULL,
+           name TEXT NOT NULL,
+           role TEXT NOT NULL,
+           password_hash TEXT,
+           CONSTRAINT pk_users PRIMARY KEY (id),
+           CONSTRAINT uq_users_name UNIQUE (name)
+   )
+
+
+   2016-04-09 02:49:51,715 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-04-09 02:49:51,716 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-04-09 02:49:51,716 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
+   CREATE TABLE pages (
+           id INTEGER NOT NULL,
+           name TEXT NOT NULL,
+           data INTEGER NOT NULL,
+           creator_id INTEGER NOT NULL,
+           CONSTRAINT pk_pages PRIMARY KEY (id),
+           CONSTRAINT uq_pages_name UNIQUE (name),
+           CONSTRAINT fk_pages_creator_id_users FOREIGN KEY(creator_id) REFERENCES users (id)
+   )
+
+
+   2016-04-09 02:49:51,716 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-04-09 02:49:51,717 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-04-09 02:49:52,256 INFO  [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit)
+   2016-04-09 02:49:52,257 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO users (name, role, password_hash) VALUES (?, ?, ?)
+   2016-04-09 02:49:52,257 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('editor', 'editor', b'$2b$12$APUPJvI/kKxrbQPyQehkR.ggoOM6fFYCZ07SFCkWGltl1wJsKB98y')
+   2016-04-09 02:49:52,258 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO users (name, role, password_hash) VALUES (?, ?, ?)
+   2016-04-09 02:49:52,258 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('basic', 'basic', b'$2b$12$GeFnypuQpZyxZLH.sN0akOrPdZMcQjqVTCim67u6f89lOFH/0ddc6')
+   2016-04-09 02:49:52,259 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO pages (name, data, creator_id) VALUES (?, ?, ?)
+   2016-04-09 02:49:52,259 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('FrontPage', 'This is the front page', 1)
+   2016-04-09 02:49:52,259 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+
+
+View the application in a browser
+---------------------------------
 
 We can't.  At this point, our system is in a "non-runnable" state; we'll need
 to change view-related files in the next chapter to be able to start the
-application successfully.  If you try to start the application, you'll wind
-up with a Python traceback on your console that ends with this exception:
+application successfully.  If you try to start the application (see
+:ref:`wiki2-start-the-application`), you'll wind up with a Python traceback on
+your console that ends with this exception:
 
 .. code-block:: text
 
    ImportError: cannot import name MyModel
 
 This will also happen if you attempt to run the tests.
+
+.. _bcrypt: https://pypi.python.org/pypi/bcrypt
+
+.. [1] We are using the bcrypt_ package from PyPI to hash our passwords
+       securely. There are other one-way hash algorithms for passwords if
+       bcrypt is an issue on your system. Just make sure that it's an
+       algorithm approved for storing passwords versus a generic one-way hash.
+
+.. [2] The command is named ``initialize_tutorial_db`` because of the mapping
+       defined in the ``[console_scripts]`` entry point of our project's
+       ``setup.py`` file.
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index cea376b77..996bff88c 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -1,343 +1,479 @@
+.. _wiki2_defining_views:
+
 ==============
 Defining Views
 ==============
 
-A :term:`view callable` in a :term:`url dispatch` -based :app:`Pyramid`
-application is typically a simple Python function that accepts a single
-parameter named :term:`request`.  A view callable is assumed to return a
-:term:`response` object.
-
-.. note:: A :app:`Pyramid` view can also be defined as callable
-   which accepts *two* arguments: a :term:`context` and a
-   :term:`request`.  You'll see this two-argument pattern used in
-   other :app:`Pyramid` tutorials and applications.  Either calling
-   convention will work in any :app:`Pyramid` application; the
-   calling conventions can be used interchangeably as necessary.  In
-   :term:`url dispatch` based applications, however, the context
-   object is rarely used in the view body itself, so within this
-   tutorial we define views as callables that accept only a request to
-   avoid the visual "noise".  If you do need the ``context`` within a
-   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
-call to :meth:`pyramid.config.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'``.
-
-The source code for this tutorial stage can be browsed at
-`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/views/
-<http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/views/>`_.
-
-Declaring Dependencies in Our ``setup.py`` File
-===============================================
-
-The view code in our application will depend on a package which is not a
-dependency of the original "tutorial" application.  The original "tutorial"
-application was generated by the ``paster create`` command; it doesn't know
-about our custom application requirements.  We need to add a dependency on
-the ``docutils`` package to our ``tutorial`` package's ``setup.py`` file by
-assigning this dependency to the ``install_requires`` parameter in the
-``setup`` function.
-
-Our resulting ``setup.py`` should look like so:
+A :term:`view callable` in a :app:`Pyramid` application is typically a simple
+Python function that accepts a single parameter named :term:`request`. A view
+callable is assumed to return a :term:`response` object.
+
+The request object has a dictionary as an attribute named ``matchdict``. A
+``matchdict`` maps the placeholders in the matching URL ``pattern`` to the
+substrings of the path in the :term:`request` URL. For instance, if a call to
+:meth:`pyramid.config.Configurator.add_route` has the pattern ``/{one}/{two}``,
+and a user visits ``http://example.com/foo/bar``, our pattern would be matched
+against ``/foo/bar`` and the ``matchdict`` would look like ``{'one':'foo',
+'two':'bar'}``.
+
+
+Adding the ``docutils`` dependency
+==================================
+
+Remember in the previous chapter we added a new dependency of the ``bcrypt``
+package. Again, the view code in our application will depend on a package which
+is not a dependency of the original "tutorial" application.
+
+We need to add a dependency on the ``docutils`` package to our ``tutorial``
+package's ``setup.py`` file by assigning this dependency to the ``requires``
+parameter in the ``setup()`` function.
+
+Open ``tutorial/setup.py`` and edit it to look like the following:
 
 .. literalinclude:: src/views/setup.py
    :linenos:
+   :emphasize-lines: 13
    :language: python
 
-.. note:: After these new dependencies are added, you will need to
-   rerun ``python setup.py develop`` inside the root of the
-   ``tutorial`` package to obtain and register the newly added
-   dependency package.
+Only the highlighted line needs to be added.
+
+Again, as we did in the previous chapter, the dependency now needs to be
+installed, so re-run the ``$VENV/bin/pip install -e .`` command.
+
+
+Static assets
+-------------
+
+Our templates name static assets, including CSS and images.  We don't need
+to create these files within our package's ``static`` directory because they
+were provided at the time we created the project.
+
+As an example, the CSS file will be accessed via
+``http://localhost:6543/static/theme.css`` by virtue of the call to the
+``add_static_view`` directive we've made in the ``routes.py`` file. Any number
+and type of static assets can be placed in this directory (or subdirectories)
+and are just referred to by URL or by using the convenience method
+``static_url``, e.g., ``request.static_url('<package>:static/foo.css')`` within
+templates.
+
+
+Adding routes to ``routes.py``
+==============================
+
+This is the `URL Dispatch` tutorial, so let's start by adding some URL patterns
+to our app. Later we'll attach views to handle the URLs.
+
+The ``routes.py`` file contains :meth:`pyramid.config.Configurator.add_route`
+calls which serve to add routes to our application. 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.
 
-Adding View Functions
-=====================
+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 registered.
 
-We'll get rid of our ``my_view`` view function in our ``views.py`` file.
-It's only an example and isn't relevant to our application.
+#. Add a declaration which maps the pattern ``/`` (signifying the root URL) to
+   the route named ``view_wiki``. In the next step, we will map it to our
+   ``view_wiki`` view callable by virtue of the ``@view_config`` decorator
+   attached to the ``view_wiki`` view function, which in turn will be indicated
+   by ``route_name='view_wiki'``.
 
-Then we're going to add four :term:`view callable` functions to our
-``views.py`` module.  One view callable (named ``view_wiki``) will display
-the wiki itself (it will answer on the root URL), another named ``view_page``
-will display an individual page, another named ``add_page`` will allow a page
-to be added, and a final view callable named ``edit_page`` will allow a page
-to be edited.  We'll describe each one briefly and show the resulting
-``views.py`` file afterward.
+#. Add a declaration which maps the pattern ``/{pagename}`` to the route named
+   ``view_page``. This is the regular view for a page. Again, in the next step,
+   we will map it to our ``view_page`` view callable by virtue of the
+   ``@view_config`` decorator attached to the ``view_page`` view function,
+   whin in turn will be indicated by ``route_name='view_page'``.
+
+#. Add a declaration which maps the pattern ``/add_page/{pagename}`` to the
+   route named ``add_page``. This is the add view for a new page. We will map
+   it to our ``add_page`` view callable by virtue of the ``@view_config``
+   decorator attached to the ``add_page`` view function, which in turn will be
+   indicated by ``route_name='add_page'``.
+
+#. Add a declaration which maps the pattern ``/{pagename}/edit_page`` to the
+   route named ``edit_page``. This is the edit view for a page. We will map it
+   to our ``edit_page`` view callable by virtue of the ``@view_config``
+   decorator attached to the ``edit_page`` view function, which in turn will be
+   indicated by ``route_name='edit_page'``.
+
+As a result of our edits, the ``routes.py`` file should look like the
+following:
+
+.. literalinclude:: src/views/tutorial/routes.py
+   :linenos:
+   :emphasize-lines: 3-6
+   :language: python
+
+The highlighted lines are the ones that need to be added or edited.
+
+.. warning::
+
+   The order of the routes is important! If you placed
+   ``/{pagename}/edit_page`` *before* ``/add_page/{pagename}``, then we would
+   never be able to add pages. This is because the first route would always
+   match a request to ``/add_page/edit_page`` whereas we want ``/add_page/..``
+   to have priority. This isn't a huge problem in this particular app because
+   wiki pages are always camel case, but it's important to be aware of this
+   behavior in your own apps.
+
+
+Adding view functions in ``views/default.py``
+=============================================
+
+It's time for a major change.  Open ``tutorial/views/default.py`` and
+edit it to look like the following:
+
+.. literalinclude:: src/views/tutorial/views/default.py
+   :linenos:
+   :language: python
+   :emphasize-lines: 1-9,12-
+
+The highlighted lines need to be added or edited.
+
+We added some imports, and created a regular expression to find "WikiWords".
+
+We got rid of the ``my_view`` view function and its decorator that was added
+when we originally rendered the ``alchemy`` scaffold.  It was only an example
+and isn't relevant to our application.  We also deleted the ``db_err_msg``
+string.
+
+Then we added four :term:`view callable` functions to our ``views/default.py``
+module, as mentioned in the previous step:
+
+* ``view_wiki()`` - Displays the wiki itself. It will answer on the root URL.
+* ``view_page()`` - Displays an individual page.
+* ``edit_page()`` - Allows the user to edit a page.
+* ``add_page()`` - Allows the user to add a page.
+
+We'll describe each one briefly in the following sections.
 
 .. note::
 
-  There is nothing special about the filename ``views.py``.  A project may
-  have many view callables throughout its codebase in arbitrarily-named
-  files.  Files implementing view callables often have ``view`` in their
-  filenames (or may live in a Python subpackage of your application package
-  named ``views``), but this is only by convention.
+  There is nothing special about the filename ``default.py`` exept that it is a
+  Python module. A project may have many view callables throughout its codebase
+  in arbitrarily named modules. Modules implementing view callables often have
+  ``view`` in their name (or may live in a Python subpackage of your
+  application package named ``views``, as in our case), but this is only by
+  convention, not a requirement.
+
 
 The ``view_wiki`` view function
 -------------------------------
 
-The ``view_wiki`` function is the :term:`default view` that will be called
-when a request is made to the root URL of our wiki.  It always redirects to
-a URL which represents the path to our "FrontPage".
+Following is the code for the ``view_wiki`` view function and its decorator:
 
-.. literalinclude:: src/views/tutorial/views.py
-   :pyobject: view_wiki
+.. literalinclude:: src/views/tutorial/views/default.py
+   :lines: 17-20
+   :lineno-match:
    :linenos:
    :language: python
 
-The ``view_wiki`` function returns an instance of the
+``view_wiki()`` is the :term:`default view` that gets called when a request is
+made to the root URL of our wiki.  It always redirects to a URL which
+represents the path to our "FrontPage".
+
+The ``view_wiki`` view callable always redirects to the URL of a Page resource
+named "FrontPage".  To do so, it returns an instance of the
 :class:`pyramid.httpexceptions.HTTPFound` class (instances of which implement
-the WebOb :term:`response` interface), It will use the
-:func:`pyramid.url.route_url` API to construct a URL to the ``FrontPage``
-page (e.g. ``http://localhost:6543/FrontPage``), and will use it as the
-"location" of the HTTPFound response, forming an HTTP redirect.
+the :class:`pyramid.interfaces.IResponse` interface, like
+:class:`pyramid.response.Response`). It uses the
+:meth:`pyramid.request.Request.route_url` API to construct a URL to the
+``FrontPage`` page (i.e., ``http://localhost:6543/FrontPage``), and uses it as
+the "location" of the ``HTTPFound`` response, forming an HTTP redirect.
+
 
 The ``view_page`` view function
 -------------------------------
 
-The ``view_page`` function will be used to show a single page of our
-wiki.  It renders the :term:`ReStructuredText` body of a page (stored as
-the ``data`` attribute of a Page object) as HTML.  Then it substitutes an
-HTML anchor for each *WikiWord* reference in the rendered HTML using a
-compiled regular expression.
+Here is the code for the ``view_page`` view function and its decorator:
 
-.. literalinclude:: src/views/tutorial/views.py
-   :pyobject: view_page
+.. literalinclude:: src/views/tutorial/views/default.py
+   :lines: 22-42
+   :lineno-match:
    :linenos:
    :language: python
 
-The curried function named ``check`` is used as the first argument to
+``view_page()`` is used to display a single page of our wiki.  It renders the
+:term:`reStructuredText` body of a page (stored as the ``data`` attribute of a
+``Page`` model object) as HTML.  Then it substitutes an HTML anchor for each
+*WikiWord* reference in the rendered HTML using a compiled regular expression.
+
+The curried function named ``add_link`` is used as the first argument to
 ``wikiwords.sub``, indicating that it should be called to provide a value for
 each WikiWord match found in the content.  If the wiki already contains a
-page with the matched WikiWord name, the ``check`` function generates a view
+page with the matched WikiWord name, ``add_link()`` generates a view
 link to be used as the substitution value and returns it.  If the wiki does
-not already contain a page with with the matched WikiWord name, the function
+not already contain a page with the matched WikiWord name, ``add_link()``
 generates an "add" link as the substitution value and returns it.
 
 As a result, the ``content`` variable is now a fully formed bit of HTML
 containing various view and add links for WikiWords based on the content of
 our current page object.
 
-We then generate an edit URL (because it's easier to do here than in the
-template), and we return a dictionary with a number of arguments.  The fact
-that this view returns a dictionary (as opposed to a :term:`response` object)
+We then generate an edit URL, because it's easier to do here than in the
+template, and we return a dictionary with a number of arguments.  The fact that
+``view_page()`` returns a dictionary (as opposed to a :term:`response` object)
 is a cue to :app:`Pyramid` that it should 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 ``__init__.py``.
-
-The ``add_page`` view function
-------------------------------
+associated with the view configuration to render a response.  In our case, the
+renderer used will be the ``view.jinja2`` template, as indicated in
+the ``@view_config`` decorator that is applied to ``view_page()``.
 
-The ``add_page`` function will be invoked when a user clicks on a *WikiWord*
-which isn't yet represented as a page in the system.  The ``check`` function
-within the ``view_page`` view generates URLs to this view.  It also acts as a
-handler for the form that is generated when we want to add a page object.
-The ``matchdict`` attribute of the request passed to the ``add_page`` view
-will have the values we need to construct URLs and find model objects.
+If the page does not exist, then we need to handle that by raising a
+:class:`pyramid.httpexceptions.HTTPNotFound` to trigger our 404 handling,
+defined in ``tutorial/views/notfound.py``.
 
-.. literalinclude:: src/views/tutorial/views.py
-   :pyobject: add_page
-   :linenos:
-   :language: python
+.. note::
 
-The ``matchdict`` will have a ``'pagename'`` key that matches the name of
-the page we'd like to add.  If our add view is invoked via,
-e.g. ``http://localhost:6543/add_page/SomeName``, the value for
-``'pagename'`` in the ``matchdict`` will be ``'SomeName'``.
+   Using ``raise`` versus ``return`` with the HTTP exceptions is an important
+   distinction that can commonly mess people up. In
+   ``tutorial/views/notfound.py`` there is an :term:`exception view`
+   registered for handling the ``HTTPNotFound`` exception. Exception views are
+   only triggered for raised exceptions. If the ``HTTPNotFound`` is returned,
+   then it has an internal "stock" template that it will use to render itself
+   as a response. If you aren't seeing your exception view being executed, this
+   is most likely the problem! See :ref:`special_exceptions_in_callables` for
+   more information about exception views.
 
-If the view execution is *not* a result of a form submission (if the
-expression ``'form.submitted' in request.params`` is ``False``), the view
-callable renders a template.  To do so, it generates a "save url" which the
-template uses as the form post URL during rendering.  We're lazy here, so
-we're trying to use the same template (``templates/edit.pt``) for the add
-view as well as the page edit view, so we create a dummy Page object in order
-to satisfy the edit form's desire to have *some* page object exposed as
-``page``, and :app:`Pyramid` will render the template associated with this
-view to a response.
-
-If the view execution *is* a result of a form submission (if the expression
-``'form.submitted' in request.params`` is ``True``), we scrape the page body
-from the form data, create a Page object with this page body and the name
-taken from ``matchdict['pagename']``, and save it into the database using
-``session.add``.  We then redirect back to the ``view_page`` view for the
-newly created page.
 
 The ``edit_page`` view function
 -------------------------------
 
-The ``edit_page`` function will be invoked when a user clicks the "Edit this
-Page" button on the view form.  It renders an edit form but it also acts as
-the handler for the form it renders.  The ``matchdict`` attribute of the
-request passed to the ``edit_page`` view will have a ``'pagename'`` key
-matching the name of the page the user wants to edit.
+Here is the code for the ``edit_page`` view function and its decorator:
 
-.. literalinclude:: src/views/tutorial/views.py
-   :pyobject: edit_page
+.. literalinclude:: src/views/tutorial/views/default.py
+   :lines: 44-56
+   :lineno-match:
    :linenos:
    :language: python
 
-If the view execution is *not* a result of a form submission (if the
-expression ``'form.submitted' in request.params`` is ``False``), the view
-simply renders the edit form, passing the page object and a ``save_url``
-which will be used as the action of the generated form.
+``edit_page()`` is invoked when a user clicks the "Edit this Page" button on
+the view form. It renders an edit form, but it also acts as the handler for the
+form which it renders. The ``matchdict`` attribute of the request passed to the
+``edit_page`` view will have a ``'pagename'`` key matching the name of the page
+that the user wants to edit.
 
-If the view execution *is* a result of a form submission (if the expression
+If the view execution *is* a result of a form submission (i.e., the expression
 ``'form.submitted' in request.params`` is ``True``), the view grabs the
 ``body`` element of the request parameters and sets it as the ``data``
 attribute of the page object.  It then redirects to the ``view_page`` view
 of the wiki page.
 
-Viewing the Result of all Our Edits to ``views.py``
-===================================================
+If the view execution is *not* a result of a form submission (i.e., the
+expression ``'form.submitted' in request.params`` is ``False``), the view
+simply renders the edit form, passing the page object and a ``save_url``
+which will be used as the action of the generated form.
+
+.. note::
+
+   Since our ``request.dbsession`` defined in the previous chapter is
+   registered with the ``pyramid_tm`` transaction manager, any changes we make
+   to objects managed by the that session will be committed automatically. In
+   the event that there was an error (even later, in our template code), the
+   changes would be aborted. This means the view itself does not need to
+   concern itself with commit/rollback logic.
+
+
+The ``add_page`` view function
+------------------------------
 
-The result of all of our edits to ``views.py`` will leave it looking
-like this:
+Here is the code for the ``add_page`` view function and its decorator:
 
-.. literalinclude:: src/views/tutorial/views.py
+.. literalinclude:: src/views/tutorial/views/default.py
+   :lines: 58-
+   :lineno-match:
    :linenos:
    :language: python
 
-Adding Templates
-================
+``add_page()`` is invoked when a user clicks on a *WikiWord* which isn't yet
+represented as a page in the system. The ``add_link`` function within the
+``view_page`` view generates URLs to this view. ``add_page()`` also acts as a
+handler for the form that is generated when we want to add a page object. The
+``matchdict`` attribute of the request passed to the ``add_page()`` view will
+have the values we need to construct URLs and find model objects.
+
+The ``matchdict`` will have a ``'pagename'`` key that matches the name of the
+page we'd like to add. If our add view is invoked via, for example,
+``http://localhost:6543/add_page/SomeName``, the value for ``'pagename'`` in
+the ``matchdict`` will be ``'SomeName'``.
+
+Next a check is performed to determine whether the ``Page`` already exists in
+the database. If it already exists, then the client is redirected to the
+``edit_page`` view, else we continue to the next check.
+
+If the view execution *is* a result of a form submission (i.e., the expression
+``'form.submitted' in request.params`` is ``True``), we grab the page body from
+the form data, create a Page object with this page body and the name taken from
+``matchdict['pagename']``, and save it into the database using
+``request.dbession.add``. Since we have not yet covered authentication, we
+don't have a logged-in user to add as the page's ``creator``. Until we get to
+that point in the tutorial, we'll just assume that all pages are created by the
+``editor`` user. Thus we query for that object, and set it on ``page.creator``.
+Finally, we redirect the client back to the ``view_page`` view for the newly
+created page.
+
+If the view execution is *not* a result of a form submission (i.e., the
+expression ``'form.submitted' in request.params`` is ``False``), the view
+callable renders a template.  To do so, it generates a ``save_url`` which the
+template uses as the form post URL during rendering.  We're lazy here, so
+we're going to use the same template (``templates/edit.jinja2``) for the add
+view as well as the page edit view. To do so we create a dummy ``Page`` object
+in order to satisfy the edit form's desire to have *some* page object
+exposed as ``page``. :app:`Pyramid` will render the template associated
+with this view to a response.
 
-The views we've added all reference a :term:`template`.  Each template is a
-:term:`Chameleon` :term:`ZPT` template.  These templates will live in the
-``templates`` directory of our tutorial package.
 
-The ``view.pt`` Template
-------------------------
+Adding templates
+================
 
-The ``view.pt`` template is used for viewing a single wiki page.  It is used
-by the ``view_page`` view function.  It should have a div that is "structure
-replaced" with the ``content`` value provided by the view.  It should also
-have a link on the rendered page that points at the "edit" URL (the URL which
-invokes the ``edit_page`` view for the page being viewed).
+The ``view_page``, ``add_page`` and ``edit_page`` views that we've added
+reference a :term:`template`.  Each template is a :term:`Jinja2` template.
+These templates will live in the ``templates`` directory of our tutorial
+package.  Jinja2 templates must have a ``.jinja2`` extension to be recognized
+as such.
 
-Once we're done with the ``view.pt`` template, it will look a lot like the
-below:
 
-.. literalinclude:: src/views/tutorial/templates/view.pt
-   :language: xml
+The ``layout.jinja2`` template
+------------------------------
 
-.. note:: The names available for our use in a template are always
-   those that are present in the dictionary returned by the view
-   callable.  But our templates make use of a ``request`` object that
-   none of our tutorial views return in their dictionary.  This value
-   appears as if "by magic".  However, ``request`` is one of several
-   names that are available "by default" in a template when a template
-   renderer is used.  See :ref:`chameleon_template_renderers` for more
-   information about other names that are available by default in a
-   template when a Chameleon template is used as a renderer.
+Update ``tutorial/templates/layout.jinja2`` with the following content, as
+indicated by the emphasized lines:
 
-The ``edit.pt`` Template
-------------------------
+.. literalinclude:: src/views/tutorial/templates/layout.jinja2
+   :linenos:
+   :emphasize-lines: 11,35-36
+   :language: html
 
-The ``edit.pt`` template is used for adding and editing a wiki page.  It is
-used by the ``add_page`` and ``edit_page`` view functions.  It should display
-a page containing a form that POSTs back to the "save_url" argument supplied
-by the view.  The form should have a "body" textarea field (the page data),
-and a submit button that has the name "form.submitted".  The textarea in the
-form should be filled with any existing page data when it is rendered.
+Since we're using a templating engine, we can factor common boilerplate out of
+our page templates into reusable components. One method for doing this is
+template inheritance via blocks.
 
-Once we're done with the ``edit.pt`` template, it will look a lot like
-the below:
+- We have defined two placeholders in the layout template where a child
+  template can override the content. These blocks are named ``subtitle`` (line
+  11) and ``content`` (line 36).
+- Please refer to the Jinja2_ documentation for more information about template
+  inheritance.
 
-.. literalinclude:: src/views/tutorial/templates/edit.pt
-   :language: xml
 
-Static Assets
--------------
+The ``view.jinja2`` template
+----------------------------
 
-Our templates name a single static asset named ``pylons.css``.  We don't need
-to create this file within our package's ``static`` directory because it was
-provided at the time we created the project. This file is a little too long
-to replicate within the body of this guide, however it is available `online
-<http://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki2/src/views/tutorial/static/pylons.css>`_.
+Create ``tutorial/templates/view.jinja2`` and add the following content:
 
-This CSS file will be accessed via
-e.g. ``http://localhost:6543/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 or by using the convenience
-method ``static_url``
-e.g. ``request.static_url('{{package}}:static/foo.css')`` within templates.
+.. literalinclude:: src/views/tutorial/templates/view.jinja2
+   :linenos:
+   :language: html
 
-Mapping Views to URLs in ``__init__.py``
-========================================
+This template is used by ``view_page()`` for displaying a single wiki page.
 
-The ``__init__.py`` file contains
-:meth:`pyramid.config.Configurator.add_view` calls which serve to map
-routes via :term:`url dispatch` to views.  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 begin by extending the ``layout.jinja2`` template defined above, which
+  provides the skeleton of the page (line 1).
+- We override the ``subtitle`` block from the base layout, inserting the page
+  name into the page's title (line 3).
+- We override the ``content`` block from the base layout to insert our markup
+  into the body (lines 5-18).
+- We use a variable that is replaced with the ``content`` value provided by the
+  view (line 6). ``content`` contains HTML, so the ``|safe`` filter is used to
+  prevent escaping it (e.g., changing ">" to "&gt;").
+- We create a link that points at the "edit" URL, which when clicked invokes
+  the ``edit_page`` view for the requested page (line 9).
 
-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 pattern ``/`` (signifying the root URL)
-   to the route named ``view_wiki``.
+The ``edit.jinja2`` template
+----------------------------
 
-#. Add a declaration which maps the pattern ``/{pagename}`` to the route named
-   ``view_page``.  This is the regular view for a page.
+Create ``tutorial/templates/edit.jinja2`` and add the following content:
 
-#. Add a declaration which maps the pattern ``/add_page/{pagename}`` to the
-   route named ``add_page``.  This is the add view for a new page.
+.. literalinclude:: src/views/tutorial/templates/edit.jinja2
+   :linenos:
+   :emphasize-lines: 1,3,12,14,17
+   :language: html
 
-#. Add a declaration which maps the pattern ``/{pagename}/edit_page`` to the
-   route named ``edit_page``.  This is the edit view for a page.
+This template serves two use cases. It is used by ``add_page()`` and
+``edit_page()`` for adding and editing a wiki page.  It displays a page
+containing a form and which provides the following:
 
-After we've defined the routes for our application, we can register views
-to handle the processing and rendering that needs to happen when each route is
-requested.
+- Again, we extend the ``layout.jinja2`` template, which provides the skeleton
+  of the page (line 1).
+- Override the ``subtitle`` block to affect the ``<title>`` tag in the
+  ``head`` of the page (line 3).
+- A 10-row by 60-column ``textarea`` field named ``body`` that is filled with
+  any existing page data when it is rendered (line 14).
+- A submit button that has the name ``form.submitted`` (line 17).
+- The form POSTs back to the ``save_url`` argument supplied by the view (line
+  12). The view will use the ``body`` and ``form.submitted`` values.
 
-#. Add a declaration which maps the ``view_wiki`` route to the view named
-   ``view_wiki`` in our ``views.py`` file.  This is the :term:`default view`
-   for the wiki.
 
-#. Add a declaration which maps the ``view_page`` route to the view named
-   ``view_page`` in our ``views.py`` file.
+The ``404.jinja2`` template
+---------------------------
 
-#. Add a declaration which maps the ``add_page`` route to the view named
-   ``add_page`` in our ``views.py`` file.
+Replace ``tutorial/templates/404.jinja2`` with the following content:
 
-#. Add a declaration which maps the ``edit_page`` route to the view named
-   ``edit_page`` in our ``views.py`` file.
+.. literalinclude:: src/views/tutorial/templates/404.jinja2
+   :linenos:
+   :language: html
 
-As a result of our edits, the ``__init__.py`` file should look
-something like so:
+This template is linked from the ``notfound_view`` defined in
+``tutorial/views/notfound.py`` as shown here:
 
-.. literalinclude:: src/views/tutorial/__init__.py
+.. literalinclude:: src/views/tutorial/views/notfound.py
    :linenos:
+   :emphasize-lines: 6
    :language: python
 
-Viewing the Application in a Browser
+There are several important things to note about this configuration:
+
+- The ``notfound_view`` in the above snippet is called an
+  :term:`exception view`. For more information see
+  :ref:`special_exceptions_in_callables`.
+- The ``notfound_view`` sets the response status to 404. It's possible
+  to affect the response object used by the renderer via
+  :ref:`request_response_attr`.
+- The ``notfound_view`` is registered as an exception view and will be invoked
+  **only** if ``pyramid.httpexceptions.HTTPNotFound`` is raised as an
+  exception. This means it will not be invoked for any responses returned
+  from a view normally. For example, on line 27 of
+  ``tutorial/views/default.py`` the exception is raised which will trigger
+  the view.
+
+Finally, we may delete the ``tutorial/templates/mytemplate.jinja2`` template
+that was provided by the ``alchemy`` scaffold, as we have created our own
+templates for the wiki.
+
+.. note::
+
+   Our templates use a ``request`` object that none of our tutorial
+   views return in their dictionary. ``request`` is one of several names that
+   are available "by default" in a template when a template renderer is used.
+   See :ref:`renderer_system_values` for information about other names that
+   are available by default when a template is used as a renderer.
+
+
+Viewing the application in a browser
 ====================================
 
-We can finally examine our application in a browser.  The views we'll try are
-as follows:
+We can finally examine our application in a browser (See
+:ref:`wiki2-start-the-application`).  Launch a browser and visit
+each of the following URLs, checking that the result is as expected:
+
+- http://localhost:6543/ invokes the ``view_wiki`` view.  This always
+  redirects to the ``view_page`` view of the ``FrontPage`` page object.
 
-- Visiting ``http://localhost:6543`` in a browser invokes the
-  ``view_wiki`` view.  This always redirects to the ``view_page`` view
-  of the FrontPage page object.
+- http://localhost:6543/FrontPage invokes the ``view_page`` view of the
+  ``FrontPage`` page object.
 
-- Visiting ``http://localhost:6543/FrontPage`` in a browser invokes
-  the ``view_page`` view of the front page page object.
+- http://localhost:6543/FrontPage/edit_page invokes the ``edit_page`` view for
+  the ``FrontPage`` page object.
 
-- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser
-  invokes the edit view for the front page object.
+- http://localhost:6543/add_page/SomePageName invokes the ``add_page`` view for
+  a page. If the page already exists, then it redirects the user to the
+  ``edit_page`` view for the page object.
 
-- Visiting ``http://localhost:6543/add_page/SomePageName`` in a
-  browser invokes the add view for a page.
+- http://localhost:6543/SomePageName/edit_page invokes the ``edit_page`` view
+  for an existing page, or generates an error if the page does not exist.
 
-Try generating an error within the body of a view by adding code to
-the top of it that generates an exception (e.g. ``raise
-Exception('Forced Exception')``).  Then visit the error-raising view
-in a browser.  You should see an interactive exception handler in the
-browser which allows you to examine values in a post-mortem mode.
+- To generate an error, visit http://localhost:6543/foobars/edit_page which
+  will generate a ``NoResultFound: No row was found for one()`` error. You'll
+  see an interactive traceback facility provided by
+  :term:`pyramid_debugtoolbar`.
 
+.. _jinja2: http://jinja.pocoo.org/
diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst
new file mode 100644
index 000000000..523a6e6d8
--- /dev/null
+++ b/docs/tutorials/wiki2/design.rst
@@ -0,0 +1,162 @@
+.. _wiki2_design:
+
+======
+Design
+======
+
+Following is a quick overview of the design of our wiki application to help us
+understand the changes that we will be making as we work through the tutorial.
+
+Overall
+=======
+
+We choose to use :term:`reStructuredText` markup in the wiki text. Translation
+from reStructuredText to HTML is provided by the widely used ``docutils``
+Python module.  We will add this module to the dependency list in the project's
+``setup.py`` file.
+
+Models
+======
+
+We'll be using an SQLite database to hold our wiki data, and we'll be using
+:term:`SQLAlchemy` to access the data in this database.
+
+Within the database, we will define two tables:
+
+- The `users` table which will store the `id`, `name`, `password_hash` and
+  `role` of each wiki user.
+- The `pages` table, whose elements will store the wiki pages.
+  There are four columns: `id`, `name`, `data` and `creator_id`.
+
+There is a one-to-many relationship between `users` and `pages` tracking
+the user who created each wiki page defined by the `creator_id` column on the
+`pages` table.
+
+URLs like ``/PageName`` will try to find an element in the `pages` table that
+has a corresponding name.
+
+To add a page to the wiki, a new row is created and the text is stored in
+`data`.
+
+A page named ``FrontPage`` containing the text *This is the front page*, will
+be created when the storage is initialized, and will be used as the wiki home
+page.
+
+Wiki Views
+==========
+
+There will be three views to handle the normal operations of adding, editing,
+and viewing wiki pages, plus one view for the wiki front page. Two templates
+will be used, one for viewing, and one for both adding and editing wiki pages.
+
+As of version 1.5 :app:`Pyramid` no longer ships with templating systems.  In
+this tutorial, we will use :term:`Jinja2`.  Jinja2 is a modern and
+designer-friendly templating language for Python, modeled after Django's
+templates.
+
+Security
+========
+
+We'll eventually be adding security to our application.  To do this, we'll
+be using a very simple role-based security model. We'll assign a single
+role category to each user in our system.
+
+`basic`
+  An authenticated user who can view content and create new pages. A `basic`
+  user may also edit the pages they have created but not pages created by
+  other users.
+
+`editor`
+  An authenticated user who can create and edit any content in the system.
+
+In order to accomplish this we'll need to define an authentication policy
+which can identify users by their :term:`userid` and role. Then we'll
+need to define a page :term:`resource` which contains the appropriate
+:term:`ACL`:
+
++----------+--------------------+----------------+
+| Action   | Principal          | Permission     |
++==========+====================+================+
+| Allow    | Everyone           | view           |
++----------+--------------------+----------------+
+| Allow    | group:basic        | create         |
++----------+--------------------+----------------+
+| Allow    | group:editors      | edit           |
++----------+--------------------+----------------+
+| Allow    | <creator of page>  | edit           |
++----------+--------------------+----------------+
+
+Permission declarations will be added to the views to assert the security
+policies as each request is handled.
+
+On the security side of the application there are two additional views for
+handling login and logout as well as two exception views for handling
+invalid access attempts and unhandled URLs.
+
+Summary
+=======
+
+The URL, actions, template, and permission associated to each view are listed
+in the following table:
+
++----------------------+-----------------------+-------------+----------------+------------+
+| URL                  |  Action               |  View       |  Template      | Permission |
+|                      |                       |             |                |            |
++======================+=======================+=============+================+============+
+| /                    |  Redirect to          |  view_wiki  |                |            |
+|                      |  /FrontPage           |             |                |            |
++----------------------+-----------------------+-------------+----------------+------------+
+| /PageName            |  Display existing     |  view_page  |  view.jinja2   |  view      |
+|                      |  page [2]_            |  [1]_       |                |            |
+|                      |                       |             |                |            |
+|                      |                       |             |                |            |
+|                      |                       |             |                |            |
++----------------------+-----------------------+-------------+----------------+------------+
+| /PageName/edit_page  |  Display edit form    |  edit_page  |  edit.jinja2   |  edit      |
+|                      |  with existing        |             |                |            |
+|                      |  content.             |             |                |            |
+|                      |                       |             |                |            |
+|                      |  If the form was      |             |                |            |
+|                      |  submitted, redirect  |             |                |            |
+|                      |  to /PageName         |             |                |            |
++----------------------+-----------------------+-------------+----------------+------------+
+| /add_page/PageName   |  Create the page      |  add_page   |  edit.jinja2   |  create    |
+|                      |  *PageName* in        |             |                |            |
+|                      |  storage,  display    |             |                |            |
+|                      |  the edit form        |             |                |            |
+|                      |  without content.     |             |                |            |
+|                      |                       |             |                |            |
+|                      |  If the form was      |             |                |            |
+|                      |  submitted,           |             |                |            |
+|                      |  redirect to          |             |                |            |
+|                      |  /PageName            |             |                |            |
++----------------------+-----------------------+-------------+----------------+------------+
+| /login               |  Display login form,  |  login      |  login.jinja2  |            |
+|                      |  Forbidden [3]_       |             |                |            |
+|                      |                       |             |                |            |
+|                      |  If the form was      |             |                |            |
+|                      |  submitted,           |             |                |            |
+|                      |  authenticate.        |             |                |            |
+|                      |                       |             |                |            |
+|                      |  - If authentication  |             |                |            |
+|                      |    succeeds,          |             |                |            |
+|                      |    redirect to the    |             |                |            |
+|                      |    page from which    |             |                |            |
+|                      |    we came.           |             |                |            |
+|                      |                       |             |                |            |
+|                      |  - If authentication  |             |                |            |
+|                      |    fails, display     |             |                |            |
+|                      |    login form with    |             |                |            |
+|                      |    "login failed"     |             |                |            |
+|                      |    message.           |             |                |            |
+|                      |                       |             |                |            |
++----------------------+-----------------------+-------------+----------------+------------+
+| /logout              |  Redirect to          |  logout     |                |            |
+|                      |  /FrontPage           |             |                |            |
++----------------------+-----------------------+-------------+----------------+------------+
+
+.. [1] This is the default view for a Page context when there is no view name.
+.. [2] Pyramid will return a default 404 Not Found page if the page *PageName*
+       does not exist yet.
+.. [3] ``pyramid.exceptions.Forbidden`` is reached when a user tries to invoke
+       a view that is not authorized by the authorization policy.
diff --git a/docs/tutorials/wiki2/distributing.rst b/docs/tutorials/wiki2/distributing.rst
index c80b43337..f264448b0 100644
--- a/docs/tutorials/wiki2/distributing.rst
+++ b/docs/tutorials/wiki2/distributing.rst
@@ -1,42 +1,40 @@
+.. _wiki2_distributing_your_application:
+
 =============================
 Distributing Your Application
 =============================
 
-Once your application works properly, you can create a "tarball" from
-it by using the ``setup.py sdist`` command.  The following commands
-assume your current working directory is the ``tutorial`` package
-we've created and that the parent directory of the ``tutorial``
-package is a virtualenv representing a :app:`Pyramid` environment.
+Once your application works properly, you can create a "tarball" from it by
+using the ``setup.py sdist`` command.  The following commands assume your
+current working directory contains the ``tutorial`` package and the
+``setup.py`` file.
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
-   $ ../bin/python setup.py sdist
+   $ $VENV/bin/python setup.py sdist
 
 On Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   c:\pyramidtut> ..\Scripts\python setup.py sdist
+   c:\pyramidtut> %VENV%\Scripts\python setup.py sdist
 
 The output of such a command will be something like:
 
 .. code-block:: text
 
    running sdist
-   # ... more output ...
+   # .. more output ..
    creating dist
-   tar -cf dist/tutorial-0.1.tar tutorial-0.1
-   gzip -f9 dist/tutorial-0.1.tar
-   removing 'tutorial-0.1' (and everything under it)
-
-Note that this command creates a tarball in the "dist" subdirectory
-named ``tutorial-0.1.tar.gz``.  You can send this file to your friends
-to show them your cool new application.  They should be able to
-install it by pointing the ``easy_install`` command directly at it.
-Or you can upload it to `PyPI <http://pypi.python.org>`_ and share it
-with the rest of the world, where it can be downloaded via
-``easy_install`` remotely like any other package people download from
-PyPI.
-
+   Creating tar archive
+   removing 'tutorial-0.0' (and everything under it)
+
+Note that this command creates a tarball in the "dist" subdirectory named
+``tutorial-0.0.tar.gz``.  You can send this file to your friends to show them
+your cool new application.  They should be able to install it by pointing the
+``easy_install`` command directly at it. Or you can upload it to `PyPI
+<http://pypi.python.org>`_ and share it with the rest of the world, where it
+can be downloaded via ``easy_install`` remotely like any other package people
+download from PyPI.
diff --git a/docs/tutorials/wiki2/index.rst b/docs/tutorials/wiki2/index.rst
index d05d70f3c..18e9f552e 100644
--- a/docs/tutorials/wiki2/index.rst
+++ b/docs/tutorials/wiki2/index.rst
@@ -1,29 +1,29 @@
 .. _bfg_sql_wiki_tutorial:
 
-SQLAlchemy + URL Dispatch Wiki Tutorial
+SQLAlchemy + URL dispatch wiki tutorial
 =======================================
 
-This tutorial introduces a :term:`SQLAlchemy` and :term:`url dispatch` -based
-:app:`Pyramid` application to a developer familiar with Python, and will be
-most familiar to developers who have used the :term:`Pylons` 1.X web
-framework.  When the tutorial is finished, the developer will have created a
-basic Wiki application with authentication.
+This tutorial introduces an :term:`SQLAlchemy` and :term:`URL dispatch`-based
+:app:`Pyramid` application to a developer familiar with Python.  When the
+tutorial is finished, the developer will have created a basic wiki
+application with authentication and authorization.
 
-For cut and paste purposes, the source code for all stages of this
-tutorial can be browsed at
-`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/
-<http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/>`_.
+For cut and paste purposes, the source code for all stages of this tutorial can
+be browsed on GitHub at `docs/tutorials/wiki2/src
+<https://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src>`_,
+which corresponds to the same location if you have Pyramid sources.
 
 .. toctree::
    :maxdepth: 2
 
    background
+   design
    installation
    basiclayout
    definingmodels
    definingviews
+   authentication
    authorization
    tests
    distributing
 
-
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index bd597b5df..f4676345e 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -1,240 +1,521 @@
+.. _wiki2_installation:
+
 ============
 Installation
 ============
 
-This tutorial assumes that Python and virtualenv are already installed
-and working in your system. If you need help setting this up, you should
-refer to the chapters on :ref:`installing_chapter`.
+Before you begin
+----------------
+
+This tutorial assumes that you have already followed the steps in
+:ref:`installing_chapter`, except **do not create a virtual environment or
+install Pyramid**.  Thereby you will satisfy the following requirements.
+
+* A Python interpreter is installed on your operating system.
+* You've satisfied the :ref:`requirements-for-installing-packages`.
+
+
+Create directory to contain the project
+---------------------------------------
+
+We need a workspace for our project files.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+    $ mkdir ~/pyramidtut
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\> mkdir pyramidtut
+
+
+Create and use a virtual Python environment
+-------------------------------------------
+
+Next let's create a virtual environment workspace for our project.  We will use
+the ``VENV`` environment variable instead of the absolute path of the virtual
+environment.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ export VENV=~/pyramidtut
+   $ python3 -m venv $VENV
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\> set VENV=c:\pyramidtut
+
+Each version of Python uses different paths, so you will need to adjust the
+path to the command for your Python version.
+
+Python 2.7:
+
+.. code-block:: doscon
+
+   c:\> c:\Python27\Scripts\virtualenv %VENV%
 
-Preparation
-===========
+Python 3.5:
 
-Please take the following steps to prepare for the tutorial.  The
-steps are slightly different depending on whether you're using UNIX or
-Windows.
+.. code-block:: doscon
 
-Preparation, UNIX
------------------
+   c:\> c:\Python35\Scripts\python -m venv %VENV%
 
-#. Install SQLite3 and its development packages if you don't already
-   have them installed.  Usually this is via your system's package
-   manager.  For example, on a Debian Linux system, do ``sudo apt-get
-   install libsqlite3-dev``.
 
-#. Use your Python's virtualenv to make a workspace:
+Upgrade ``pip`` and ``setuptools`` in the virtual environment
+-------------------------------------------------------------
 
-   .. code-block:: text
+On UNIX
+^^^^^^^
 
-      $ path/to/my/Python-2.6/bin/virtualenv --no-site-packages pyramidtut
+.. code-block:: bash
 
-#. Switch to the ``pyramidtut`` directory:
+    $ $VENV/bin/pip install --upgrade pip setuptools
 
-   .. code-block:: text
+On Windows
+^^^^^^^^^^
 
-      $ cd pyramidtut
+.. code-block:: doscon
 
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct
-   dependencies installed:
+   c:\> %VENV%\Scripts\pip install --upgrade pip setuptools
 
-   .. code-block:: text
 
-      $ bin/easy_install pyramid
+Install Pyramid into the virtual Python environment
+---------------------------------------------------
 
-#. Use ``easy_install`` to install various packages from PyPI.
+On UNIX
+^^^^^^^
 
-   .. code-block:: text
+.. code-block:: bash
 
-      $ bin/easy_install docutils nose coverage zope.sqlalchemy \
-                SQLAlchemy repoze.tm2
+   $ $VENV/bin/pip install pyramid
 
-Preparation, Windows
---------------------
+On Windows
+^^^^^^^^^^
 
-#. Use your Python's virtualenv to make a workspace:
+.. code-block:: doscon
 
-   .. code-block:: text
+   c:\> %VENV%\Scripts\pip install pyramid
 
-      c:\> c:\Python26\Scripts\virtualenv --no-site-packages pyramidtut
 
-#. Switch to the ``pyramidtut`` directory:
+Install SQLite3 and its development packages
+--------------------------------------------
 
-   .. code-block:: text
+If you used a package manager to install your Python or if you compiled
+your Python from source, then you must install SQLite3 and its
+development packages.  If you downloaded your Python as an installer
+from https://www.python.org, then you already have it installed and can skip
+this step.
 
-      c:\> cd pyramidtut
+If you need to install the SQLite3 packages, then, for example, using
+the Debian system and ``apt-get``, the command would be the following:
 
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct
-   dependencies installed:
+.. code-block:: bash
 
-   .. code-block:: text
+   $ sudo apt-get install libsqlite3-dev
 
-      c:\pyramidtut> Scripts\easy_install pyramid
 
-#. Use ``easy_install`` to install various packages from PyPI.
+Change directory to your virtual Python environment
+---------------------------------------------------
 
-   .. code-block:: text
+Change directory to the ``pyramidtut`` directory, which is both your workspace
+and your virtual environment.
 
-      c:\pyramidtut> Scripts\easy_install docutils ^
-               nose coverage zope.sqlalchemy SQLAlchemy repoze.tm2
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ cd pyramidtut
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\> cd pyramidtut
 
 
 .. _sql_making_a_project:
 
-Making a Project
-================
+Making a project
+----------------
 
-Your next step is to create a project.  :app:`Pyramid` supplies a
-variety of scaffolds to generate sample projects.  We will use the
-``pyramid_routesalchemy`` scaffold, which generates an application
+Your next step is to create a project.  For this tutorial we will use
+the :term:`scaffold` named ``alchemy`` which generates an application
 that uses :term:`SQLAlchemy` and :term:`URL dispatch`.
 
-The below instructions assume your current working directory is the
-"virtualenv" named "pyramidtut".
+:app:`Pyramid` supplies a variety of scaffolds to generate sample projects. We
+will use ``pcreate``, a script that comes with Pyramid, to create our project
+using a scaffold.
+
+By passing ``alchemy`` into the ``pcreate`` command, the script creates the
+files needed to use SQLAlchemy. By passing in our application name
+``tutorial``, the script inserts that application name into all the required
+files. For example, ``pcreate`` creates the ``initialize_tutorial_db`` in the
+``pyramidtut/bin`` directory.
 
-On UNIX:
+The below instructions assume your current working directory is "pyramidtut".
 
-.. code-block:: text
+On UNIX
+^^^^^^^
 
-   $ bin/paster create -t pyramid_routesalchemy tutorial
+.. code-block:: bash
 
-On Windows:
+   $ $VENV/bin/pcreate -s alchemy tutorial
 
-.. code-block:: text
+On Windows
+^^^^^^^^^^
 
-   c:\pyramidtut> Scripts\paster create -t pyramid_routesalchemy tutorial
+.. code-block:: doscon
 
-.. note:: If you are using Windows, the ``pyramid_routesalchemy``
-   scaffold may not deal gracefully with installation into a
-   location that contains spaces in the path.  If you experience
-   startup problems, try putting both the virtualenv and the project
-   into directories that do not contain spaces in their paths.
+   c:\pyramidtut> %VENV%\Scripts\pcreate -s alchemy tutorial
 
-Installing the Project in "Development Mode"
-============================================
+.. note:: If you are using Windows, the ``alchemy`` scaffold may not deal
+   gracefully with installation into a location that contains spaces in the
+   path. If you experience startup problems, try putting both the virtual
+   environment and the project into directories that do not contain spaces in
+   their paths.
 
-In order to do development on the project easily, you must "register"
-the project as a development egg in your workspace using the
-``setup.py develop`` command.  In order to do so, cd to the "tutorial"
-directory you created in :ref:`sql_making_a_project`, and run the
-"setup.py develop" command using virtualenv Python interpreter.
 
-On UNIX:
+.. _installing_project_in_dev_mode:
 
-.. code-block:: text
+Installing the project in development mode
+------------------------------------------
+
+In order to do development on the project easily, you must "register" the
+project as a development egg in your workspace using the ``pip install -e .``
+command. In order to do so, change directory to the ``tutorial`` directory that
+you created in :ref:`sql_making_a_project`, and run the ``pip install -e .``
+command using the virtual environment Python interpreter.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
 
    $ cd tutorial
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/pip install -e .
 
-On Windows:
+On Windows
+^^^^^^^^^^
 
-.. code-block:: text
+.. code-block:: doscon
 
    c:\pyramidtut> cd tutorial
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e .
 
-.. _sql_running_tests:
+The console will show ``pip`` checking for packages and installing missing
+packages. Success executing this command will show a line like the following:
 
-Running the Tests
-=================
+.. code-block:: bash
 
-After you've installed the project in development mode, you may run
-the tests for the project.
+   Successfully installed Chameleon-2.24 Mako-1.0.4 MarkupSafe-0.23 \
+   Pygments-2.1.3 SQLAlchemy-1.0.12 pyramid-chameleon-0.3 \
+   pyramid-debugtoolbar-2.4.2 pyramid-mako-1.0.2 pyramid-tm-0.12.1 \
+   transaction-1.4.4 tutorial waitress-0.8.10 zope.sqlalchemy-0.7.6
 
-On UNIX:
 
-.. code-block:: text
+.. _install-testing-requirements:
 
-   $ ../bin/python setup.py test -q
+Install testing requirements
+----------------------------
 
-On Windows:
+In order to run tests, we need to install the testing requirements. This is
+done through our project's ``setup.py`` file, in the ``tests_require`` and
+``extras_require`` stanzas, and by issuing the command below for your
+operating system.
 
-.. code-block:: text
+.. literalinclude:: src/installation/setup.py
+   :language: python
+   :linenos:
+   :lineno-start: 22
+   :lines: 22-26
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+.. literalinclude:: src/installation/setup.py
+   :language: python
+   :linenos:
+   :lineno-start: 45
+   :lines: 45-47
 
-Starting the Application
-========================
+On UNIX
+^^^^^^^
 
-Start the application.
+.. code-block:: bash
+
+   $ $VENV/bin/pip install -e ".[testing]"
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e ".[testing]"
+
+
+.. _sql_running_tests:
+
+Run the tests
+-------------
+
+After you've installed the project in development mode as well as the testing
+requirements, you may run the tests for the project.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test tutorial/tests.py -q
+
+On Windows
+^^^^^^^^^^
 
-On UNIX:
+.. code-block:: doscon
 
-.. code-block:: text
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial\tests.py -q
 
-   $ ../bin/paster serve development.ini --reload
+For a successful test run, you should see output that ends like this:
 
-On Windows:
+.. code-block:: bash
 
-.. code-block:: text
+   ..
+   2 passed in 0.44 seconds
 
-   c:\pyramidtut\tutorial> ..\Scripts\paster serve development.ini --reload
 
-Exposing Test Coverage Information
-==================================
+Expose test coverage information
+--------------------------------
 
-You can run the ``nosetests`` command to see test coverage
-information.  This runs the tests in the same way that ``setup.py
-test`` does but provides additional "coverage" information, exposing
-which lines of your project are "covered" (or not covered) by the
+You can run the ``py.test`` command to see test coverage information. This
+runs the tests in the same way that ``py.test`` does, but provides additional
+"coverage" information, exposing which lines of your project are covered by the
 tests.
 
-To get this functionality working, we'll need to install a couple of
-other packages into our ``virtualenv``: ``nose`` and ``coverage``:
+We've already installed the ``pytest-cov`` package into our virtual
+environment, so we can run the tests with coverage.
 
-On UNIX:
+On UNIX
+^^^^^^^
 
-.. code-block:: text
+.. code-block:: bash
 
-   $ ../bin/easy_install nose coverage
+   $ $VENV/bin/py.test --cov=tutorial --cov-report=term-missing tutorial/tests.py
 
-On Windows:
+On Windows
+^^^^^^^^^^
 
-.. code-block:: text
+.. code-block:: doscon
 
-   c:\pyramidtut\tutorial> ..\Scripts\easy_install nose coverage
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
+       --cov-report=term-missing tutorial\tests.py
 
-Once ``nose`` and ``coverage`` are installed, we can actually run the
-coverage tests.
+If successful, you will see output something like this:
 
-On UNIX:
+.. code-block:: bash
 
-.. code-block:: text
+   ======================== test session starts ========================
+   platform Python 3.5.1, pytest-2.9.1, py-1.4.31, pluggy-0.3.1
+   rootdir: /Users/stevepiercy/projects/pyramidtut/tutorial, inifile:
+   plugins: cov-2.2.1
+   collected 2 items
 
-   $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
+   tutorial/tests.py ..
+   ------------------ coverage: platform Python 3.5.1 ------------------
+   Name                               Stmts   Miss  Cover   Missing
+   ----------------------------------------------------------------
+   tutorial/__init__.py                   8      6    25%   7-12
+   tutorial/models/__init__.py           22      0   100%
+   tutorial/models/meta.py                5      0   100%
+   tutorial/models/mymodel.py             8      0   100%
+   tutorial/routes.py                     3      3     0%   1-3
+   tutorial/scripts/__init__.py           0      0   100%
+   tutorial/scripts/initializedb.py      26     26     0%   1-45
+   tutorial/tests.py                     39      0   100%
+   tutorial/views/__init__.py             0      0   100%
+   tutorial/views/default.py             12      0   100%
+   tutorial/views/notfound.py             4      4     0%   1-7
+   ----------------------------------------------------------------
+   TOTAL                                127     39    69%
 
-On Windows:
+   ===================== 2 passed in 0.57 seconds ======================
 
-.. code-block:: text
+Our package doesn't quite have 100% test coverage.
 
-   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.
+.. _initialize_db_wiki2:
 
-Visit the Application in a Browser
-==================================
+Initializing the database
+-------------------------
 
-In a browser, visit ``http://localhost:6543/``.  You will see the
-generated application's default page.
+We need to use the ``initialize_tutorial_db`` :term:`console script` to
+initialize our database.
 
-Decisions the ``pyramid_routesalchemy`` Scaffold Has Made For You
-=================================================================
+.. note::
+
+   The ``initialize_tutorial_db`` command does not perform a migration, but
+   rather it simply creates missing tables and adds some dummy data. If you
+   already have a database, you should delete it before running
+   ``initialize_tutorial_db`` again.
+
+.. note::
+
+   The ``initialize_tutorial_db`` command is not performing a migration but
+   rather simply creating missing tables and adding some dummy data. If you
+   already have a database, you should delete it before running
+   ``initialize_tutorial_db`` again.
+
+Type the following command, making sure you are still in the ``tutorial``
+directory (the directory with a ``development.ini`` in it):
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ $VENV/bin/initialize_tutorial_db development.ini
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\pyramidtut\tutorial> %VENV%\Scripts\initialize_tutorial_db development.ini
+
+The output to your console should be something like this:
+
+.. code-block:: bash
+
+   2016-04-09 00:53:37,801 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
+   2016-04-09 00:53:37,801 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
+   2016-04-09 00:53:37,802 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
+   2016-04-09 00:53:37,802 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
+   2016-04-09 00:53:37,802 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("models")
+   2016-04-09 00:53:37,803 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-04-09 00:53:37,803 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
+   CREATE TABLE models (
+           id INTEGER NOT NULL,
+           name TEXT,
+           value INTEGER,
+           CONSTRAINT pk_models PRIMARY KEY (id)
+   )
+
+
+   2016-04-09 00:53:37,803 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-04-09 00:53:37,804 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-04-09 00:53:37,805 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] CREATE UNIQUE INDEX my_index ON models (name)
+   2016-04-09 00:53:37,805 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-04-09 00:53:37,806 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-04-09 00:53:37,807 INFO  [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit)
+   2016-04-09 00:53:37,808 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO models (name, value) VALUES (?, ?)
+   2016-04-09 00:53:37,808 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('one', 1)
+   2016-04-09 00:53:37,809 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+
+Success!  You should now have a ``tutorial.sqlite`` file in your current
+working directory. This is an SQLite database with a single table defined in it
+(``models``).
+
+.. _wiki2-start-the-application:
+
+Start the application
+---------------------
+
+Start the application.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
 
-Creating a project using the ``pyramid_routesalchemy`` scaffold makes
-the following assumptions:
+   $ $VENV/bin/pserve development.ini --reload
 
-- you are willing to use :term:`SQLAlchemy` as a database access tool
+On Windows
+^^^^^^^^^^
 
-- you are willing to use :term:`url dispatch` to map URLs to code.
+.. code-block:: doscon
 
-- you want to configure your application *imperatively* (no
-  :term:`declarative configuration` such as ZCML).
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload
 
 .. note::
 
-   :app:`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.
+   Your OS firewall, if any, may pop up a dialog asking for authorization
+   to allow python to accept incoming network connections.
+
+If successful, you will see something like this on your console::
+
+   Starting subprocess with file monitor
+   Starting server in PID 82349.
+   serving on http://127.0.0.1:6543
+
+This means the server is ready to accept requests.
+
+
+Visit the application in a browser
+----------------------------------
+
+In a browser, visit http://localhost:6543/.  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
+:ref:`debug_toolbar`.  It allows you to get information about your
+application while you develop.
+
+
+Decisions the ``alchemy`` scaffold has made for you
+---------------------------------------------------
+
+Creating a project using the ``alchemy`` scaffold makes 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 use zope.sqlalchemy_, pyramid_tm_, and the transaction_ packages
+  to scope sessions to requests.
+
+- You want to use pyramid_jinja2_ to render your templates. Different
+  templating engines can be used, but we had to choose one to make this
+  tutorial. See :ref:`available_template_system_bindings` for some options.
+
+.. note::
+
+   :app:`Pyramid` supports any persistent storage mechanism (e.g., object
+   database or filesystem files). 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.
+
+.. _pyramid_jinja2:
+   http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/
+
+.. _pyramid_tm:
+   http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/
+
+.. _zope.sqlalchemy:
+   https://pypi.python.org/pypi/zope.sqlalchemy
+
+.. _transaction:
+   http://zodb.readthedocs.org/en/latest/transactions.html
+
+.. _pyramid_jinja2:
+   http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/
+
+.. _pyramid_tm:
+   http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/
+
+.. _zope.sqlalchemy:
+   https://pypi.python.org/pypi/zope.sqlalchemy
 
+.. _transaction:
+   http://zodb.readthedocs.org/en/latest/transactions.html
diff --git a/docs/tutorials/wiki2/src/authentication/CHANGES.txt b/docs/tutorials/wiki2/src/authentication/CHANGES.txt
new file mode 100644
index 000000000..35a34f332
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/CHANGES.txt
@@ -0,0 +1,4 @@
+0.0
+---
+
+-  Initial version
diff --git a/docs/tutorials/wiki2/src/authentication/MANIFEST.in b/docs/tutorials/wiki2/src/authentication/MANIFEST.in
new file mode 100644
index 000000000..42cd299b5
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/MANIFEST.in
@@ -0,0 +1,2 @@
+include *.txt *.ini *.cfg *.rst
+recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.jinja2 *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/tutorials/wiki2/src/authentication/README.txt b/docs/tutorials/wiki2/src/authentication/README.txt
new file mode 100644
index 000000000..5b0101e5f
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/README.txt
@@ -0,0 +1,14 @@
+tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/initialize_tutorial_db development.ini
+
+- $VENV/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/authentication/development.ini b/docs/tutorials/wiki2/src/authentication/development.ini
new file mode 100644
index 000000000..4a6c9325c
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/development.ini
@@ -0,0 +1,73 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_tm
+
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
+
+auth.secret = seekrit
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
+[server:main]
+use = egg:waitress#main
+host = 127.0.0.1
+port = 6543
+
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial, sqlalchemy
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
+[logger_sqlalchemy]
+level = INFO
+handlers =
+qualname = sqlalchemy.engine
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARN" logs neither.  (Recommended for production systems.)
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/authentication/production.ini b/docs/tutorials/wiki2/src/authentication/production.ini
new file mode 100644
index 000000000..a13a0ca19
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/production.ini
@@ -0,0 +1,62 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
+
+auth.secret = real-seekrit
+
+[server:main]
+use = egg:waitress#main
+host = 0.0.0.0
+port = 6543
+
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial, sqlalchemy
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_tutorial]
+level = WARN
+handlers =
+qualname = tutorial
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARN" logs neither.  (Recommended for production systems.)
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/authentication/setup.py b/docs/tutorials/wiki2/src/authentication/setup.py
new file mode 100644
index 000000000..def3ce1f6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/setup.py
@@ -0,0 +1,57 @@
+import os
+
+from setuptools import setup, find_packages
+
+here = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
+
+requires = [
+    'bcrypt',
+    'docutils',
+    'pyramid',
+    'pyramid_jinja2',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
+    'SQLAlchemy',
+    'transaction',
+    'zope.sqlalchemy',
+    'waitress',
+    ]
+
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
+
+setup(name='tutorial',
+      version='0.0',
+      description='tutorial',
+      long_description=README + '\n\n' + CHANGES,
+      classifiers=[
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
+      author='',
+      author_email='',
+      url='',
+      keywords='web wsgi bfg pylons pyramid',
+      packages=find_packages(),
+      include_package_data=True,
+      zip_safe=False,
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
+      [paste.app_factory]
+      main = tutorial:main
+      [console_scripts]
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
+      """,
+      )
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/__init__.py b/docs/tutorials/wiki2/src/authentication/tutorial/__init__.py
new file mode 100644
index 000000000..f5c033b8b
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/__init__.py
@@ -0,0 +1,13 @@
+from pyramid.config import Configurator
+
+
+def main(global_config, **settings):
+    """ This function returns a Pyramid WSGI application.
+    """
+    config = Configurator(settings=settings)
+    config.include('pyramid_jinja2')
+    config.include('.models')
+    config.include('.routes')
+    config.include('.security')
+    config.scan()
+    return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/authentication/tutorial/models/__init__.py
new file mode 100644
index 000000000..a8871f6f5
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/models/__init__.py
@@ -0,0 +1,74 @@
+from sqlalchemy import engine_from_config
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import configure_mappers
+import zope.sqlalchemy
+
+# import or define all models here to ensure they are attached to the
+# Base.metadata prior to any initialization routines
+from .page import Page # flake8: noqa
+from .user import User # flake8: noqa
+
+# run configure_mappers after defining all of the models to ensure
+# all relationships can be setup
+configure_mappers()
+
+
+def get_engine(settings, prefix='sqlalchemy.'):
+    return engine_from_config(settings, prefix)
+
+
+def get_session_factory(engine):
+    factory = sessionmaker()
+    factory.configure(bind=engine)
+    return factory
+
+
+def get_tm_session(session_factory, transaction_manager):
+    """
+    Get a ``sqlalchemy.orm.Session`` instance backed by a transaction.
+
+    This function will hook the session to the transaction manager which
+    will take care of committing any changes.
+
+    - When using pyramid_tm it will automatically be committed or aborted
+      depending on whether an exception is raised.
+
+    - When using scripts you should wrap the session in a manager yourself.
+      For example::
+
+          import transaction
+
+          engine = get_engine(settings)
+          session_factory = get_session_factory(engine)
+          with transaction.manager:
+              dbsession = get_tm_session(session_factory, transaction.manager)
+
+    """
+    dbsession = session_factory()
+    zope.sqlalchemy.register(
+        dbsession, transaction_manager=transaction_manager)
+    return dbsession
+
+
+def includeme(config):
+    """
+    Initialize the model for a Pyramid app.
+
+    Activate this setup using ``config.include('tutorial.models')``.
+
+    """
+    settings = config.get_settings()
+
+    # use pyramid_tm to hook the transaction lifecycle to the request
+    config.include('pyramid_tm')
+
+    session_factory = get_session_factory(get_engine(settings))
+    config.registry['dbsession_factory'] = session_factory
+
+    # make request.dbsession available for use in Pyramid
+    config.add_request_method(
+        # r.tm is the transaction manager used by pyramid_tm
+        lambda r: get_tm_session(session_factory, r.tm),
+        'dbsession',
+        reify=True
+    )
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/models/meta.py b/docs/tutorials/wiki2/src/authentication/tutorial/models/meta.py
new file mode 100644
index 000000000..fc3e8f1dd
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/models/meta.py
@@ -0,0 +1,16 @@
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.schema import MetaData
+
+# Recommended naming convention used by Alembic, as various different database
+# providers will autogenerate vastly different names making migrations more
+# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+NAMING_CONVENTION = {
+    "ix": 'ix_%(column_0_label)s',
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s"
+}
+
+metadata = MetaData(naming_convention=NAMING_CONVENTION)
+Base = declarative_base(metadata=metadata)
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/models/page.py b/docs/tutorials/wiki2/src/authentication/tutorial/models/page.py
new file mode 100644
index 000000000..4dd5b5721
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/models/page.py
@@ -0,0 +1,20 @@
+from sqlalchemy import (
+    Column,
+    ForeignKey,
+    Integer,
+    Text,
+)
+from sqlalchemy.orm import relationship
+
+from .meta import Base
+
+
+class Page(Base):
+    """ The SQLAlchemy declarative model class for a Page object. """
+    __tablename__ = 'pages'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text, nullable=False, unique=True)
+    data = Column(Integer, nullable=False)
+
+    creator_id = Column(ForeignKey('users.id'), nullable=False)
+    creator = relationship('User', backref='created_pages')
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py b/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py
new file mode 100644
index 000000000..6bd3315d6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py
@@ -0,0 +1,29 @@
+import bcrypt
+from sqlalchemy import (
+    Column,
+    Integer,
+    Text,
+)
+
+from .meta import Base
+
+
+class User(Base):
+    """ The SQLAlchemy declarative model class for a User object. """
+    __tablename__ = 'users'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text, nullable=False, unique=True)
+    role = Column(Text, nullable=False)
+
+    password_hash = Column(Text)
+
+    def set_password(self, pw):
+        pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
+        self.password_hash = pwhash
+
+    def check_password(self, pw):
+        if self.password_hash is not None:
+            expected_hash = self.password_hash
+            actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
+            return expected_hash == actual_hash
+        return False
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/routes.py b/docs/tutorials/wiki2/src/authentication/tutorial/routes.py
new file mode 100644
index 000000000..cb747244f
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/routes.py
@@ -0,0 +1,8 @@
+def includeme(config):
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.add_route('view_wiki', '/')
+    config.add_route('login', '/login')
+    config.add_route('logout', '/logout')
+    config.add_route('view_page', '/{pagename}')
+    config.add_route('add_page', '/add_page/{pagename}')
+    config.add_route('edit_page', '/{pagename}/edit_page')
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/scripts/__init__.py b/docs/tutorials/wiki2/src/authentication/tutorial/scripts/__init__.py
new file mode 100644
index 000000000..5bb534f79
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/scripts/__init__.py
@@ -0,0 +1 @@
+# package
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/authentication/tutorial/scripts/initializedb.py
new file mode 100644
index 000000000..f3c0a6fef
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/scripts/initializedb.py
@@ -0,0 +1,57 @@
+import os
+import sys
+import transaction
+
+from pyramid.paster import (
+    get_appsettings,
+    setup_logging,
+    )
+
+from pyramid.scripts.common import parse_vars
+
+from ..models.meta import Base
+from ..models import (
+    get_engine,
+    get_session_factory,
+    get_tm_session,
+    )
+from ..models import Page, User
+
+
+def usage(argv):
+    cmd = os.path.basename(argv[0])
+    print('usage: %s <config_uri> [var=value]\n'
+          '(example: "%s development.ini")' % (cmd, cmd))
+    sys.exit(1)
+
+
+def main(argv=sys.argv):
+    if len(argv) < 2:
+        usage(argv)
+    config_uri = argv[1]
+    options = parse_vars(argv[2:])
+    setup_logging(config_uri)
+    settings = get_appsettings(config_uri, options=options)
+
+    engine = get_engine(settings)
+    Base.metadata.create_all(engine)
+
+    session_factory = get_session_factory(engine)
+
+    with transaction.manager:
+        dbsession = get_tm_session(session_factory, transaction.manager)
+
+        editor = User(name='editor', role='editor')
+        editor.set_password('editor')
+        dbsession.add(editor)
+
+        basic = User(name='basic', role='basic')
+        basic.set_password('basic')
+        dbsession.add(basic)
+
+        page = Page(
+            name='FrontPage',
+            creator=editor,
+            data='This is the front page',
+        )
+        dbsession.add(page)
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/security.py b/docs/tutorials/wiki2/src/authentication/tutorial/security.py
new file mode 100644
index 000000000..8ea3858d2
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/security.py
@@ -0,0 +1,27 @@
+from pyramid.authentication import AuthTktAuthenticationPolicy
+from pyramid.authorization import ACLAuthorizationPolicy
+
+from .models import User
+
+
+class MyAuthenticationPolicy(AuthTktAuthenticationPolicy):
+    def authenticated_userid(self, request):
+        user = request.user
+        if user is not None:
+            return user.id
+
+def get_user(request):
+    user_id = request.unauthenticated_userid
+    if user_id is not None:
+        user = request.dbsession.query(User).get(user_id)
+        return user
+
+def includeme(config):
+    settings = config.get_settings()
+    authn_policy = MyAuthenticationPolicy(
+        settings['auth.secret'],
+        hashalg='sha512',
+    )
+    config.set_authentication_policy(authn_policy)
+    config.set_authorization_policy(ACLAuthorizationPolicy())
+    config.add_request_method(get_user, 'user', reify=True)
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki2/src/authentication/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/static/pyramid.png b/docs/tutorials/wiki2/src/authentication/tutorial/static/pyramid.png
new file mode 100644
index 000000000..4ab837be9
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/static/theme.css b/docs/tutorials/wiki2/src/authentication/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/templates/404.jinja2 b/docs/tutorials/wiki2/src/authentication/tutorial/templates/404.jinja2
new file mode 100644
index 000000000..37b0a16b6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/templates/404.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid tutorial wiki</span> <span class="smaller">(based on TurboGears 20-Minute Wiki)</span></h1>
+  <p class="lead"><span class="font-semi-bold">404</span> Page Not Found</p>
+</div>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/templates/edit.jinja2 b/docs/tutorials/wiki2/src/authentication/tutorial/templates/edit.jinja2
new file mode 100644
index 000000000..7db25c674
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/templates/edit.jinja2
@@ -0,0 +1,20 @@
+{% extends 'layout.jinja2' %}
+
+{% block subtitle %}Edit {{pagename}} - {% endblock subtitle %}
+
+{% block content %}
+<p>
+Editing <strong>{{pagename}}</strong>
+</p>
+<p>You can return to the
+<a href="{{request.route_url('view_page', pagename='FrontPage')}}">FrontPage</a>.
+</p>
+<form action="{{ save_url }}" method="post">
+<div class="form-group">
+    <textarea class="form-control" name="body" rows="10" cols="60">{{ pagedata }}</textarea>
+</div>
+<div class="form-group">
+    <button type="submit" name="form.submitted" value="Save" class="btn btn-default">Save</button>
+</div>
+</form>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/templates/layout.jinja2 b/docs/tutorials/wiki2/src/authentication/tutorial/templates/layout.jinja2
new file mode 100644
index 000000000..44d14304e
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/templates/layout.jinja2
@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="{{request.locale_name}}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="{{request.static_url('tutorial:static/pyramid-16x16.png')}}">
+
+    <title>{% block subtitle %}{% endblock %}Pyramid tutorial wiki (based on TurboGears 20-Minute Wiki)</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="{{request.static_url('tutorial:static/theme.css')}}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="{{request.static_url('tutorial:static/pyramid.png')}}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+            {% if request.user is none %}
+            <p class="pull-right">
+            <a href="{{ request.route_url('login') }}">Login</a>
+            </p>
+            {% else %}
+            <p class="pull-right">
+            {{request.user.name}} <a href="{{request.route_url('logout')}}">Logout</a>
+            </p>
+            {% endif %}
+            {% block content %}{% endblock %}
+            </div>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/templates/login.jinja2 b/docs/tutorials/wiki2/src/authentication/tutorial/templates/login.jinja2
new file mode 100644
index 000000000..1806de0ff
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/templates/login.jinja2
@@ -0,0 +1,26 @@
+{% extends 'layout.jinja2' %}
+
+{% block title %}Login - {% endblock title %}
+
+{% block content %}
+<p>
+<strong>
+    Login
+</strong><br>
+{{ message }}
+</p>
+<form action="{{ url }}" method="post">
+<input type="hidden" name="next" value="{{ next_url }}">
+<div class="form-group">
+    <label for="login">Username</label>
+    <input type="text" name="login" value="{{ login }}">
+</div>
+<div class="form-group">
+    <label for="password">Password</label>
+    <input type="password" name="password">
+</div>
+<div class="form-group">
+    <button type="submit" name="form.submitted" value="Log In" class="btn btn-default">Log In</button>
+</div>
+</form>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/templates/view.jinja2 b/docs/tutorials/wiki2/src/authentication/tutorial/templates/view.jinja2
new file mode 100644
index 000000000..94419e228
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/templates/view.jinja2
@@ -0,0 +1,18 @@
+{% extends 'layout.jinja2' %}
+
+{% block subtitle %}{{page.name}} - {% endblock subtitle %}
+
+{% block content %}
+<p>{{ content|safe }}</p>
+<p>
+<a href="{{ edit_url }}">
+    Edit this page
+</a>
+</p>
+<p>
+    Viewing <strong>{{page.name}}</strong>, created by <strong>{{page.creator.name}}</strong>.
+</p>
+<p>You can return to the
+<a href="{{request.route_url('view_page', pagename='FrontPage')}}">FrontPage</a>.
+</p>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/tests.py b/docs/tutorials/wiki2/src/authentication/tutorial/tests.py
new file mode 100644
index 000000000..99e95efd3
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/tests.py
@@ -0,0 +1,65 @@
+import unittest
+import transaction
+
+from pyramid import testing
+
+
+def dummy_request(dbsession):
+    return testing.DummyRequest(dbsession=dbsession)
+
+
+class BaseTest(unittest.TestCase):
+    def setUp(self):
+        self.config = testing.setUp(settings={
+            'sqlalchemy.url': 'sqlite:///:memory:'
+        })
+        self.config.include('.models')
+        settings = self.config.get_settings()
+
+        from .models import (
+            get_engine,
+            get_session_factory,
+            get_tm_session,
+            )
+
+        self.engine = get_engine(settings)
+        session_factory = get_session_factory(self.engine)
+
+        self.session = get_tm_session(session_factory, transaction.manager)
+
+    def init_database(self):
+        from .models.meta import Base
+        Base.metadata.create_all(self.engine)
+
+    def tearDown(self):
+        from .models.meta import Base
+
+        testing.tearDown()
+        transaction.abort()
+        Base.metadata.drop_all(self.engine)
+
+
+class TestMyViewSuccessCondition(BaseTest):
+
+    def setUp(self):
+        super(TestMyViewSuccessCondition, self).setUp()
+        self.init_database()
+
+        from .models import MyModel
+
+        model = MyModel(name='one', value=55)
+        self.session.add(model)
+
+    def test_passing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info['one'].name, 'one')
+        self.assertEqual(info['project'], 'tutorial')
+
+
+class TestMyViewFailureCondition(BaseTest):
+
+    def test_failing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info.status_int, 500)
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/views/__init__.py b/docs/tutorials/wiki2/src/authentication/tutorial/views/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/views/__init__.py
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/views/auth.py b/docs/tutorials/wiki2/src/authentication/tutorial/views/auth.py
new file mode 100644
index 000000000..2b993b430
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/views/auth.py
@@ -0,0 +1,46 @@
+from pyramid.httpexceptions import HTTPFound
+from pyramid.security import (
+    remember,
+    forget,
+    )
+from pyramid.view import (
+    forbidden_view_config,
+    view_config,
+)
+
+from ..models import User
+
+
+@view_config(route_name='login', renderer='../templates/login.jinja2')
+def login(request):
+    next_url = request.params.get('next', request.referrer)
+    if not next_url:
+        next_url = request.route_url('view_wiki')
+    message = ''
+    login = ''
+    if 'form.submitted' in request.params:
+        login = request.params['login']
+        password = request.params['password']
+        user = request.dbsession.query(User).filter_by(name=login).first()
+        if user is not None and user.check_password(password):
+            headers = remember(request, user.id)
+            return HTTPFound(location=next_url, headers=headers)
+        message = 'Failed login'
+
+    return dict(
+        message=message,
+        url=request.route_url('login'),
+        next_url=next_url,
+        login=login,
+        )
+
+@view_config(route_name='logout')
+def logout(request):
+    headers = forget(request)
+    next_url = request.route_url('view_wiki')
+    return HTTPFound(location=next_url, headers=headers)
+
+@forbidden_view_config()
+def forbidden_view(request):
+    next_url = request.route_url('login', _query={'next': request.url})
+    return HTTPFound(location=next_url)
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/views/default.py b/docs/tutorials/wiki2/src/authentication/tutorial/views/default.py
new file mode 100644
index 000000000..1b071434c
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/views/default.py
@@ -0,0 +1,79 @@
+import cgi
+import re
+from docutils.core import publish_parts
+
+from pyramid.httpexceptions import (
+    HTTPForbidden,
+    HTTPFound,
+    HTTPNotFound,
+    )
+
+from pyramid.view import view_config
+
+from ..models import Page
+
+# regular expression used to find WikiWords
+wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")
+
+@view_config(route_name='view_wiki')
+def view_wiki(request):
+    next_url = request.route_url('view_page', pagename='FrontPage')
+    return HTTPFound(location=next_url)
+
+@view_config(route_name='view_page', renderer='../templates/view.jinja2')
+def view_page(request):
+    pagename = request.matchdict['pagename']
+    page = request.dbsession.query(Page).filter_by(name=pagename).first()
+    if page is None:
+        raise HTTPNotFound('No such page')
+
+    def add_link(match):
+        word = match.group(1)
+        exists = request.dbsession.query(Page).filter_by(name=word).all()
+        if exists:
+            view_url = request.route_url('view_page', pagename=word)
+            return '<a href="%s">%s</a>' % (view_url, cgi.escape(word))
+        else:
+            add_url = request.route_url('add_page', pagename=word)
+            return '<a href="%s">%s</a>' % (add_url, cgi.escape(word))
+
+    content = publish_parts(page.data, writer_name='html')['html_body']
+    content = wikiwords.sub(add_link, content)
+    edit_url = request.route_url('edit_page', pagename=page.name)
+    return dict(page=page, content=content, edit_url=edit_url)
+
+@view_config(route_name='edit_page', renderer='../templates/edit.jinja2')
+def edit_page(request):
+    pagename = request.matchdict['pagename']
+    page = request.dbsession.query(Page).filter_by(name=pagename).one()
+    user = request.user
+    if user is None or (user.role != 'editor' and page.creator != user):
+        raise HTTPForbidden
+    if 'form.submitted' in request.params:
+        page.data = request.params['body']
+        next_url = request.route_url('view_page', pagename=page.name)
+        return HTTPFound(location=next_url)
+    return dict(
+        pagename=page.name,
+        pagedata=page.data,
+        save_url=request.route_url('edit_page', pagename=page.name),
+        )
+
+@view_config(route_name='add_page', renderer='../templates/edit.jinja2')
+def add_page(request):
+    user = request.user
+    if user is None or user.role not in ('editor', 'basic'):
+        raise HTTPForbidden
+    pagename = request.matchdict['pagename']
+    if request.dbsession.query(Page).filter_by(name=pagename).count() > 0:
+        next_url = request.route_url('edit_page', pagename=pagename)
+        return HTTPFound(location=next_url)
+    if 'form.submitted' in request.params:
+        body = request.params['body']
+        page = Page(name=pagename, data=body)
+        page.creator = request.user
+        request.dbsession.add(page)
+        next_url = request.route_url('view_page', pagename=pagename)
+        return HTTPFound(location=next_url)
+    save_url = request.route_url('add_page', pagename=pagename)
+    return dict(pagename=pagename, pagedata='', save_url=save_url)
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/views/notfound.py b/docs/tutorials/wiki2/src/authentication/tutorial/views/notfound.py
new file mode 100644
index 000000000..69d6e2804
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/views/notfound.py
@@ -0,0 +1,7 @@
+from pyramid.view import notfound_view_config
+
+
+@notfound_view_config(renderer='../templates/404.jinja2')
+def notfound_view(request):
+    request.response.status = 404
+    return {}
diff --git a/docs/tutorials/wiki2/src/authorization/MANIFEST.in b/docs/tutorials/wiki2/src/authorization/MANIFEST.in
index 81beba1b1..42cd299b5 100644
--- a/docs/tutorials/wiki2/src/authorization/MANIFEST.in
+++ b/docs/tutorials/wiki2/src/authorization/MANIFEST.in
@@ -1,2 +1,2 @@
 include *.txt *.ini *.cfg *.rst
-recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml
+recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.jinja2 *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/tutorials/wiki2/src/authorization/README.txt b/docs/tutorials/wiki2/src/authorization/README.txt
index d41f7f90f..5b0101e5f 100644
--- a/docs/tutorials/wiki2/src/authorization/README.txt
+++ b/docs/tutorials/wiki2/src/authorization/README.txt
@@ -1,4 +1,14 @@
 tutorial README
+==================
 
+Getting Started
+---------------
 
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/initialize_tutorial_db development.ini
+
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/authorization/development.ini b/docs/tutorials/wiki2/src/authorization/development.ini
index 3b615f635..4a6c9325c 100644
--- a/docs/tutorials/wiki2/src/authorization/development.ini
+++ b/docs/tutorials/wiki2/src/authorization/development.ini
@@ -1,32 +1,44 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = true
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = true
-default_locale_name = en
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
-
-[pipeline:main]
-pipeline =
-    egg:WebError#evalerror
-    tm
-    tutorial
-
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_tm
+
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
+
+auth.secret = seekrit
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
-host = 0.0.0.0
+use = egg:waitress#main
+host = 127.0.0.1
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
-keys = root, sqlalchemy
+keys = root, tutorial, sqlalchemy
 
 [handlers]
 keys = console
@@ -38,6 +50,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [logger_sqlalchemy]
 level = INFO
 handlers =
@@ -53,6 +70,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/authorization/production.ini b/docs/tutorials/wiki2/src/authorization/production.ini
index 0fdc38811..a13a0ca19 100644
--- a/docs/tutorials/wiki2/src/authorization/production.ini
+++ b/docs/tutorials/wiki2/src/authorization/production.ini
@@ -1,43 +1,30 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = false
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = false
-default_locale_name = en
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
 
-[filter:weberror]
-use = egg:WebError#error_catcher
-debug = false
-;error_log = 
-;show_exceptions_in_wsgi_errors = true
-;smtp_server = localhost
-;error_email = janitor@example.com
-;smtp_username = janitor
-;smtp_password = "janitor's password"
-;from_address = paste@localhost
-;error_subject_prefix = "Pyramid Error"
-;smtp_use_tls =
-;error_message =
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
-[pipeline:main]
-pipeline =
-    weberror
-    tm
-    tutorial
+auth.secret = real-seekrit
 
 [server:main]
-use = egg:Paste#http
+use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -72,6 +59,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/authorization/setup.cfg b/docs/tutorials/wiki2/src/authorization/setup.cfg
deleted file mode 100644
index 23b2ad983..000000000
--- a/docs/tutorials/wiki2/src/authorization/setup.cfg
+++ /dev/null
@@ -1,27 +0,0 @@
-[nosetests]
-match=^test
-nocapture=1
-cover-package=tutorial
-with-coverage=1
-cover-erase=1
-
-[compile_catalog]
-directory = tutorial/locale
-domain = tutorial
-statistics = true
-
-[extract_messages]
-add_comments = TRANSLATORS:
-output_file = tutorial/locale/tutorial.pot
-width = 80
-
-[init_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-
-[update_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-previous = true
diff --git a/docs/tutorials/wiki2/src/authorization/setup.py b/docs/tutorials/wiki2/src/authorization/setup.py
index ae9869d50..def3ce1f6 100644
--- a/docs/tutorials/wiki2/src/authorization/setup.py
+++ b/docs/tutorials/wiki2/src/authorization/setup.py
@@ -1,35 +1,42 @@
 import os
-import sys
 
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
+    'bcrypt',
+    'docutils',
     'pyramid',
+    'pyramid_jinja2',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
     'SQLAlchemy',
     'transaction',
-    'repoze.tm2>=1.0b1', # default_commit_veto
     'zope.sqlalchemy',
-    'WebError',
-    'docutils',
+    'waitress',
     ]
 
-if sys.version_info[:3] < (2,5,0):
-    requires.append('pysqlite')
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
 
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Programming Language :: Python",
-        "Framework :: Pylons",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
       author='',
       author_email='',
       url='',
@@ -37,12 +44,14 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
+      [console_scripts]
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
-      paster_plugins=['pyramid'],
       )
-
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
index 05183d3d4..f5c033b8b 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
@@ -1,45 +1,13 @@
 from pyramid.config import Configurator
-from pyramid.authentication import AuthTktAuthenticationPolicy
-from pyramid.authorization import ACLAuthorizationPolicy
 
-from sqlalchemy import engine_from_config
-
-from tutorial.models import initialize_sql
-from tutorial.security import groupfinder
 
 def main(global_config, **settings):
-    """ This function returns a WSGI application.
+    """ This function returns a Pyramid WSGI application.
     """
-    engine = engine_from_config(settings, 'sqlalchemy.')
-    initialize_sql(engine)
-    authn_policy = AuthTktAuthenticationPolicy(
-        'sosecret', callback=groupfinder)
-    authz_policy = ACLAuthorizationPolicy()
-    config = Configurator(settings=settings,
-                          root_factory='tutorial.models.RootFactory',
-                          authentication_policy=authn_policy,
-                          authorization_policy=authz_policy)
-    config.add_static_view('static', 'tutorial:static')
-
-    config.add_route('view_wiki', '/')
-    config.add_route('login', '/login')
-    config.add_route('logout', '/logout')
-    config.add_route('view_page', '/{pagename}')
-    config.add_route('add_page', '/add_page/{pagename}')
-    config.add_route('edit_page', '/{pagename}/edit_page')
-
-    config.add_view('tutorial.views.view_wiki', route_name='view_wiki')
-    config.add_view('tutorial.login.login', route_name='login', 
-                    renderer='tutorial:templates/login.pt')
-    config.add_view('tutorial.login.logout', route_name='logout')
-    config.add_view('tutorial.views.view_page', route_name='view_page',
-                    renderer='tutorial:templates/view.pt')
-    config.add_view('tutorial.views.add_page', route_name='add_page',
-                    renderer='tutorial:templates/edit.pt', permission='edit')
-    config.add_view('tutorial.views.edit_page', route_name='edit_page',
-                    renderer='tutorial:templates/edit.pt', permission='edit')
-    config.add_view('tutorial.login.login',
-                    context='pyramid.exceptions.Forbidden',
-                    renderer='tutorial:templates/login.pt')
+    config = Configurator(settings=settings)
+    config.include('pyramid_jinja2')
+    config.include('.models')
+    config.include('.routes')
+    config.include('.security')
+    config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/login.py b/docs/tutorials/wiki2/src/authorization/tutorial/login.py
deleted file mode 100644
index 7a1d1f663..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/login.py
+++ /dev/null
@@ -1,38 +0,0 @@
-from pyramid.httpexceptions import HTTPFound
-from pyramid.security import remember
-from pyramid.security import forget
-from pyramid.url import route_url
-
-from tutorial.security import USERS
-
-def login(request):
-    login_url = route_url('login', request)
-    referrer = request.url
-    if referrer == login_url:
-        referrer = '/' # never use the login form itself as came_from
-    came_from = request.params.get('came_from', referrer)
-    message = ''
-    login = ''
-    password = ''
-    if 'form.submitted' in request.params:
-        login = request.params['login']
-        password = request.params['password']
-        if USERS.get(login) == password:
-            headers = remember(request, login)
-            return HTTPFound(location = came_from,
-                             headers = headers)
-        message = 'Failed login'
-
-    return dict(
-        message = message,
-        url = request.application_url + '/login',
-        came_from = came_from,
-        login = login,
-        password = password,
-        )
-    
-def logout(request):
-    headers = forget(request)
-    return HTTPFound(location = route_url('view_wiki', request),
-                     headers = headers)
-    
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models.py b/docs/tutorials/wiki2/src/authorization/tutorial/models.py
deleted file mode 100644
index 53c6d1122..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/models.py
+++ /dev/null
@@ -1,50 +0,0 @@
-import transaction
-
-from pyramid.security import Allow
-from pyramid.security import Everyone
-
-from sqlalchemy import Column
-from sqlalchemy import Integer
-from sqlalchemy import Text
-
-from sqlalchemy.exc import IntegrityError
-from sqlalchemy.ext.declarative import declarative_base
-
-from sqlalchemy.orm import scoped_session
-from sqlalchemy.orm import sessionmaker
-
-from zope.sqlalchemy import ZopeTransactionExtension
-
-DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
-Base = declarative_base()
-
-class Page(Base):
-    """ The SQLAlchemy declarative model class for a Page object. """
-    __tablename__ = 'pages'
-    id = Column(Integer, primary_key=True)
-    name = Column(Text, unique=True)
-    data = Column(Text)
-
-    def __init__(self, name, data):
-        self.name = name
-        self.data = data
-
-def initialize_sql(engine):
-    DBSession.configure(bind=engine)
-    Base.metadata.bind = engine
-    Base.metadata.create_all(engine)
-    try:
-        transaction.begin()
-        session = DBSession()
-        page = Page('FrontPage', 'This is the front page')
-        session.add(page)
-        transaction.commit()
-    except IntegrityError:
-        # already created
-        pass
-
-class RootFactory(object):
-    __acl__ = [ (Allow, Everyone, 'view'),
-                (Allow, 'group:editors', 'edit') ]
-    def __init__(self, request):
-        pass
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/authorization/tutorial/models/__init__.py
new file mode 100644
index 000000000..a8871f6f5
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models/__init__.py
@@ -0,0 +1,74 @@
+from sqlalchemy import engine_from_config
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import configure_mappers
+import zope.sqlalchemy
+
+# import or define all models here to ensure they are attached to the
+# Base.metadata prior to any initialization routines
+from .page import Page # flake8: noqa
+from .user import User # flake8: noqa
+
+# run configure_mappers after defining all of the models to ensure
+# all relationships can be setup
+configure_mappers()
+
+
+def get_engine(settings, prefix='sqlalchemy.'):
+    return engine_from_config(settings, prefix)
+
+
+def get_session_factory(engine):
+    factory = sessionmaker()
+    factory.configure(bind=engine)
+    return factory
+
+
+def get_tm_session(session_factory, transaction_manager):
+    """
+    Get a ``sqlalchemy.orm.Session`` instance backed by a transaction.
+
+    This function will hook the session to the transaction manager which
+    will take care of committing any changes.
+
+    - When using pyramid_tm it will automatically be committed or aborted
+      depending on whether an exception is raised.
+
+    - When using scripts you should wrap the session in a manager yourself.
+      For example::
+
+          import transaction
+
+          engine = get_engine(settings)
+          session_factory = get_session_factory(engine)
+          with transaction.manager:
+              dbsession = get_tm_session(session_factory, transaction.manager)
+
+    """
+    dbsession = session_factory()
+    zope.sqlalchemy.register(
+        dbsession, transaction_manager=transaction_manager)
+    return dbsession
+
+
+def includeme(config):
+    """
+    Initialize the model for a Pyramid app.
+
+    Activate this setup using ``config.include('tutorial.models')``.
+
+    """
+    settings = config.get_settings()
+
+    # use pyramid_tm to hook the transaction lifecycle to the request
+    config.include('pyramid_tm')
+
+    session_factory = get_session_factory(get_engine(settings))
+    config.registry['dbsession_factory'] = session_factory
+
+    # make request.dbsession available for use in Pyramid
+    config.add_request_method(
+        # r.tm is the transaction manager used by pyramid_tm
+        lambda r: get_tm_session(session_factory, r.tm),
+        'dbsession',
+        reify=True
+    )
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models/meta.py b/docs/tutorials/wiki2/src/authorization/tutorial/models/meta.py
new file mode 100644
index 000000000..fc3e8f1dd
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models/meta.py
@@ -0,0 +1,16 @@
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.schema import MetaData
+
+# Recommended naming convention used by Alembic, as various different database
+# providers will autogenerate vastly different names making migrations more
+# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+NAMING_CONVENTION = {
+    "ix": 'ix_%(column_0_label)s',
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s"
+}
+
+metadata = MetaData(naming_convention=NAMING_CONVENTION)
+Base = declarative_base(metadata=metadata)
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models/page.py b/docs/tutorials/wiki2/src/authorization/tutorial/models/page.py
new file mode 100644
index 000000000..4dd5b5721
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models/page.py
@@ -0,0 +1,20 @@
+from sqlalchemy import (
+    Column,
+    ForeignKey,
+    Integer,
+    Text,
+)
+from sqlalchemy.orm import relationship
+
+from .meta import Base
+
+
+class Page(Base):
+    """ The SQLAlchemy declarative model class for a Page object. """
+    __tablename__ = 'pages'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text, nullable=False, unique=True)
+    data = Column(Integer, nullable=False)
+
+    creator_id = Column(ForeignKey('users.id'), nullable=False)
+    creator = relationship('User', backref='created_pages')
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py b/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py
new file mode 100644
index 000000000..6bd3315d6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py
@@ -0,0 +1,29 @@
+import bcrypt
+from sqlalchemy import (
+    Column,
+    Integer,
+    Text,
+)
+
+from .meta import Base
+
+
+class User(Base):
+    """ The SQLAlchemy declarative model class for a User object. """
+    __tablename__ = 'users'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text, nullable=False, unique=True)
+    role = Column(Text, nullable=False)
+
+    password_hash = Column(Text)
+
+    def set_password(self, pw):
+        pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
+        self.password_hash = pwhash
+
+    def check_password(self, pw):
+        if self.password_hash is not None:
+            expected_hash = self.password_hash
+            actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
+            return expected_hash == actual_hash
+        return False
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/routes.py b/docs/tutorials/wiki2/src/authorization/tutorial/routes.py
new file mode 100644
index 000000000..f0a8b7f96
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/routes.py
@@ -0,0 +1,56 @@
+from pyramid.httpexceptions import (
+    HTTPNotFound,
+    HTTPFound,
+)
+from pyramid.security import (
+    Allow,
+    Everyone,
+)
+
+from .models import Page
+
+def includeme(config):
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.add_route('view_wiki', '/')
+    config.add_route('login', '/login')
+    config.add_route('logout', '/logout')
+    config.add_route('view_page', '/{pagename}', factory=page_factory)
+    config.add_route('add_page', '/add_page/{pagename}',
+                     factory=new_page_factory)
+    config.add_route('edit_page', '/{pagename}/edit_page',
+                     factory=page_factory)
+
+def new_page_factory(request):
+    pagename = request.matchdict['pagename']
+    if request.dbsession.query(Page).filter_by(name=pagename).count() > 0:
+        next_url = request.route_url('edit_page', pagename=pagename)
+        raise HTTPFound(location=next_url)
+    return NewPage(pagename)
+
+class NewPage(object):
+    def __init__(self, pagename):
+        self.pagename = pagename
+
+    def __acl__(self):
+        return [
+            (Allow, 'role:editor', 'create'),
+            (Allow, 'role:basic', 'create'),
+        ]
+
+def page_factory(request):
+    pagename = request.matchdict['pagename']
+    page = request.dbsession.query(Page).filter_by(name=pagename).first()
+    if page is None:
+        raise HTTPNotFound
+    return PageResource(page)
+
+class PageResource(object):
+    def __init__(self, page):
+        self.page = page
+
+    def __acl__(self):
+        return [
+            (Allow, Everyone, 'view'),
+            (Allow, 'role:editor', 'edit'),
+            (Allow, str(self.page.creator_id), 'edit'),
+        ]
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/__init__.py b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/__init__.py
new file mode 100644
index 000000000..5bb534f79
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/__init__.py
@@ -0,0 +1 @@
+# package
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
new file mode 100644
index 000000000..f3c0a6fef
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
@@ -0,0 +1,57 @@
+import os
+import sys
+import transaction
+
+from pyramid.paster import (
+    get_appsettings,
+    setup_logging,
+    )
+
+from pyramid.scripts.common import parse_vars
+
+from ..models.meta import Base
+from ..models import (
+    get_engine,
+    get_session_factory,
+    get_tm_session,
+    )
+from ..models import Page, User
+
+
+def usage(argv):
+    cmd = os.path.basename(argv[0])
+    print('usage: %s <config_uri> [var=value]\n'
+          '(example: "%s development.ini")' % (cmd, cmd))
+    sys.exit(1)
+
+
+def main(argv=sys.argv):
+    if len(argv) < 2:
+        usage(argv)
+    config_uri = argv[1]
+    options = parse_vars(argv[2:])
+    setup_logging(config_uri)
+    settings = get_appsettings(config_uri, options=options)
+
+    engine = get_engine(settings)
+    Base.metadata.create_all(engine)
+
+    session_factory = get_session_factory(engine)
+
+    with transaction.manager:
+        dbsession = get_tm_session(session_factory, transaction.manager)
+
+        editor = User(name='editor', role='editor')
+        editor.set_password('editor')
+        dbsession.add(editor)
+
+        basic = User(name='basic', role='basic')
+        basic.set_password('basic')
+        dbsession.add(basic)
+
+        page = Page(
+            name='FrontPage',
+            creator=editor,
+            data='This is the front page',
+        )
+        dbsession.add(page)
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/security.py b/docs/tutorials/wiki2/src/authorization/tutorial/security.py
index cfd13071e..25cff7b05 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/security.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/security.py
@@ -1,8 +1,40 @@
-USERS = {'editor':'editor',
-          'viewer':'viewer'}
-GROUPS = {'editor':['group:editors']}
+from pyramid.authentication import AuthTktAuthenticationPolicy
+from pyramid.authorization import ACLAuthorizationPolicy
+from pyramid.security import (
+    Authenticated,
+    Everyone,
+)
 
-def groupfinder(userid, request):
-    if userid in USERS:
-        return GROUPS.get(userid, [])
+from .models import User
 
+
+class MyAuthenticationPolicy(AuthTktAuthenticationPolicy):
+    def authenticated_userid(self, request):
+        user = request.user
+        if user is not None:
+            return user.id
+
+    def effective_principals(self, request):
+        principals = [Everyone]
+        user = request.user
+        if user is not None:
+            principals.append(Authenticated)
+            principals.append(str(user.id))
+            principals.append('role:' + user.role)
+        return principals
+
+def get_user(request):
+    user_id = request.unauthenticated_userid
+    if user_id is not None:
+        user = request.dbsession.query(User).get(user_id)
+        return user
+
+def includeme(config):
+    settings = config.get_settings()
+    authn_policy = MyAuthenticationPolicy(
+        settings['auth.secret'],
+        hashalg='sha512',
+    )
+    config.set_authentication_policy(authn_policy)
+    config.set_authorization_policy(ACLAuthorizationPolicy())
+    config.add_request_method(get_user, 'user', reify=True)
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/favicon.ico b/docs/tutorials/wiki2/src/authorization/tutorial/static/favicon.ico
deleted file mode 100644
index 71f837c9e..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/static/favicon.ico
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/footerbg.png b/docs/tutorials/wiki2/src/authorization/tutorial/static/footerbg.png
deleted file mode 100644
index 1fbc873da..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/static/footerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/headerbg.png b/docs/tutorials/wiki2/src/authorization/tutorial/static/headerbg.png
deleted file mode 100644
index 0596f2020..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/static/headerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/ie6.css b/docs/tutorials/wiki2/src/authorization/tutorial/static/ie6.css
deleted file mode 100644
index b7c8493d8..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/static/ie6.css
+++ /dev/null
@@ -1,8 +0,0 @@
-* html img,
-* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
-this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
-this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
-);}
-#wrap{display:table;height:100%}
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/middlebg.png b/docs/tutorials/wiki2/src/authorization/tutorial/static/middlebg.png
deleted file mode 100644
index 2369cfb7d..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/static/middlebg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/pylons.css b/docs/tutorials/wiki2/src/authorization/tutorial/static/pylons.css
deleted file mode 100644
index fd1914d8d..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/static/pylons.css
+++ /dev/null
@@ -1,65 +0,0 @@
-html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */
-vertical-align:baseline;background:transparent;}
-body{line-height:1;}
-ol,ul{list-style:none;}
-blockquote,q{quotes:none;}
-blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;}
-:focus{outline:0;}
-ins{text-decoration:none;}
-del{text-decoration:line-through;}
-table{border-collapse:collapse;border-spacing:0;}
-sub{vertical-align:sub;font-size:smaller;line-height:normal;}
-sup{vertical-align:super;font-size:smaller;line-height:normal;}
-ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;}
-ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;}
-li{display:list-item;}
-ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;}
-ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;}
-ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;}
-.hidden{display:none;}
-p{line-height:1.5em;}
-h1{font-size:1.75em;line-height:1.7em;font-family:helvetica,verdana;}
-h2{font-size:1.5em;line-height:1.7em;font-family:helvetica,verdana;}
-h3{font-size:1.25em;line-height:1.7em;font-family:helvetica,verdana;}
-h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;}
-html,body{width:100%;height:100%;}
-body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;}
-a{color:#1b61d6;text-decoration:none;}
-a:hover{color:#e88f00;text-decoration:underline;}
-body h1,
-body h2,
-body h3,
-body h4,
-body h5,
-body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;}
-#wrap{min-height:100%;}
-#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;}
-#header{background:#000000;top:0;font-size:14px;}
-#footer{bottom:0;background:#000000 url(footerbg.png) repeat-x 0 top;position:relative;margin-top:-40px;clear:both;}
-.header,.footer{width:750px;margin-right:auto;margin-left:auto;}
-.wrapper{width:100%}
-#top,#top-small,#bottom{width:100%;}
-#top{color:#000000;height:230px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#top-small{color:#000000;height:60px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#bottom{color:#222;background-color:#ffffff;}
-.top,.top-small,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;}
-.top{padding-top:40px;}
-.top-small{padding-top:10px;}
-#middle{width:100%;height:100px;background:url(middlebg.png) repeat-x;border-top:2px solid #ffffff;border-bottom:2px solid #b2b2b2;}
-.app-welcome{margin-top:25px;}
-.app-name{color:#000000;font-weight:bold;}
-.bottom{padding-top:50px;}
-#left{width:350px;float:left;padding-right:25px;}
-#right{width:350px;float:right;padding-left:25px;}
-.align-left{text-align:left;}
-.align-right{text-align:right;}
-.align-center{text-align:center;}
-ul.links{margin:0;padding:0;}
-ul.links li{list-style-type:none;font-size:14px;}
-form{border-style:none;}
-fieldset{border-style:none;}
-input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;}
-input[type=text],input[type=password]{width:205px;}
-input[type=submit]{background-color:#ddd;font-weight:bold;}
-/*Opera Fix*/
-body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;}
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki2/src/authorization/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/pyramid-small.png b/docs/tutorials/wiki2/src/authorization/tutorial/static/pyramid-small.png
deleted file mode 100644
index a5bc0ade7..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/static/pyramid-small.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/pyramid.png b/docs/tutorials/wiki2/src/authorization/tutorial/static/pyramid.png
index 347e05549..4ab837be9 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/static/pyramid.png
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/theme.css b/docs/tutorials/wiki2/src/authorization/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/static/transparent.gif b/docs/tutorials/wiki2/src/authorization/tutorial/static/transparent.gif
deleted file mode 100644
index 0341802e5..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/static/transparent.gif
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/404.jinja2 b/docs/tutorials/wiki2/src/authorization/tutorial/templates/404.jinja2
new file mode 100644
index 000000000..37b0a16b6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/templates/404.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid tutorial wiki</span> <span class="smaller">(based on TurboGears 20-Minute Wiki)</span></h1>
+  <p class="lead"><span class="font-semi-bold">404</span> Page Not Found</p>
+</div>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/edit.jinja2 b/docs/tutorials/wiki2/src/authorization/tutorial/templates/edit.jinja2
new file mode 100644
index 000000000..7db25c674
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/templates/edit.jinja2
@@ -0,0 +1,20 @@
+{% extends 'layout.jinja2' %}
+
+{% block subtitle %}Edit {{pagename}} - {% endblock subtitle %}
+
+{% block content %}
+<p>
+Editing <strong>{{pagename}}</strong>
+</p>
+<p>You can return to the
+<a href="{{request.route_url('view_page', pagename='FrontPage')}}">FrontPage</a>.
+</p>
+<form action="{{ save_url }}" method="post">
+<div class="form-group">
+    <textarea class="form-control" name="body" rows="10" cols="60">{{ pagedata }}</textarea>
+</div>
+<div class="form-group">
+    <button type="submit" name="form.submitted" value="Save" class="btn btn-default">Save</button>
+</div>
+</form>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/edit.pt b/docs/tutorials/wiki2/src/authorization/tutorial/templates/edit.pt
deleted file mode 100644
index ca28b9fa5..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/templates/edit.pt
+++ /dev/null
@@ -1,62 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
-      xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>${page.name} - Pyramid tutorial wiki (based on
-    TurboGears 20-Minute Wiki)</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon"
-        href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/pylons.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/ie6.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top-small">
-      <div class="top-small align-center">
-        <div>
-          <img width="220" height="50" alt="pyramid"
-        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
-        </div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-right">
-        <div id="left" class="app-welcome align-left">
-          Editing <b><span tal:replace="page.name">Page Name
-            Goes Here</span></b><br/>
-          You can return to the
-          <a href="${request.application_url}">FrontPage</a>.<br/>
-        </div>
-        <div id="right" class="app-welcome align-right">
-          <span tal:condition="logged_in">
-              <a href="${request.application_url}/logout">Logout</a>
-          </span>
-        </div>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <form action="${save_url}" method="post">
-          <textarea name="body" tal:content="page.data" rows="10"
-                    cols="60"/><br/>
-          <input type="submit" name="form.submitted" value="Save"/>
-        </form>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer"
-         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
-</html>
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/layout.jinja2 b/docs/tutorials/wiki2/src/authorization/tutorial/templates/layout.jinja2
new file mode 100644
index 000000000..44d14304e
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/templates/layout.jinja2
@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="{{request.locale_name}}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="{{request.static_url('tutorial:static/pyramid-16x16.png')}}">
+
+    <title>{% block subtitle %}{% endblock %}Pyramid tutorial wiki (based on TurboGears 20-Minute Wiki)</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="{{request.static_url('tutorial:static/theme.css')}}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="{{request.static_url('tutorial:static/pyramid.png')}}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+            {% if request.user is none %}
+            <p class="pull-right">
+            <a href="{{ request.route_url('login') }}">Login</a>
+            </p>
+            {% else %}
+            <p class="pull-right">
+            {{request.user.name}} <a href="{{request.route_url('logout')}}">Logout</a>
+            </p>
+            {% endif %}
+            {% block content %}{% endblock %}
+            </div>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/login.jinja2 b/docs/tutorials/wiki2/src/authorization/tutorial/templates/login.jinja2
new file mode 100644
index 000000000..1806de0ff
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/templates/login.jinja2
@@ -0,0 +1,26 @@
+{% extends 'layout.jinja2' %}
+
+{% block title %}Login - {% endblock title %}
+
+{% block content %}
+<p>
+<strong>
+    Login
+</strong><br>
+{{ message }}
+</p>
+<form action="{{ url }}" method="post">
+<input type="hidden" name="next" value="{{ next_url }}">
+<div class="form-group">
+    <label for="login">Username</label>
+    <input type="text" name="login" value="{{ login }}">
+</div>
+<div class="form-group">
+    <label for="password">Password</label>
+    <input type="password" name="password">
+</div>
+<div class="form-group">
+    <button type="submit" name="form.submitted" value="Log In" class="btn btn-default">Log In</button>
+</div>
+</form>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/login.pt b/docs/tutorials/wiki2/src/authorization/tutorial/templates/login.pt
deleted file mode 100644
index 64e592ea9..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/templates/login.pt
+++ /dev/null
@@ -1,58 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
-      xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>Login - Pyramid tutorial wiki (based on TurboGears
-    20-Minute Wiki)</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon"
-        href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/pylons.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/ie6.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top-small">
-      <div class="top-small align-center">
-        <div>
-          <img width="220" height="50" alt="pyramid"
-        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
-        </div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-right">
-        <div id="left" class="app-welcome align-left">
-          <b>Login</b><br/>
-          <span tal:replace="message"/>
-        </div>
-        <div id="right" class="app-welcome align-right"></div>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <form action="${url}" method="post">
-          <input type="hidden" name="came_from" value="${came_from}"/>
-          <input type="text" name="login" value="${login}"/><br/>
-          <input type="password" name="password"
-                 value="${password}"/><br/>
-          <input type="submit" name="form.submitted" value="Log In"/>
-        </form>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer"
-         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
-</html>
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt
deleted file mode 100644
index d98420680..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt
+++ /dev/null
@@ -1,75 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>The Pyramid Web Application Development Framework</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon" href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
-  <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton|Nobile:regular,i,b,bi&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top">
-      <div class="top align-center">
-        <div><img src="${request.static_url('tutorial:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-center">
-        <p class="app-welcome">
-          Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web application development framework.
-        </p>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div id="left" class="align-right">
-          <h2>Search documentation</h2>
-          <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/dev/search.html">
-                <input type="text" id="q" name="q" value="" />
-                <input type="submit" id="x" value="Go" />
-            </form>
-        </div>
-        <div id="right" class="align-left">
-          <h2>Pyramid links</h2>
-          <ul class="links">
-            <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#narrative-documentation">Narrative Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#api-documentation">API Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#tutorials">Tutorials</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#change-history">Change History</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#sample-applications">Sample Applications</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#support-and-development">Support and Development</a>
-            </li>
-            <li>
-              <a href="irc://irc.freenode.net#pyramid">IRC Channel</a>
-            </li>
-            </ul>
-        </div>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
-</html>
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/view.jinja2 b/docs/tutorials/wiki2/src/authorization/tutorial/templates/view.jinja2
new file mode 100644
index 000000000..94419e228
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/templates/view.jinja2
@@ -0,0 +1,18 @@
+{% extends 'layout.jinja2' %}
+
+{% block subtitle %}{{page.name}} - {% endblock subtitle %}
+
+{% block content %}
+<p>{{ content|safe }}</p>
+<p>
+<a href="{{ edit_url }}">
+    Edit this page
+</a>
+</p>
+<p>
+    Viewing <strong>{{page.name}}</strong>, created by <strong>{{page.creator.name}}</strong>.
+</p>
+<p>You can return to the
+<a href="{{request.route_url('view_page', pagename='FrontPage')}}">FrontPage</a>.
+</p>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/view.pt b/docs/tutorials/wiki2/src/authorization/tutorial/templates/view.pt
deleted file mode 100644
index 5a69818c1..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/templates/view.pt
+++ /dev/null
@@ -1,65 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
-      xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>${page.name} - Pyramid tutorial wiki (based on
-    TurboGears 20-Minute Wiki)</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon"
-        href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/pylons.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/ie6.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top-small">
-      <div class="top-small align-center">
-        <div>
-          <img width="220" height="50" alt="pyramid"
-        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
-        </div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-right">
-        <div id="left" class="app-welcome align-left">
-          Viewing <b><span tal:replace="page.name">Page Name
-            Goes Here</span></b><br/>
-          You can return to the
-          <a href="${request.application_url}">FrontPage</a>.<br/>
-        </div>
-        <div id="right" class="app-welcome align-right">
-          <span tal:condition="logged_in">
-            <a href="${request.application_url}/logout">Logout</a>
-          </span>
-        </div>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div tal:replace="structure content">
-          Page text goes here.
-        </div>
-        <p>
-          <a tal:attributes="href edit_url" href="">
-            Edit this page
-          </a>
-        </p>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer"
-         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
-</html>
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/tests.py b/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
index 332031ba4..99e95efd3 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
@@ -1,136 +1,65 @@
 import unittest
+import transaction
 
 from pyramid import testing
 
-def _initTestingDB():
-    from tutorial.models import DBSession
-    from tutorial.models import Base
-    from sqlalchemy import create_engine
-    engine = create_engine('sqlite://')
-    DBSession.configure(bind=engine)
-    Base.metadata.bind = engine
-    Base.metadata.create_all(engine)
-    return DBSession
-
-def _registerRoutes(config):
-    config.add_route('view_page', '{pagename}')
-    config.add_route('edit_page', '{pagename}/edit_page')
-    config.add_route('add_page', 'add_page/{pagename}')
-
-class ViewWikiTests(unittest.TestCase):
-    def setUp(self):
-        self.config = testing.setUp()
 
-    def tearDown(self):
-        testing.tearDown()
+def dummy_request(dbsession):
+    return testing.DummyRequest(dbsession=dbsession)
 
-    def _callFUT(self, request):
-        from tutorial.views import view_wiki
-        return view_wiki(request)
-        
-    def test_it(self):
-        _registerRoutes(self.config)
-        request = testing.DummyRequest()
-        response = self._callFUT(request)
-        self.assertEqual(response.location, 'http://example.com/FrontPage')
-
-class ViewPageTests(unittest.TestCase):
-    def setUp(self):
-        self.session = _initTestingDB()
-        self.config = testing.setUp()
 
-    def tearDown(self):
-        testing.tearDown()
-        
-    def _callFUT(self, request):
-        from tutorial.views import view_page
-        return view_page(request)
-
-    def test_it(self):
-        from tutorial.models import Page
-        request = testing.DummyRequest()
-        request.matchdict['pagename'] = 'IDoExist'
-        page = Page('IDoExist', 'Hello CruelWorld IDoExist')
-        self.session.add(page)
-        _registerRoutes(self.config)
-        info = self._callFUT(request)
-        self.assertEqual(info['page'], page)
-        self.assertEqual(
-            info['content'], 
-            '<div class="document">\n'
-            '<p>Hello <a href="http://example.com/add_page/CruelWorld">'
-            'CruelWorld</a> '
-            '<a href="http://example.com/IDoExist">'
-            'IDoExist</a>'
-            '</p>\n</div>\n')
-        self.assertEqual(info['edit_url'],
-                         'http://example.com/IDoExist/edit_page')
-        
-    
-class AddPageTests(unittest.TestCase):
+class BaseTest(unittest.TestCase):
     def setUp(self):
-        self.session = _initTestingDB()
-        self.config = testing.setUp()
+        self.config = testing.setUp(settings={
+            'sqlalchemy.url': 'sqlite:///:memory:'
+        })
+        self.config.include('.models')
+        settings = self.config.get_settings()
+
+        from .models import (
+            get_engine,
+            get_session_factory,
+            get_tm_session,
+            )
+
+        self.engine = get_engine(settings)
+        session_factory = get_session_factory(self.engine)
+
+        self.session = get_tm_session(session_factory, transaction.manager)
+
+    def init_database(self):
+        from .models.meta import Base
+        Base.metadata.create_all(self.engine)
 
     def tearDown(self):
-        self.session.remove()
+        from .models.meta import Base
+
         testing.tearDown()
+        transaction.abort()
+        Base.metadata.drop_all(self.engine)
+
+
+class TestMyViewSuccessCondition(BaseTest):
 
-    def _callFUT(self, request):
-        from tutorial.views import add_page
-        return add_page(request)
-
-    def test_it_notsubmitted(self):
-        _registerRoutes(self.config)
-        request = testing.DummyRequest()
-        request.matchdict = {'pagename':'AnotherPage'}
-        info = self._callFUT(request)
-        self.assertEqual(info['page'].data,'')
-        self.assertEqual(info['save_url'],
-                         'http://example.com/add_page/AnotherPage')
-        
-    def test_it_submitted(self):
-        from tutorial.models import Page
-        _registerRoutes(self.config)
-        request = testing.DummyRequest({'form.submitted':True,
-                                        'body':'Hello yo!'})
-        request.matchdict = {'pagename':'AnotherPage'}
-        self._callFUT(request)
-        page = self.session.query(Page).filter_by(name='AnotherPage').one()
-        self.assertEqual(page.data, 'Hello yo!')
-
-class EditPageTests(unittest.TestCase):
     def setUp(self):
-        self.session = _initTestingDB()
-        self.config = testing.setUp()
+        super(TestMyViewSuccessCondition, self).setUp()
+        self.init_database()
 
-    def tearDown(self):
-        self.session.remove()
-        testing.tearDown()
+        from .models import MyModel
+
+        model = MyModel(name='one', value=55)
+        self.session.add(model)
+
+    def test_passing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info['one'].name, 'one')
+        self.assertEqual(info['project'], 'tutorial')
+
+
+class TestMyViewFailureCondition(BaseTest):
 
-    def _callFUT(self, request):
-        from tutorial.views import edit_page
-        return edit_page(request)
-
-    def test_it_notsubmitted(self):
-        from tutorial.models import Page
-        _registerRoutes(self.config)
-        request = testing.DummyRequest()
-        request.matchdict = {'pagename':'abc'}
-        page = Page('abc', 'hello')
-        self.session.add(page)
-        info = self._callFUT(request)
-        self.assertEqual(info['page'], page)
-        self.assertEqual(info['save_url'], 'http://example.com/abc/edit_page')
-        
-    def test_it_submitted(self):
-        from tutorial.models import Page
-        _registerRoutes(self.config)
-        request = testing.DummyRequest({'form.submitted':True,
-                                        'body':'Hello yo!'})
-        request.matchdict = {'pagename':'abc'}
-        page = Page('abc', 'hello')
-        self.session.add(page)
-        response = self._callFUT(request)
-        self.assertEqual(response.location, 'http://example.com/abc')
-        self.assertEqual(page.data, 'Hello yo!')
+    def test_failing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info.status_int, 500)
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/views.py b/docs/tutorials/wiki2/src/authorization/tutorial/views.py
deleted file mode 100644
index e0b84971d..000000000
--- a/docs/tutorials/wiki2/src/authorization/tutorial/views.py
+++ /dev/null
@@ -1,72 +0,0 @@
-import re
-
-from docutils.core import publish_parts
-
-from pyramid.httpexceptions import HTTPFound, HTTPNotFound
-from pyramid.security import authenticated_userid
-from pyramid.url import route_url
-
-from tutorial.models import DBSession
-from tutorial.models import Page
-
-# regular expression used to find WikiWords
-wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")
-
-def view_wiki(request):
-    return HTTPFound(location = route_url('view_page', request,
-                                          pagename='FrontPage'))
-
-def view_page(request):
-    pagename = request.matchdict['pagename']
-    session = DBSession()
-    page = session.query(Page).filter_by(name=pagename).first()
-    if page is None:
-        return HTTPNotFound('No such page')
-
-    def check(match):
-        word = match.group(1)
-        exists = session.query(Page).filter_by(name=word).all()
-        if exists:
-            view_url = route_url('view_page', request, pagename=word)
-            return '<a href="%s">%s</a>' % (view_url, word)
-        else:
-            add_url = route_url('add_page', request, pagename=word)
-            return '<a href="%s">%s</a>' % (add_url, word)
-
-    content = publish_parts(page.data, writer_name='html')['html_body']
-    content = wikiwords.sub(check, content)
-    edit_url = route_url('edit_page', request, pagename=pagename)
-    logged_in = authenticated_userid(request)
-    return dict(page=page, content=content, edit_url=edit_url,
-                logged_in=logged_in)
-
-def add_page(request):
-    name = request.matchdict['pagename']
-    if 'form.submitted' in request.params:
-        session = DBSession()
-        body = request.params['body']
-        page = Page(name, body)
-        session.add(page)
-        return HTTPFound(location = route_url('view_page', request,
-                                              pagename=name))
-    save_url = route_url('add_page', request, pagename=name)
-    page = Page('', '')
-    logged_in = authenticated_userid(request)
-    return dict(page=page, save_url=save_url, logged_in=logged_in)
-
-def edit_page(request):
-    name = request.matchdict['pagename']
-    session = DBSession()
-    page = session.query(Page).filter_by(name=name).one()
-    if 'form.submitted' in request.params:
-        page.data = request.params['body']
-        session.add(page)
-        return HTTPFound(location = route_url('view_page', request,
-                                              pagename=name))
-
-    logged_in = authenticated_userid(request)
-    return dict(
-        page=page,
-        save_url = route_url('edit_page', request, pagename=name),
-        logged_in = logged_in,
-        )
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/views/__init__.py b/docs/tutorials/wiki2/src/authorization/tutorial/views/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/views/__init__.py
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/views/auth.py b/docs/tutorials/wiki2/src/authorization/tutorial/views/auth.py
new file mode 100644
index 000000000..2b993b430
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/views/auth.py
@@ -0,0 +1,46 @@
+from pyramid.httpexceptions import HTTPFound
+from pyramid.security import (
+    remember,
+    forget,
+    )
+from pyramid.view import (
+    forbidden_view_config,
+    view_config,
+)
+
+from ..models import User
+
+
+@view_config(route_name='login', renderer='../templates/login.jinja2')
+def login(request):
+    next_url = request.params.get('next', request.referrer)
+    if not next_url:
+        next_url = request.route_url('view_wiki')
+    message = ''
+    login = ''
+    if 'form.submitted' in request.params:
+        login = request.params['login']
+        password = request.params['password']
+        user = request.dbsession.query(User).filter_by(name=login).first()
+        if user is not None and user.check_password(password):
+            headers = remember(request, user.id)
+            return HTTPFound(location=next_url, headers=headers)
+        message = 'Failed login'
+
+    return dict(
+        message=message,
+        url=request.route_url('login'),
+        next_url=next_url,
+        login=login,
+        )
+
+@view_config(route_name='logout')
+def logout(request):
+    headers = forget(request)
+    next_url = request.route_url('view_wiki')
+    return HTTPFound(location=next_url, headers=headers)
+
+@forbidden_view_config()
+def forbidden_view(request):
+    next_url = request.route_url('login', _query={'next': request.url})
+    return HTTPFound(location=next_url)
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/views/default.py b/docs/tutorials/wiki2/src/authorization/tutorial/views/default.py
new file mode 100644
index 000000000..9358993ea
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/views/default.py
@@ -0,0 +1,64 @@
+import cgi
+import re
+from docutils.core import publish_parts
+
+from pyramid.httpexceptions import HTTPFound
+from pyramid.view import view_config
+
+from ..models import Page
+
+# regular expression used to find WikiWords
+wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")
+
+@view_config(route_name='view_wiki')
+def view_wiki(request):
+    next_url = request.route_url('view_page', pagename='FrontPage')
+    return HTTPFound(location=next_url)
+
+@view_config(route_name='view_page', renderer='../templates/view.jinja2',
+             permission='view')
+def view_page(request):
+    page = request.context.page
+
+    def add_link(match):
+        word = match.group(1)
+        exists = request.dbsession.query(Page).filter_by(name=word).all()
+        if exists:
+            view_url = request.route_url('view_page', pagename=word)
+            return '<a href="%s">%s</a>' % (view_url, cgi.escape(word))
+        else:
+            add_url = request.route_url('add_page', pagename=word)
+            return '<a href="%s">%s</a>' % (add_url, cgi.escape(word))
+
+    content = publish_parts(page.data, writer_name='html')['html_body']
+    content = wikiwords.sub(add_link, content)
+    edit_url = request.route_url('edit_page', pagename=page.name)
+    return dict(page=page, content=content, edit_url=edit_url)
+
+@view_config(route_name='edit_page', renderer='../templates/edit.jinja2',
+             permission='edit')
+def edit_page(request):
+    page = request.context.page
+    if 'form.submitted' in request.params:
+        page.data = request.params['body']
+        next_url = request.route_url('view_page', pagename=page.name)
+        return HTTPFound(location=next_url)
+    return dict(
+        pagename=page.name,
+        pagedata=page.data,
+        save_url=request.route_url('edit_page', pagename=page.name),
+        )
+
+@view_config(route_name='add_page', renderer='../templates/edit.jinja2',
+             permission='create')
+def add_page(request):
+    pagename = request.context.pagename
+    if 'form.submitted' in request.params:
+        body = request.params['body']
+        page = Page(name=pagename, data=body)
+        page.creator = request.user
+        request.dbsession.add(page)
+        next_url = request.route_url('view_page', pagename=pagename)
+        return HTTPFound(location=next_url)
+    save_url = request.route_url('add_page', pagename=pagename)
+    return dict(pagename=pagename, pagedata='', save_url=save_url)
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/views/notfound.py b/docs/tutorials/wiki2/src/authorization/tutorial/views/notfound.py
new file mode 100644
index 000000000..69d6e2804
--- /dev/null
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/views/notfound.py
@@ -0,0 +1,7 @@
+from pyramid.view import notfound_view_config
+
+
+@notfound_view_config(renderer='../templates/404.jinja2')
+def notfound_view(request):
+    request.response.status = 404
+    return {}
diff --git a/docs/tutorials/wiki2/src/basiclayout/MANIFEST.in b/docs/tutorials/wiki2/src/basiclayout/MANIFEST.in
index 81beba1b1..42cd299b5 100644
--- a/docs/tutorials/wiki2/src/basiclayout/MANIFEST.in
+++ b/docs/tutorials/wiki2/src/basiclayout/MANIFEST.in
@@ -1,2 +1,2 @@
 include *.txt *.ini *.cfg *.rst
-recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml
+recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.jinja2 *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/tutorials/wiki2/src/basiclayout/README.txt b/docs/tutorials/wiki2/src/basiclayout/README.txt
index d41f7f90f..5b0101e5f 100644
--- a/docs/tutorials/wiki2/src/basiclayout/README.txt
+++ b/docs/tutorials/wiki2/src/basiclayout/README.txt
@@ -1,4 +1,14 @@
 tutorial README
+==================
 
+Getting Started
+---------------
 
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/initialize_tutorial_db development.ini
+
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/basiclayout/development.ini b/docs/tutorials/wiki2/src/basiclayout/development.ini
index 3b615f635..22b733e10 100644
--- a/docs/tutorials/wiki2/src/basiclayout/development.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/development.ini
@@ -1,32 +1,42 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = true
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = true
-default_locale_name = en
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
-
-[pipeline:main]
-pipeline =
-    egg:WebError#evalerror
-    tm
-    tutorial
-
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_tm
+
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
-host = 0.0.0.0
+use = egg:waitress#main
+host = 127.0.0.1
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
-keys = root, sqlalchemy
+keys = root, tutorial, sqlalchemy
 
 [handlers]
 keys = console
@@ -38,6 +48,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [logger_sqlalchemy]
 level = INFO
 handlers =
@@ -53,6 +68,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/basiclayout/production.ini b/docs/tutorials/wiki2/src/basiclayout/production.ini
index 0fdc38811..d2ecfe22a 100644
--- a/docs/tutorials/wiki2/src/basiclayout/production.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/production.ini
@@ -1,43 +1,28 @@
-[app:tutorial]
-use = egg:tutorial
-reload_templates = false
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = false
-default_locale_name = en
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
 
-[filter:weberror]
-use = egg:WebError#error_catcher
-debug = false
-;error_log = 
-;show_exceptions_in_wsgi_errors = true
-;smtp_server = localhost
-;error_email = janitor@example.com
-;smtp_username = janitor
-;smtp_password = "janitor's password"
-;from_address = paste@localhost
-;error_subject_prefix = "Pyramid Error"
-;smtp_use_tls =
-;error_message =
+[app:main]
+use = egg:tutorial
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
 
-[pipeline:main]
-pipeline =
-    weberror
-    tm
-    tutorial
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
-use = egg:Paste#http
+use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -72,6 +57,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/basiclayout/setup.cfg b/docs/tutorials/wiki2/src/basiclayout/setup.cfg
deleted file mode 100644
index 23b2ad983..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/setup.cfg
+++ /dev/null
@@ -1,27 +0,0 @@
-[nosetests]
-match=^test
-nocapture=1
-cover-package=tutorial
-with-coverage=1
-cover-erase=1
-
-[compile_catalog]
-directory = tutorial/locale
-domain = tutorial
-statistics = true
-
-[extract_messages]
-add_comments = TRANSLATORS:
-output_file = tutorial/locale/tutorial.pot
-width = 80
-
-[init_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-
-[update_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-previous = true
diff --git a/docs/tutorials/wiki2/src/basiclayout/setup.py b/docs/tutorials/wiki2/src/basiclayout/setup.py
index eaf1ddcfe..ede0a82ef 100644
--- a/docs/tutorials/wiki2/src/basiclayout/setup.py
+++ b/docs/tutorials/wiki2/src/basiclayout/setup.py
@@ -1,34 +1,40 @@
 import os
-import sys
 
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
+    'pyramid_jinja2',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
     'SQLAlchemy',
     'transaction',
-    'repoze.tm2>=1.0b1', # default_commit_veto
     'zope.sqlalchemy',
-    'WebError',
+    'waitress',
     ]
 
-if sys.version_info[:3] < (2,5,0):
-    requires.append('pysqlite')
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
 
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Programming Language :: Python",
-        "Framework :: Pylons",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
       author='',
       author_email='',
       url='',
@@ -36,12 +42,14 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
+      [console_scripts]
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
-      paster_plugins=['pyramid'],
       )
-
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
index c74f07652..4dab44823 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
@@ -1,18 +1,12 @@
 from pyramid.config import Configurator
-from sqlalchemy import engine_from_config
 
-from tutorial.models import initialize_sql
 
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
-    engine = engine_from_config(settings, 'sqlalchemy.')
-    initialize_sql(engine)
     config = Configurator(settings=settings)
-    config.add_static_view('static', 'tutorial:static')
-    config.add_route('home', '/')
-    config.add_view('tutorial.views.my_view', route_name='home',
-                    renderer='templates/mytemplate.pt')
+    config.include('pyramid_jinja2')
+    config.include('.models')
+    config.include('.routes')
+    config.scan()
     return config.make_wsgi_app()
-
-
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py
deleted file mode 100644
index 4fd010c5c..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py
+++ /dev/null
@@ -1,43 +0,0 @@
-import transaction
-
-from sqlalchemy import Column
-from sqlalchemy import Integer
-from sqlalchemy import Unicode
-
-from sqlalchemy.exc import IntegrityError
-from sqlalchemy.ext.declarative import declarative_base
-
-from sqlalchemy.orm import scoped_session
-from sqlalchemy.orm import sessionmaker
-
-from zope.sqlalchemy import ZopeTransactionExtension
-
-DBSession = scoped_session(sessionmaker(
-                             extension=ZopeTransactionExtension()))
-Base = declarative_base()
-
-class MyModel(Base):
-    __tablename__ = 'models'
-    id = Column(Integer, primary_key=True)
-    name = Column(Unicode(255), unique=True)
-    value = Column(Integer)
-
-    def __init__(self, name, value):
-        self.name = name
-        self.value = value
-
-def populate():
-    session = DBSession()
-    model = MyModel(name=u'root',value=55)
-    session.add(model)
-    session.flush()
-    transaction.commit()
-    
-def initialize_sql(engine):
-    DBSession.configure(bind=engine)
-    Base.metadata.bind = engine
-    Base.metadata.create_all(engine)
-    try:
-        populate()
-    except IntegrityError:
-        pass
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py
new file mode 100644
index 000000000..48a957ecb
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py
@@ -0,0 +1,73 @@
+from sqlalchemy import engine_from_config
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import configure_mappers
+import zope.sqlalchemy
+
+# import or define all models here to ensure they are attached to the
+# Base.metadata prior to any initialization routines
+from .mymodel import MyModel # flake8: noqa
+
+# run configure_mappers after defining all of the models to ensure
+# all relationships can be setup
+configure_mappers()
+
+
+def get_engine(settings, prefix='sqlalchemy.'):
+    return engine_from_config(settings, prefix)
+
+
+def get_session_factory(engine):
+    factory = sessionmaker()
+    factory.configure(bind=engine)
+    return factory
+
+
+def get_tm_session(session_factory, transaction_manager):
+    """
+    Get a ``sqlalchemy.orm.Session`` instance backed by a transaction.
+
+    This function will hook the session to the transaction manager which
+    will take care of committing any changes.
+
+    - When using pyramid_tm it will automatically be committed or aborted
+      depending on whether an exception is raised.
+
+    - When using scripts you should wrap the session in a manager yourself.
+      For example::
+
+          import transaction
+
+          engine = get_engine(settings)
+          session_factory = get_session_factory(engine)
+          with transaction.manager:
+              dbsession = get_tm_session(session_factory, transaction.manager)
+
+    """
+    dbsession = session_factory()
+    zope.sqlalchemy.register(
+        dbsession, transaction_manager=transaction_manager)
+    return dbsession
+
+
+def includeme(config):
+    """
+    Initialize the model for a Pyramid app.
+
+    Activate this setup using ``config.include('tutorial.models')``.
+
+    """
+    settings = config.get_settings()
+
+    # use pyramid_tm to hook the transaction lifecycle to the request
+    config.include('pyramid_tm')
+
+    session_factory = get_session_factory(get_engine(settings))
+    config.registry['dbsession_factory'] = session_factory
+
+    # make request.dbsession available for use in Pyramid
+    config.add_request_method(
+        # r.tm is the transaction manager used by pyramid_tm
+        lambda r: get_tm_session(session_factory, r.tm),
+        'dbsession',
+        reify=True
+    )
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/models/meta.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/meta.py
new file mode 100644
index 000000000..fc3e8f1dd
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/meta.py
@@ -0,0 +1,16 @@
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.schema import MetaData
+
+# Recommended naming convention used by Alembic, as various different database
+# providers will autogenerate vastly different names making migrations more
+# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+NAMING_CONVENTION = {
+    "ix": 'ix_%(column_0_label)s',
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s"
+}
+
+metadata = MetaData(naming_convention=NAMING_CONVENTION)
+Base = declarative_base(metadata=metadata)
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/models/mymodel.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/mymodel.py
new file mode 100644
index 000000000..d65a01a42
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/mymodel.py
@@ -0,0 +1,18 @@
+from sqlalchemy import (
+    Column,
+    Index,
+    Integer,
+    Text,
+)
+
+from .meta import Base
+
+
+class MyModel(Base):
+    __tablename__ = 'models'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text)
+    value = Column(Integer)
+
+
+Index('my_index', MyModel.name, unique=True, mysql_length=255)
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/routes.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/routes.py
new file mode 100644
index 000000000..25504ad4d
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/routes.py
@@ -0,0 +1,3 @@
+def includeme(config):
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.add_route('home', '/')
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/__init__.py
new file mode 100644
index 000000000..5bb534f79
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/__init__.py
@@ -0,0 +1 @@
+# package
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py
new file mode 100644
index 000000000..7307ecc5c
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py
@@ -0,0 +1,45 @@
+import os
+import sys
+import transaction
+
+from pyramid.paster import (
+    get_appsettings,
+    setup_logging,
+    )
+
+from pyramid.scripts.common import parse_vars
+
+from ..models.meta import Base
+from ..models import (
+    get_engine,
+    get_session_factory,
+    get_tm_session,
+    )
+from ..models import MyModel
+
+
+def usage(argv):
+    cmd = os.path.basename(argv[0])
+    print('usage: %s <config_uri> [var=value]\n'
+          '(example: "%s development.ini")' % (cmd, cmd))
+    sys.exit(1)
+
+
+def main(argv=sys.argv):
+    if len(argv) < 2:
+        usage(argv)
+    config_uri = argv[1]
+    options = parse_vars(argv[2:])
+    setup_logging(config_uri)
+    settings = get_appsettings(config_uri, options=options)
+
+    engine = get_engine(settings)
+    Base.metadata.create_all(engine)
+
+    session_factory = get_session_factory(engine)
+
+    with transaction.manager:
+        dbsession = get_tm_session(session_factory, transaction.manager)
+
+        model = MyModel(name='one', value=1)
+        dbsession.add(model)
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/favicon.ico b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/favicon.ico
deleted file mode 100644
index 71f837c9e..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/favicon.ico
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/footerbg.png b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/footerbg.png
deleted file mode 100644
index 1fbc873da..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/footerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/headerbg.png b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/headerbg.png
deleted file mode 100644
index 0596f2020..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/headerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/ie6.css b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/ie6.css
deleted file mode 100644
index b7c8493d8..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/ie6.css
+++ /dev/null
@@ -1,8 +0,0 @@
-* html img,
-* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
-this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
-this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
-);}
-#wrap{display:table;height:100%}
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/middlebg.png b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/middlebg.png
deleted file mode 100644
index 2369cfb7d..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/middlebg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pylons.css b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pylons.css
deleted file mode 100644
index fd1914d8d..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pylons.css
+++ /dev/null
@@ -1,65 +0,0 @@
-html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */
-vertical-align:baseline;background:transparent;}
-body{line-height:1;}
-ol,ul{list-style:none;}
-blockquote,q{quotes:none;}
-blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;}
-:focus{outline:0;}
-ins{text-decoration:none;}
-del{text-decoration:line-through;}
-table{border-collapse:collapse;border-spacing:0;}
-sub{vertical-align:sub;font-size:smaller;line-height:normal;}
-sup{vertical-align:super;font-size:smaller;line-height:normal;}
-ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;}
-ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;}
-li{display:list-item;}
-ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;}
-ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;}
-ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;}
-.hidden{display:none;}
-p{line-height:1.5em;}
-h1{font-size:1.75em;line-height:1.7em;font-family:helvetica,verdana;}
-h2{font-size:1.5em;line-height:1.7em;font-family:helvetica,verdana;}
-h3{font-size:1.25em;line-height:1.7em;font-family:helvetica,verdana;}
-h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;}
-html,body{width:100%;height:100%;}
-body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;}
-a{color:#1b61d6;text-decoration:none;}
-a:hover{color:#e88f00;text-decoration:underline;}
-body h1,
-body h2,
-body h3,
-body h4,
-body h5,
-body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;}
-#wrap{min-height:100%;}
-#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;}
-#header{background:#000000;top:0;font-size:14px;}
-#footer{bottom:0;background:#000000 url(footerbg.png) repeat-x 0 top;position:relative;margin-top:-40px;clear:both;}
-.header,.footer{width:750px;margin-right:auto;margin-left:auto;}
-.wrapper{width:100%}
-#top,#top-small,#bottom{width:100%;}
-#top{color:#000000;height:230px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#top-small{color:#000000;height:60px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#bottom{color:#222;background-color:#ffffff;}
-.top,.top-small,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;}
-.top{padding-top:40px;}
-.top-small{padding-top:10px;}
-#middle{width:100%;height:100px;background:url(middlebg.png) repeat-x;border-top:2px solid #ffffff;border-bottom:2px solid #b2b2b2;}
-.app-welcome{margin-top:25px;}
-.app-name{color:#000000;font-weight:bold;}
-.bottom{padding-top:50px;}
-#left{width:350px;float:left;padding-right:25px;}
-#right{width:350px;float:right;padding-left:25px;}
-.align-left{text-align:left;}
-.align-right{text-align:right;}
-.align-center{text-align:center;}
-ul.links{margin:0;padding:0;}
-ul.links li{list-style-type:none;font-size:14px;}
-form{border-style:none;}
-fieldset{border-style:none;}
-input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;}
-input[type=text],input[type=password]{width:205px;}
-input[type=submit]{background-color:#ddd;font-weight:bold;}
-/*Opera Fix*/
-body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;}
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pyramid-small.png b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pyramid-small.png
deleted file mode 100644
index a5bc0ade7..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pyramid-small.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pyramid.png b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pyramid.png
index 347e05549..4ab837be9 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pyramid.png
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/theme.css b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/transparent.gif b/docs/tutorials/wiki2/src/basiclayout/tutorial/static/transparent.gif
deleted file mode 100644
index 0341802e5..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/static/transparent.gif
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/404.jinja2 b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/404.jinja2
new file mode 100644
index 000000000..1917f83c7
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/404.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Alchemy scaffold</span></h1>
+  <p class="lead"><span class="font-semi-bold">404</span> Page Not Found</p>
+</div>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/layout.jinja2 b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/layout.jinja2
new file mode 100644
index 000000000..ab8c5ea3d
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/layout.jinja2
@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html lang="{{request.locale_name}}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="{{request.static_url('tutorial:static/pyramid-16x16.png')}}">
+
+    <title>Alchemy Scaffold for The Pyramid Web Framework</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="{{request.static_url('tutorial:static/theme.css')}}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="{{request.static_url('tutorial:static/pyramid.png')}}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            {% block content %}
+                <p>No content</p>
+            {% endblock content %}
+          </div>
+        </div>
+        <div class="row">
+          <div class="links">
+            <ul>
+              <li class="current-version">Generated by v1.7</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
+              <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
+              <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
+              <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
+            </ul>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.jinja2 b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.jinja2
new file mode 100644
index 000000000..6b49869c4
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Alchemy scaffold</span></h1>
+  <p class="lead">Welcome to <span class="font-normal">{{project}}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7</span>.</p>
+</div>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt
deleted file mode 100644
index d98420680..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt
+++ /dev/null
@@ -1,75 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>The Pyramid Web Application Development Framework</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon" href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
-  <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton|Nobile:regular,i,b,bi&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top">
-      <div class="top align-center">
-        <div><img src="${request.static_url('tutorial:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-center">
-        <p class="app-welcome">
-          Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web application development framework.
-        </p>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div id="left" class="align-right">
-          <h2>Search documentation</h2>
-          <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/dev/search.html">
-                <input type="text" id="q" name="q" value="" />
-                <input type="submit" id="x" value="Go" />
-            </form>
-        </div>
-        <div id="right" class="align-left">
-          <h2>Pyramid links</h2>
-          <ul class="links">
-            <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#narrative-documentation">Narrative Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#api-documentation">API Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#tutorials">Tutorials</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#change-history">Change History</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#sample-applications">Sample Applications</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#support-and-development">Support and Development</a>
-            </li>
-            <li>
-              <a href="irc://irc.freenode.net#pyramid">IRC Channel</a>
-            </li>
-            </ul>
-        </div>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
-</html>
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
index 5efa6affa..99e95efd3 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
@@ -1,23 +1,65 @@
 import unittest
+import transaction
+
 from pyramid import testing
 
-def _initTestingDB():
-    from sqlalchemy import create_engine
-    from tutorial.models import initialize_sql
-    session = initialize_sql(create_engine('sqlite://'))
-    return session
 
-class TestMyView(unittest.TestCase):
+def dummy_request(dbsession):
+    return testing.DummyRequest(dbsession=dbsession)
+
+
+class BaseTest(unittest.TestCase):
     def setUp(self):
-        self.config = testing.setUp()
-        _initTestingDB()
+        self.config = testing.setUp(settings={
+            'sqlalchemy.url': 'sqlite:///:memory:'
+        })
+        self.config.include('.models')
+        settings = self.config.get_settings()
+
+        from .models import (
+            get_engine,
+            get_session_factory,
+            get_tm_session,
+            )
+
+        self.engine = get_engine(settings)
+        session_factory = get_session_factory(self.engine)
+
+        self.session = get_tm_session(session_factory, transaction.manager)
+
+    def init_database(self):
+        from .models.meta import Base
+        Base.metadata.create_all(self.engine)
 
     def tearDown(self):
+        from .models.meta import Base
+
         testing.tearDown()
+        transaction.abort()
+        Base.metadata.drop_all(self.engine)
+
 
-    def test_it(self):
-        from tutorial.views import my_view
-        request = testing.DummyRequest()
-        info = my_view(request)
-        self.assertEqual(info['root'].name, 'root')
+class TestMyViewSuccessCondition(BaseTest):
+
+    def setUp(self):
+        super(TestMyViewSuccessCondition, self).setUp()
+        self.init_database()
+
+        from .models import MyModel
+
+        model = MyModel(name='one', value=55)
+        self.session.add(model)
+
+    def test_passing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info['one'].name, 'one')
         self.assertEqual(info['project'], 'tutorial')
+
+
+class TestMyViewFailureCondition(BaseTest):
+
+    def test_failing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info.status_int, 500)
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
deleted file mode 100644
index e550e3257..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
+++ /dev/null
@@ -1,7 +0,0 @@
-from tutorial.models import DBSession
-from tutorial.models import MyModel
-
-def my_view(request):
-    dbsession = DBSession()
-    root = dbsession.query(MyModel).filter(MyModel.name==u'root').first()
-    return {'root':root, 'project':'tutorial'}
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/views/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/views/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/views/__init__.py
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/views/default.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/views/default.py
new file mode 100644
index 000000000..ad0c728d7
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/views/default.py
@@ -0,0 +1,33 @@
+from pyramid.response import Response
+from pyramid.view import view_config
+
+from sqlalchemy.exc import DBAPIError
+
+from ..models import MyModel
+
+
+@view_config(route_name='home', renderer='../templates/mytemplate.jinja2')
+def my_view(request):
+    try:
+        query = request.dbsession.query(MyModel)
+        one = query.filter(MyModel.name == 'one').first()
+    except DBAPIError:
+        return Response(db_err_msg, content_type='text/plain', status=500)
+    return {'one': one, 'project': 'tutorial'}
+
+
+db_err_msg = """\
+Pyramid is having a problem using your SQL database.  The problem
+might be caused by one of the following things:
+
+1.  You may need to run the "initialize_tutorial_db" script
+    to initialize your database tables.  Check your virtual
+    environment's "bin" directory for this script and try to run it.
+
+2.  Your database server may not be running.  Check that the
+    database server referred to by the "sqlalchemy.url" setting in
+    your "development.ini" file is running.
+
+After you fix the problem, please restart the Pyramid application to
+try it again.
+"""
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/views/notfound.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/views/notfound.py
new file mode 100644
index 000000000..69d6e2804
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/views/notfound.py
@@ -0,0 +1,7 @@
+from pyramid.view import notfound_view_config
+
+
+@notfound_view_config(renderer='../templates/404.jinja2')
+def notfound_view(request):
+    request.response.status = 404
+    return {}
diff --git a/docs/tutorials/wiki2/src/installation/CHANGES.txt b/docs/tutorials/wiki2/src/installation/CHANGES.txt
new file mode 100644
index 000000000..35a34f332
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/CHANGES.txt
@@ -0,0 +1,4 @@
+0.0
+---
+
+-  Initial version
diff --git a/docs/tutorials/wiki2/src/installation/MANIFEST.in b/docs/tutorials/wiki2/src/installation/MANIFEST.in
new file mode 100644
index 000000000..42cd299b5
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/MANIFEST.in
@@ -0,0 +1,2 @@
+include *.txt *.ini *.cfg *.rst
+recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.jinja2 *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/tutorials/wiki2/src/installation/README.txt b/docs/tutorials/wiki2/src/installation/README.txt
new file mode 100644
index 000000000..5b0101e5f
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/README.txt
@@ -0,0 +1,14 @@
+tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/initialize_tutorial_db development.ini
+
+- $VENV/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/installation/development.ini b/docs/tutorials/wiki2/src/installation/development.ini
new file mode 100644
index 000000000..22b733e10
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/development.ini
@@ -0,0 +1,71 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_tm
+
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
+[server:main]
+use = egg:waitress#main
+host = 127.0.0.1
+port = 6543
+
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial, sqlalchemy
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
+[logger_sqlalchemy]
+level = INFO
+handlers =
+qualname = sqlalchemy.engine
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARN" logs neither.  (Recommended for production systems.)
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/installation/production.ini b/docs/tutorials/wiki2/src/installation/production.ini
new file mode 100644
index 000000000..d2ecfe22a
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/production.ini
@@ -0,0 +1,60 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
+
+[server:main]
+use = egg:waitress#main
+host = 0.0.0.0
+port = 6543
+
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial, sqlalchemy
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_tutorial]
+level = WARN
+handlers =
+qualname = tutorial
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARN" logs neither.  (Recommended for production systems.)
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/installation/setup.py b/docs/tutorials/wiki2/src/installation/setup.py
new file mode 100644
index 000000000..ede0a82ef
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/setup.py
@@ -0,0 +1,55 @@
+import os
+
+from setuptools import setup, find_packages
+
+here = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
+
+requires = [
+    'pyramid',
+    'pyramid_jinja2',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
+    'SQLAlchemy',
+    'transaction',
+    'zope.sqlalchemy',
+    'waitress',
+    ]
+
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
+
+setup(name='tutorial',
+      version='0.0',
+      description='tutorial',
+      long_description=README + '\n\n' + CHANGES,
+      classifiers=[
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
+      author='',
+      author_email='',
+      url='',
+      keywords='web wsgi bfg pylons pyramid',
+      packages=find_packages(),
+      include_package_data=True,
+      zip_safe=False,
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
+      [paste.app_factory]
+      main = tutorial:main
+      [console_scripts]
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
+      """,
+      )
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/__init__.py b/docs/tutorials/wiki2/src/installation/tutorial/__init__.py
new file mode 100644
index 000000000..4dab44823
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/__init__.py
@@ -0,0 +1,12 @@
+from pyramid.config import Configurator
+
+
+def main(global_config, **settings):
+    """ This function returns a Pyramid WSGI application.
+    """
+    config = Configurator(settings=settings)
+    config.include('pyramid_jinja2')
+    config.include('.models')
+    config.include('.routes')
+    config.scan()
+    return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py
new file mode 100644
index 000000000..48a957ecb
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py
@@ -0,0 +1,73 @@
+from sqlalchemy import engine_from_config
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import configure_mappers
+import zope.sqlalchemy
+
+# import or define all models here to ensure they are attached to the
+# Base.metadata prior to any initialization routines
+from .mymodel import MyModel # flake8: noqa
+
+# run configure_mappers after defining all of the models to ensure
+# all relationships can be setup
+configure_mappers()
+
+
+def get_engine(settings, prefix='sqlalchemy.'):
+    return engine_from_config(settings, prefix)
+
+
+def get_session_factory(engine):
+    factory = sessionmaker()
+    factory.configure(bind=engine)
+    return factory
+
+
+def get_tm_session(session_factory, transaction_manager):
+    """
+    Get a ``sqlalchemy.orm.Session`` instance backed by a transaction.
+
+    This function will hook the session to the transaction manager which
+    will take care of committing any changes.
+
+    - When using pyramid_tm it will automatically be committed or aborted
+      depending on whether an exception is raised.
+
+    - When using scripts you should wrap the session in a manager yourself.
+      For example::
+
+          import transaction
+
+          engine = get_engine(settings)
+          session_factory = get_session_factory(engine)
+          with transaction.manager:
+              dbsession = get_tm_session(session_factory, transaction.manager)
+
+    """
+    dbsession = session_factory()
+    zope.sqlalchemy.register(
+        dbsession, transaction_manager=transaction_manager)
+    return dbsession
+
+
+def includeme(config):
+    """
+    Initialize the model for a Pyramid app.
+
+    Activate this setup using ``config.include('tutorial.models')``.
+
+    """
+    settings = config.get_settings()
+
+    # use pyramid_tm to hook the transaction lifecycle to the request
+    config.include('pyramid_tm')
+
+    session_factory = get_session_factory(get_engine(settings))
+    config.registry['dbsession_factory'] = session_factory
+
+    # make request.dbsession available for use in Pyramid
+    config.add_request_method(
+        # r.tm is the transaction manager used by pyramid_tm
+        lambda r: get_tm_session(session_factory, r.tm),
+        'dbsession',
+        reify=True
+    )
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/models/meta.py b/docs/tutorials/wiki2/src/installation/tutorial/models/meta.py
new file mode 100644
index 000000000..fc3e8f1dd
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/models/meta.py
@@ -0,0 +1,16 @@
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.schema import MetaData
+
+# Recommended naming convention used by Alembic, as various different database
+# providers will autogenerate vastly different names making migrations more
+# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+NAMING_CONVENTION = {
+    "ix": 'ix_%(column_0_label)s',
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s"
+}
+
+metadata = MetaData(naming_convention=NAMING_CONVENTION)
+Base = declarative_base(metadata=metadata)
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/models/mymodel.py b/docs/tutorials/wiki2/src/installation/tutorial/models/mymodel.py
new file mode 100644
index 000000000..d65a01a42
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/models/mymodel.py
@@ -0,0 +1,18 @@
+from sqlalchemy import (
+    Column,
+    Index,
+    Integer,
+    Text,
+)
+
+from .meta import Base
+
+
+class MyModel(Base):
+    __tablename__ = 'models'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text)
+    value = Column(Integer)
+
+
+Index('my_index', MyModel.name, unique=True, mysql_length=255)
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/routes.py b/docs/tutorials/wiki2/src/installation/tutorial/routes.py
new file mode 100644
index 000000000..25504ad4d
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/routes.py
@@ -0,0 +1,3 @@
+def includeme(config):
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.add_route('home', '/')
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/scripts/__init__.py b/docs/tutorials/wiki2/src/installation/tutorial/scripts/__init__.py
new file mode 100644
index 000000000..5bb534f79
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/scripts/__init__.py
@@ -0,0 +1 @@
+# package
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/installation/tutorial/scripts/initializedb.py
new file mode 100644
index 000000000..7307ecc5c
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/scripts/initializedb.py
@@ -0,0 +1,45 @@
+import os
+import sys
+import transaction
+
+from pyramid.paster import (
+    get_appsettings,
+    setup_logging,
+    )
+
+from pyramid.scripts.common import parse_vars
+
+from ..models.meta import Base
+from ..models import (
+    get_engine,
+    get_session_factory,
+    get_tm_session,
+    )
+from ..models import MyModel
+
+
+def usage(argv):
+    cmd = os.path.basename(argv[0])
+    print('usage: %s <config_uri> [var=value]\n'
+          '(example: "%s development.ini")' % (cmd, cmd))
+    sys.exit(1)
+
+
+def main(argv=sys.argv):
+    if len(argv) < 2:
+        usage(argv)
+    config_uri = argv[1]
+    options = parse_vars(argv[2:])
+    setup_logging(config_uri)
+    settings = get_appsettings(config_uri, options=options)
+
+    engine = get_engine(settings)
+    Base.metadata.create_all(engine)
+
+    session_factory = get_session_factory(engine)
+
+    with transaction.manager:
+        dbsession = get_tm_session(session_factory, transaction.manager)
+
+        model = MyModel(name='one', value=1)
+        dbsession.add(model)
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki2/src/installation/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/static/pyramid.png b/docs/tutorials/wiki2/src/installation/tutorial/static/pyramid.png
new file mode 100644
index 000000000..4ab837be9
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/static/theme.css b/docs/tutorials/wiki2/src/installation/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/templates/404.jinja2 b/docs/tutorials/wiki2/src/installation/tutorial/templates/404.jinja2
new file mode 100644
index 000000000..1917f83c7
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/templates/404.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Alchemy scaffold</span></h1>
+  <p class="lead"><span class="font-semi-bold">404</span> Page Not Found</p>
+</div>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/templates/layout.jinja2 b/docs/tutorials/wiki2/src/installation/tutorial/templates/layout.jinja2
new file mode 100644
index 000000000..ab8c5ea3d
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/templates/layout.jinja2
@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html lang="{{request.locale_name}}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="{{request.static_url('tutorial:static/pyramid-16x16.png')}}">
+
+    <title>Alchemy Scaffold for The Pyramid Web Framework</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="{{request.static_url('tutorial:static/theme.css')}}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="{{request.static_url('tutorial:static/pyramid.png')}}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            {% block content %}
+                <p>No content</p>
+            {% endblock content %}
+          </div>
+        </div>
+        <div class="row">
+          <div class="links">
+            <ul>
+              <li class="current-version">Generated by v1.7</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
+              <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
+              <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
+              <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
+            </ul>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/templates/mytemplate.jinja2 b/docs/tutorials/wiki2/src/installation/tutorial/templates/mytemplate.jinja2
new file mode 100644
index 000000000..6b49869c4
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/templates/mytemplate.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Alchemy scaffold</span></h1>
+  <p class="lead">Welcome to <span class="font-normal">{{project}}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7</span>.</p>
+</div>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/tests.py b/docs/tutorials/wiki2/src/installation/tutorial/tests.py
new file mode 100644
index 000000000..99e95efd3
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/tests.py
@@ -0,0 +1,65 @@
+import unittest
+import transaction
+
+from pyramid import testing
+
+
+def dummy_request(dbsession):
+    return testing.DummyRequest(dbsession=dbsession)
+
+
+class BaseTest(unittest.TestCase):
+    def setUp(self):
+        self.config = testing.setUp(settings={
+            'sqlalchemy.url': 'sqlite:///:memory:'
+        })
+        self.config.include('.models')
+        settings = self.config.get_settings()
+
+        from .models import (
+            get_engine,
+            get_session_factory,
+            get_tm_session,
+            )
+
+        self.engine = get_engine(settings)
+        session_factory = get_session_factory(self.engine)
+
+        self.session = get_tm_session(session_factory, transaction.manager)
+
+    def init_database(self):
+        from .models.meta import Base
+        Base.metadata.create_all(self.engine)
+
+    def tearDown(self):
+        from .models.meta import Base
+
+        testing.tearDown()
+        transaction.abort()
+        Base.metadata.drop_all(self.engine)
+
+
+class TestMyViewSuccessCondition(BaseTest):
+
+    def setUp(self):
+        super(TestMyViewSuccessCondition, self).setUp()
+        self.init_database()
+
+        from .models import MyModel
+
+        model = MyModel(name='one', value=55)
+        self.session.add(model)
+
+    def test_passing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info['one'].name, 'one')
+        self.assertEqual(info['project'], 'tutorial')
+
+
+class TestMyViewFailureCondition(BaseTest):
+
+    def test_failing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info.status_int, 500)
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/views/__init__.py b/docs/tutorials/wiki2/src/installation/tutorial/views/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/views/__init__.py
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/views/default.py b/docs/tutorials/wiki2/src/installation/tutorial/views/default.py
new file mode 100644
index 000000000..ad0c728d7
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/views/default.py
@@ -0,0 +1,33 @@
+from pyramid.response import Response
+from pyramid.view import view_config
+
+from sqlalchemy.exc import DBAPIError
+
+from ..models import MyModel
+
+
+@view_config(route_name='home', renderer='../templates/mytemplate.jinja2')
+def my_view(request):
+    try:
+        query = request.dbsession.query(MyModel)
+        one = query.filter(MyModel.name == 'one').first()
+    except DBAPIError:
+        return Response(db_err_msg, content_type='text/plain', status=500)
+    return {'one': one, 'project': 'tutorial'}
+
+
+db_err_msg = """\
+Pyramid is having a problem using your SQL database.  The problem
+might be caused by one of the following things:
+
+1.  You may need to run the "initialize_tutorial_db" script
+    to initialize your database tables.  Check your virtual
+    environment's "bin" directory for this script and try to run it.
+
+2.  Your database server may not be running.  Check that the
+    database server referred to by the "sqlalchemy.url" setting in
+    your "development.ini" file is running.
+
+After you fix the problem, please restart the Pyramid application to
+try it again.
+"""
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/views/notfound.py b/docs/tutorials/wiki2/src/installation/tutorial/views/notfound.py
new file mode 100644
index 000000000..69d6e2804
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tutorial/views/notfound.py
@@ -0,0 +1,7 @@
+from pyramid.view import notfound_view_config
+
+
+@notfound_view_config(renderer='../templates/404.jinja2')
+def notfound_view(request):
+    request.response.status = 404
+    return {}
diff --git a/docs/tutorials/wiki2/src/models/MANIFEST.in b/docs/tutorials/wiki2/src/models/MANIFEST.in
index 81beba1b1..42cd299b5 100644
--- a/docs/tutorials/wiki2/src/models/MANIFEST.in
+++ b/docs/tutorials/wiki2/src/models/MANIFEST.in
@@ -1,2 +1,2 @@
 include *.txt *.ini *.cfg *.rst
-recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml
+recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.jinja2 *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/tutorials/wiki2/src/models/README.txt b/docs/tutorials/wiki2/src/models/README.txt
index d41f7f90f..5b0101e5f 100644
--- a/docs/tutorials/wiki2/src/models/README.txt
+++ b/docs/tutorials/wiki2/src/models/README.txt
@@ -1,4 +1,14 @@
 tutorial README
+==================
 
+Getting Started
+---------------
 
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/initialize_tutorial_db development.ini
+
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/models/development.ini b/docs/tutorials/wiki2/src/models/development.ini
index 3b615f635..22b733e10 100644
--- a/docs/tutorials/wiki2/src/models/development.ini
+++ b/docs/tutorials/wiki2/src/models/development.ini
@@ -1,32 +1,42 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = true
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = true
-default_locale_name = en
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
-
-[pipeline:main]
-pipeline =
-    egg:WebError#evalerror
-    tm
-    tutorial
-
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_tm
+
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
-host = 0.0.0.0
+use = egg:waitress#main
+host = 127.0.0.1
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
-keys = root, sqlalchemy
+keys = root, tutorial, sqlalchemy
 
 [handlers]
 keys = console
@@ -38,6 +48,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [logger_sqlalchemy]
 level = INFO
 handlers =
@@ -53,6 +68,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/models/production.ini b/docs/tutorials/wiki2/src/models/production.ini
index 0fdc38811..d2ecfe22a 100644
--- a/docs/tutorials/wiki2/src/models/production.ini
+++ b/docs/tutorials/wiki2/src/models/production.ini
@@ -1,43 +1,28 @@
-[app:tutorial]
-use = egg:tutorial
-reload_templates = false
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = false
-default_locale_name = en
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
 
-[filter:weberror]
-use = egg:WebError#error_catcher
-debug = false
-;error_log = 
-;show_exceptions_in_wsgi_errors = true
-;smtp_server = localhost
-;error_email = janitor@example.com
-;smtp_username = janitor
-;smtp_password = "janitor's password"
-;from_address = paste@localhost
-;error_subject_prefix = "Pyramid Error"
-;smtp_use_tls =
-;error_message =
+[app:main]
+use = egg:tutorial
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
 
-[pipeline:main]
-pipeline =
-    weberror
-    tm
-    tutorial
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
-use = egg:Paste#http
+use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -72,6 +57,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/models/setup.cfg b/docs/tutorials/wiki2/src/models/setup.cfg
deleted file mode 100644
index 23b2ad983..000000000
--- a/docs/tutorials/wiki2/src/models/setup.cfg
+++ /dev/null
@@ -1,27 +0,0 @@
-[nosetests]
-match=^test
-nocapture=1
-cover-package=tutorial
-with-coverage=1
-cover-erase=1
-
-[compile_catalog]
-directory = tutorial/locale
-domain = tutorial
-statistics = true
-
-[extract_messages]
-add_comments = TRANSLATORS:
-output_file = tutorial/locale/tutorial.pot
-width = 80
-
-[init_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-
-[update_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-previous = true
diff --git a/docs/tutorials/wiki2/src/models/setup.py b/docs/tutorials/wiki2/src/models/setup.py
index eaf1ddcfe..742a7c59c 100644
--- a/docs/tutorials/wiki2/src/models/setup.py
+++ b/docs/tutorials/wiki2/src/models/setup.py
@@ -1,34 +1,41 @@
 import os
-import sys
 
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
+    'bcrypt',
     'pyramid',
+    'pyramid_jinja2',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
     'SQLAlchemy',
     'transaction',
-    'repoze.tm2>=1.0b1', # default_commit_veto
     'zope.sqlalchemy',
-    'WebError',
+    'waitress',
     ]
 
-if sys.version_info[:3] < (2,5,0):
-    requires.append('pysqlite')
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
 
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Programming Language :: Python",
-        "Framework :: Pylons",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
       author='',
       author_email='',
       url='',
@@ -36,12 +43,14 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
+      [console_scripts]
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
-      paster_plugins=['pyramid'],
       )
-
diff --git a/docs/tutorials/wiki2/src/models/tutorial/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
index ecc41ca9f..4dab44823 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
@@ -1,16 +1,12 @@
 from pyramid.config import Configurator
-from sqlalchemy import engine_from_config
 
-from tutorial.models import initialize_sql
 
 def main(global_config, **settings):
-    """ This function returns a WSGI application.
+    """ This function returns a Pyramid WSGI application.
     """
-    engine = engine_from_config(settings, 'sqlalchemy.')
-    initialize_sql(engine)
     config = Configurator(settings=settings)
-    config.add_static_view('static', 'tutorial:static')
-    config.add_route('home', '/')
-    config.add_view('tutorial.views.my_view', route_name='home',
-                    renderer='templates/mytemplate.pt')
+    config.include('pyramid_jinja2')
+    config.include('.models')
+    config.include('.routes')
+    config.scan()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models.py b/docs/tutorials/wiki2/src/models/tutorial/models.py
deleted file mode 100644
index ecc8d567b..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/models.py
+++ /dev/null
@@ -1,42 +0,0 @@
-import transaction
-
-from sqlalchemy import Column
-from sqlalchemy import Integer
-from sqlalchemy import Text
-
-from sqlalchemy.exc import IntegrityError
-from sqlalchemy.ext.declarative import declarative_base
-
-from sqlalchemy.orm import scoped_session
-from sqlalchemy.orm import sessionmaker
-
-from zope.sqlalchemy import ZopeTransactionExtension
-
-DBSession = scoped_session(sessionmaker(
-                             extension=ZopeTransactionExtension()))
-Base = declarative_base()
-
-class Page(Base):
-    """ The SQLAlchemy declarative model class for a Page object. """
-    __tablename__ = 'pages'
-    id = Column(Integer, primary_key=True)
-    name = Column(Text, unique=True)
-    data = Column(Text)
-
-    def __init__(self, name, data):
-        self.name = name
-        self.data = data
-
-def initialize_sql(engine):
-    DBSession.configure(bind=engine)
-    Base.metadata.bind = engine
-    Base.metadata.create_all(engine)
-    try:
-        transaction.begin()
-        session = DBSession()
-        page = Page('FrontPage', 'This is the front page')
-        session.add(page)
-        transaction.commit()
-    except IntegrityError:
-        # already created
-        pass
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py
new file mode 100644
index 000000000..a8871f6f5
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py
@@ -0,0 +1,74 @@
+from sqlalchemy import engine_from_config
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import configure_mappers
+import zope.sqlalchemy
+
+# import or define all models here to ensure they are attached to the
+# Base.metadata prior to any initialization routines
+from .page import Page # flake8: noqa
+from .user import User # flake8: noqa
+
+# run configure_mappers after defining all of the models to ensure
+# all relationships can be setup
+configure_mappers()
+
+
+def get_engine(settings, prefix='sqlalchemy.'):
+    return engine_from_config(settings, prefix)
+
+
+def get_session_factory(engine):
+    factory = sessionmaker()
+    factory.configure(bind=engine)
+    return factory
+
+
+def get_tm_session(session_factory, transaction_manager):
+    """
+    Get a ``sqlalchemy.orm.Session`` instance backed by a transaction.
+
+    This function will hook the session to the transaction manager which
+    will take care of committing any changes.
+
+    - When using pyramid_tm it will automatically be committed or aborted
+      depending on whether an exception is raised.
+
+    - When using scripts you should wrap the session in a manager yourself.
+      For example::
+
+          import transaction
+
+          engine = get_engine(settings)
+          session_factory = get_session_factory(engine)
+          with transaction.manager:
+              dbsession = get_tm_session(session_factory, transaction.manager)
+
+    """
+    dbsession = session_factory()
+    zope.sqlalchemy.register(
+        dbsession, transaction_manager=transaction_manager)
+    return dbsession
+
+
+def includeme(config):
+    """
+    Initialize the model for a Pyramid app.
+
+    Activate this setup using ``config.include('tutorial.models')``.
+
+    """
+    settings = config.get_settings()
+
+    # use pyramid_tm to hook the transaction lifecycle to the request
+    config.include('pyramid_tm')
+
+    session_factory = get_session_factory(get_engine(settings))
+    config.registry['dbsession_factory'] = session_factory
+
+    # make request.dbsession available for use in Pyramid
+    config.add_request_method(
+        # r.tm is the transaction manager used by pyramid_tm
+        lambda r: get_tm_session(session_factory, r.tm),
+        'dbsession',
+        reify=True
+    )
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models/meta.py b/docs/tutorials/wiki2/src/models/tutorial/models/meta.py
new file mode 100644
index 000000000..fc3e8f1dd
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/models/meta.py
@@ -0,0 +1,16 @@
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.schema import MetaData
+
+# Recommended naming convention used by Alembic, as various different database
+# providers will autogenerate vastly different names making migrations more
+# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+NAMING_CONVENTION = {
+    "ix": 'ix_%(column_0_label)s',
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s"
+}
+
+metadata = MetaData(naming_convention=NAMING_CONVENTION)
+Base = declarative_base(metadata=metadata)
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models/page.py b/docs/tutorials/wiki2/src/models/tutorial/models/page.py
new file mode 100644
index 000000000..4dd5b5721
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/models/page.py
@@ -0,0 +1,20 @@
+from sqlalchemy import (
+    Column,
+    ForeignKey,
+    Integer,
+    Text,
+)
+from sqlalchemy.orm import relationship
+
+from .meta import Base
+
+
+class Page(Base):
+    """ The SQLAlchemy declarative model class for a Page object. """
+    __tablename__ = 'pages'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text, nullable=False, unique=True)
+    data = Column(Integer, nullable=False)
+
+    creator_id = Column(ForeignKey('users.id'), nullable=False)
+    creator = relationship('User', backref='created_pages')
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models/user.py b/docs/tutorials/wiki2/src/models/tutorial/models/user.py
new file mode 100644
index 000000000..6bd3315d6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/models/user.py
@@ -0,0 +1,29 @@
+import bcrypt
+from sqlalchemy import (
+    Column,
+    Integer,
+    Text,
+)
+
+from .meta import Base
+
+
+class User(Base):
+    """ The SQLAlchemy declarative model class for a User object. """
+    __tablename__ = 'users'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text, nullable=False, unique=True)
+    role = Column(Text, nullable=False)
+
+    password_hash = Column(Text)
+
+    def set_password(self, pw):
+        pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
+        self.password_hash = pwhash
+
+    def check_password(self, pw):
+        if self.password_hash is not None:
+            expected_hash = self.password_hash
+            actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
+            return expected_hash == actual_hash
+        return False
diff --git a/docs/tutorials/wiki2/src/models/tutorial/routes.py b/docs/tutorials/wiki2/src/models/tutorial/routes.py
new file mode 100644
index 000000000..25504ad4d
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/routes.py
@@ -0,0 +1,3 @@
+def includeme(config):
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.add_route('home', '/')
diff --git a/docs/tutorials/wiki2/src/models/tutorial/scripts/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/scripts/__init__.py
new file mode 100644
index 000000000..5bb534f79
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/scripts/__init__.py
@@ -0,0 +1 @@
+# package
diff --git a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
new file mode 100644
index 000000000..f3c0a6fef
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
@@ -0,0 +1,57 @@
+import os
+import sys
+import transaction
+
+from pyramid.paster import (
+    get_appsettings,
+    setup_logging,
+    )
+
+from pyramid.scripts.common import parse_vars
+
+from ..models.meta import Base
+from ..models import (
+    get_engine,
+    get_session_factory,
+    get_tm_session,
+    )
+from ..models import Page, User
+
+
+def usage(argv):
+    cmd = os.path.basename(argv[0])
+    print('usage: %s <config_uri> [var=value]\n'
+          '(example: "%s development.ini")' % (cmd, cmd))
+    sys.exit(1)
+
+
+def main(argv=sys.argv):
+    if len(argv) < 2:
+        usage(argv)
+    config_uri = argv[1]
+    options = parse_vars(argv[2:])
+    setup_logging(config_uri)
+    settings = get_appsettings(config_uri, options=options)
+
+    engine = get_engine(settings)
+    Base.metadata.create_all(engine)
+
+    session_factory = get_session_factory(engine)
+
+    with transaction.manager:
+        dbsession = get_tm_session(session_factory, transaction.manager)
+
+        editor = User(name='editor', role='editor')
+        editor.set_password('editor')
+        dbsession.add(editor)
+
+        basic = User(name='basic', role='basic')
+        basic.set_password('basic')
+        dbsession.add(basic)
+
+        page = Page(
+            name='FrontPage',
+            creator=editor,
+            data='This is the front page',
+        )
+        dbsession.add(page)
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/favicon.ico b/docs/tutorials/wiki2/src/models/tutorial/static/favicon.ico
deleted file mode 100644
index 71f837c9e..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/static/favicon.ico
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/footerbg.png b/docs/tutorials/wiki2/src/models/tutorial/static/footerbg.png
deleted file mode 100644
index 1fbc873da..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/static/footerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/headerbg.png b/docs/tutorials/wiki2/src/models/tutorial/static/headerbg.png
deleted file mode 100644
index 0596f2020..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/static/headerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/ie6.css b/docs/tutorials/wiki2/src/models/tutorial/static/ie6.css
deleted file mode 100644
index b7c8493d8..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/static/ie6.css
+++ /dev/null
@@ -1,8 +0,0 @@
-* html img,
-* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
-this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
-this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
-);}
-#wrap{display:table;height:100%}
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/middlebg.png b/docs/tutorials/wiki2/src/models/tutorial/static/middlebg.png
deleted file mode 100644
index 2369cfb7d..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/static/middlebg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/pylons.css b/docs/tutorials/wiki2/src/models/tutorial/static/pylons.css
deleted file mode 100644
index fd1914d8d..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/static/pylons.css
+++ /dev/null
@@ -1,65 +0,0 @@
-html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */
-vertical-align:baseline;background:transparent;}
-body{line-height:1;}
-ol,ul{list-style:none;}
-blockquote,q{quotes:none;}
-blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;}
-:focus{outline:0;}
-ins{text-decoration:none;}
-del{text-decoration:line-through;}
-table{border-collapse:collapse;border-spacing:0;}
-sub{vertical-align:sub;font-size:smaller;line-height:normal;}
-sup{vertical-align:super;font-size:smaller;line-height:normal;}
-ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;}
-ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;}
-li{display:list-item;}
-ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;}
-ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;}
-ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;}
-.hidden{display:none;}
-p{line-height:1.5em;}
-h1{font-size:1.75em;line-height:1.7em;font-family:helvetica,verdana;}
-h2{font-size:1.5em;line-height:1.7em;font-family:helvetica,verdana;}
-h3{font-size:1.25em;line-height:1.7em;font-family:helvetica,verdana;}
-h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;}
-html,body{width:100%;height:100%;}
-body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;}
-a{color:#1b61d6;text-decoration:none;}
-a:hover{color:#e88f00;text-decoration:underline;}
-body h1,
-body h2,
-body h3,
-body h4,
-body h5,
-body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;}
-#wrap{min-height:100%;}
-#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;}
-#header{background:#000000;top:0;font-size:14px;}
-#footer{bottom:0;background:#000000 url(footerbg.png) repeat-x 0 top;position:relative;margin-top:-40px;clear:both;}
-.header,.footer{width:750px;margin-right:auto;margin-left:auto;}
-.wrapper{width:100%}
-#top,#top-small,#bottom{width:100%;}
-#top{color:#000000;height:230px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#top-small{color:#000000;height:60px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#bottom{color:#222;background-color:#ffffff;}
-.top,.top-small,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;}
-.top{padding-top:40px;}
-.top-small{padding-top:10px;}
-#middle{width:100%;height:100px;background:url(middlebg.png) repeat-x;border-top:2px solid #ffffff;border-bottom:2px solid #b2b2b2;}
-.app-welcome{margin-top:25px;}
-.app-name{color:#000000;font-weight:bold;}
-.bottom{padding-top:50px;}
-#left{width:350px;float:left;padding-right:25px;}
-#right{width:350px;float:right;padding-left:25px;}
-.align-left{text-align:left;}
-.align-right{text-align:right;}
-.align-center{text-align:center;}
-ul.links{margin:0;padding:0;}
-ul.links li{list-style-type:none;font-size:14px;}
-form{border-style:none;}
-fieldset{border-style:none;}
-input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;}
-input[type=text],input[type=password]{width:205px;}
-input[type=submit]{background-color:#ddd;font-weight:bold;}
-/*Opera Fix*/
-body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;}
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki2/src/models/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/pyramid-small.png b/docs/tutorials/wiki2/src/models/tutorial/static/pyramid-small.png
deleted file mode 100644
index a5bc0ade7..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/static/pyramid-small.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/pyramid.png b/docs/tutorials/wiki2/src/models/tutorial/static/pyramid.png
index 347e05549..4ab837be9 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/static/pyramid.png
+++ b/docs/tutorials/wiki2/src/models/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/theme.css b/docs/tutorials/wiki2/src/models/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki2/src/models/tutorial/static/transparent.gif b/docs/tutorials/wiki2/src/models/tutorial/static/transparent.gif
deleted file mode 100644
index 0341802e5..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/static/transparent.gif
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/models/tutorial/templates/404.jinja2 b/docs/tutorials/wiki2/src/models/tutorial/templates/404.jinja2
new file mode 100644
index 000000000..1917f83c7
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/templates/404.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Alchemy scaffold</span></h1>
+  <p class="lead"><span class="font-semi-bold">404</span> Page Not Found</p>
+</div>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/models/tutorial/templates/layout.jinja2 b/docs/tutorials/wiki2/src/models/tutorial/templates/layout.jinja2
new file mode 100644
index 000000000..ab8c5ea3d
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/templates/layout.jinja2
@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html lang="{{request.locale_name}}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="{{request.static_url('tutorial:static/pyramid-16x16.png')}}">
+
+    <title>Alchemy Scaffold for The Pyramid Web Framework</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="{{request.static_url('tutorial:static/theme.css')}}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="{{request.static_url('tutorial:static/pyramid.png')}}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            {% block content %}
+                <p>No content</p>
+            {% endblock content %}
+          </div>
+        </div>
+        <div class="row">
+          <div class="links">
+            <ul>
+              <li class="current-version">Generated by v1.7</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
+              <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
+              <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
+              <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
+            </ul>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.jinja2 b/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.jinja2
new file mode 100644
index 000000000..6b49869c4
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Alchemy scaffold</span></h1>
+  <p class="lead">Welcome to <span class="font-normal">{{project}}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7</span>.</p>
+</div>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt
deleted file mode 100644
index d98420680..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt
+++ /dev/null
@@ -1,75 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>The Pyramid Web Application Development Framework</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon" href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
-  <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton|Nobile:regular,i,b,bi&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top">
-      <div class="top align-center">
-        <div><img src="${request.static_url('tutorial:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-center">
-        <p class="app-welcome">
-          Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web application development framework.
-        </p>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div id="left" class="align-right">
-          <h2>Search documentation</h2>
-          <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/dev/search.html">
-                <input type="text" id="q" name="q" value="" />
-                <input type="submit" id="x" value="Go" />
-            </form>
-        </div>
-        <div id="right" class="align-left">
-          <h2>Pyramid links</h2>
-          <ul class="links">
-            <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#narrative-documentation">Narrative Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#api-documentation">API Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#tutorials">Tutorials</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#change-history">Change History</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#sample-applications">Sample Applications</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#support-and-development">Support and Development</a>
-            </li>
-            <li>
-              <a href="irc://irc.freenode.net#pyramid">IRC Channel</a>
-            </li>
-            </ul>
-        </div>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
-</html>
diff --git a/docs/tutorials/wiki2/src/models/tutorial/tests.py b/docs/tutorials/wiki2/src/models/tutorial/tests.py
index 71f5e21e3..99e95efd3 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/tests.py
@@ -1,22 +1,65 @@
 import unittest
+import transaction
+
 from pyramid import testing
 
-def _initTestingDB():
-    from tutorial.models import initialize_sql
-    session = initialize_sql('sqlite://')
-    return session
 
-class TestMyView(unittest.TestCase):
+def dummy_request(dbsession):
+    return testing.DummyRequest(dbsession=dbsession)
+
+
+class BaseTest(unittest.TestCase):
     def setUp(self):
-        self.config = testing.setUp()
-        _initTestingDB()
+        self.config = testing.setUp(settings={
+            'sqlalchemy.url': 'sqlite:///:memory:'
+        })
+        self.config.include('.models')
+        settings = self.config.get_settings()
+
+        from .models import (
+            get_engine,
+            get_session_factory,
+            get_tm_session,
+            )
+
+        self.engine = get_engine(settings)
+        session_factory = get_session_factory(self.engine)
+
+        self.session = get_tm_session(session_factory, transaction.manager)
+
+    def init_database(self):
+        from .models.meta import Base
+        Base.metadata.create_all(self.engine)
 
     def tearDown(self):
+        from .models.meta import Base
+
         testing.tearDown()
+        transaction.abort()
+        Base.metadata.drop_all(self.engine)
+
 
-    def test_it(self):
-        from tutorial.views import my_view
-        request = testing.DummyRequest()
-        info = my_view(request)
-        self.assertEqual(info['root'].name, 'root')
+class TestMyViewSuccessCondition(BaseTest):
+
+    def setUp(self):
+        super(TestMyViewSuccessCondition, self).setUp()
+        self.init_database()
+
+        from .models import MyModel
+
+        model = MyModel(name='one', value=55)
+        self.session.add(model)
+
+    def test_passing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info['one'].name, 'one')
         self.assertEqual(info['project'], 'tutorial')
+
+
+class TestMyViewFailureCondition(BaseTest):
+
+    def test_failing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info.status_int, 500)
diff --git a/docs/tutorials/wiki2/src/models/tutorial/views.py b/docs/tutorials/wiki2/src/models/tutorial/views.py
deleted file mode 100644
index e550e3257..000000000
--- a/docs/tutorials/wiki2/src/models/tutorial/views.py
+++ /dev/null
@@ -1,7 +0,0 @@
-from tutorial.models import DBSession
-from tutorial.models import MyModel
-
-def my_view(request):
-    dbsession = DBSession()
-    root = dbsession.query(MyModel).filter(MyModel.name==u'root').first()
-    return {'root':root, 'project':'tutorial'}
diff --git a/docs/tutorials/wiki2/src/models/tutorial/views/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/views/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/views/__init__.py
diff --git a/docs/tutorials/wiki2/src/models/tutorial/views/default.py b/docs/tutorials/wiki2/src/models/tutorial/views/default.py
new file mode 100644
index 000000000..ad0c728d7
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/views/default.py
@@ -0,0 +1,33 @@
+from pyramid.response import Response
+from pyramid.view import view_config
+
+from sqlalchemy.exc import DBAPIError
+
+from ..models import MyModel
+
+
+@view_config(route_name='home', renderer='../templates/mytemplate.jinja2')
+def my_view(request):
+    try:
+        query = request.dbsession.query(MyModel)
+        one = query.filter(MyModel.name == 'one').first()
+    except DBAPIError:
+        return Response(db_err_msg, content_type='text/plain', status=500)
+    return {'one': one, 'project': 'tutorial'}
+
+
+db_err_msg = """\
+Pyramid is having a problem using your SQL database.  The problem
+might be caused by one of the following things:
+
+1.  You may need to run the "initialize_tutorial_db" script
+    to initialize your database tables.  Check your virtual
+    environment's "bin" directory for this script and try to run it.
+
+2.  Your database server may not be running.  Check that the
+    database server referred to by the "sqlalchemy.url" setting in
+    your "development.ini" file is running.
+
+After you fix the problem, please restart the Pyramid application to
+try it again.
+"""
diff --git a/docs/tutorials/wiki2/src/models/tutorial/views/notfound.py b/docs/tutorials/wiki2/src/models/tutorial/views/notfound.py
new file mode 100644
index 000000000..69d6e2804
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tutorial/views/notfound.py
@@ -0,0 +1,7 @@
+from pyramid.view import notfound_view_config
+
+
+@notfound_view_config(renderer='../templates/404.jinja2')
+def notfound_view(request):
+    request.response.status = 404
+    return {}
diff --git a/docs/tutorials/wiki2/src/tests/CHANGES.txt b/docs/tutorials/wiki2/src/tests/CHANGES.txt
new file mode 100644
index 000000000..35a34f332
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/CHANGES.txt
@@ -0,0 +1,4 @@
+0.0
+---
+
+-  Initial version
diff --git a/docs/tutorials/wiki2/src/tests/MANIFEST.in b/docs/tutorials/wiki2/src/tests/MANIFEST.in
new file mode 100644
index 000000000..42cd299b5
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/MANIFEST.in
@@ -0,0 +1,2 @@
+include *.txt *.ini *.cfg *.rst
+recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.jinja2 *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/tutorials/wiki2/src/tests/README.txt b/docs/tutorials/wiki2/src/tests/README.txt
new file mode 100644
index 000000000..5b0101e5f
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/README.txt
@@ -0,0 +1,14 @@
+tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/initialize_tutorial_db development.ini
+
+- $VENV/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/tests/development.ini b/docs/tutorials/wiki2/src/tests/development.ini
new file mode 100644
index 000000000..4a6c9325c
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/development.ini
@@ -0,0 +1,73 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_tm
+
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
+
+auth.secret = seekrit
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
+[server:main]
+use = egg:waitress#main
+host = 127.0.0.1
+port = 6543
+
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial, sqlalchemy
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
+[logger_sqlalchemy]
+level = INFO
+handlers =
+qualname = sqlalchemy.engine
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARN" logs neither.  (Recommended for production systems.)
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/tests/production.ini b/docs/tutorials/wiki2/src/tests/production.ini
new file mode 100644
index 000000000..a13a0ca19
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/production.ini
@@ -0,0 +1,62 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
+
+auth.secret = real-seekrit
+
+[server:main]
+use = egg:waitress#main
+host = 0.0.0.0
+port = 6543
+
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial, sqlalchemy
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_tutorial]
+level = WARN
+handlers =
+qualname = tutorial
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARN" logs neither.  (Recommended for production systems.)
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/tests/setup.py b/docs/tutorials/wiki2/src/tests/setup.py
new file mode 100644
index 000000000..def3ce1f6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/setup.py
@@ -0,0 +1,57 @@
+import os
+
+from setuptools import setup, find_packages
+
+here = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
+
+requires = [
+    'bcrypt',
+    'docutils',
+    'pyramid',
+    'pyramid_jinja2',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
+    'SQLAlchemy',
+    'transaction',
+    'zope.sqlalchemy',
+    'waitress',
+    ]
+
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
+
+setup(name='tutorial',
+      version='0.0',
+      description='tutorial',
+      long_description=README + '\n\n' + CHANGES,
+      classifiers=[
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
+      author='',
+      author_email='',
+      url='',
+      keywords='web wsgi bfg pylons pyramid',
+      packages=find_packages(),
+      include_package_data=True,
+      zip_safe=False,
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
+      [paste.app_factory]
+      main = tutorial:main
+      [console_scripts]
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
+      """,
+      )
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/__init__.py b/docs/tutorials/wiki2/src/tests/tutorial/__init__.py
new file mode 100644
index 000000000..f5c033b8b
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/__init__.py
@@ -0,0 +1,13 @@
+from pyramid.config import Configurator
+
+
+def main(global_config, **settings):
+    """ This function returns a Pyramid WSGI application.
+    """
+    config = Configurator(settings=settings)
+    config.include('pyramid_jinja2')
+    config.include('.models')
+    config.include('.routes')
+    config.include('.security')
+    config.scan()
+    return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/tests/tutorial/models/__init__.py
new file mode 100644
index 000000000..a8871f6f5
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models/__init__.py
@@ -0,0 +1,74 @@
+from sqlalchemy import engine_from_config
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import configure_mappers
+import zope.sqlalchemy
+
+# import or define all models here to ensure they are attached to the
+# Base.metadata prior to any initialization routines
+from .page import Page # flake8: noqa
+from .user import User # flake8: noqa
+
+# run configure_mappers after defining all of the models to ensure
+# all relationships can be setup
+configure_mappers()
+
+
+def get_engine(settings, prefix='sqlalchemy.'):
+    return engine_from_config(settings, prefix)
+
+
+def get_session_factory(engine):
+    factory = sessionmaker()
+    factory.configure(bind=engine)
+    return factory
+
+
+def get_tm_session(session_factory, transaction_manager):
+    """
+    Get a ``sqlalchemy.orm.Session`` instance backed by a transaction.
+
+    This function will hook the session to the transaction manager which
+    will take care of committing any changes.
+
+    - When using pyramid_tm it will automatically be committed or aborted
+      depending on whether an exception is raised.
+
+    - When using scripts you should wrap the session in a manager yourself.
+      For example::
+
+          import transaction
+
+          engine = get_engine(settings)
+          session_factory = get_session_factory(engine)
+          with transaction.manager:
+              dbsession = get_tm_session(session_factory, transaction.manager)
+
+    """
+    dbsession = session_factory()
+    zope.sqlalchemy.register(
+        dbsession, transaction_manager=transaction_manager)
+    return dbsession
+
+
+def includeme(config):
+    """
+    Initialize the model for a Pyramid app.
+
+    Activate this setup using ``config.include('tutorial.models')``.
+
+    """
+    settings = config.get_settings()
+
+    # use pyramid_tm to hook the transaction lifecycle to the request
+    config.include('pyramid_tm')
+
+    session_factory = get_session_factory(get_engine(settings))
+    config.registry['dbsession_factory'] = session_factory
+
+    # make request.dbsession available for use in Pyramid
+    config.add_request_method(
+        # r.tm is the transaction manager used by pyramid_tm
+        lambda r: get_tm_session(session_factory, r.tm),
+        'dbsession',
+        reify=True
+    )
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models/meta.py b/docs/tutorials/wiki2/src/tests/tutorial/models/meta.py
new file mode 100644
index 000000000..fc3e8f1dd
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models/meta.py
@@ -0,0 +1,16 @@
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.schema import MetaData
+
+# Recommended naming convention used by Alembic, as various different database
+# providers will autogenerate vastly different names making migrations more
+# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+NAMING_CONVENTION = {
+    "ix": 'ix_%(column_0_label)s',
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s"
+}
+
+metadata = MetaData(naming_convention=NAMING_CONVENTION)
+Base = declarative_base(metadata=metadata)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models/page.py b/docs/tutorials/wiki2/src/tests/tutorial/models/page.py
new file mode 100644
index 000000000..4dd5b5721
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models/page.py
@@ -0,0 +1,20 @@
+from sqlalchemy import (
+    Column,
+    ForeignKey,
+    Integer,
+    Text,
+)
+from sqlalchemy.orm import relationship
+
+from .meta import Base
+
+
+class Page(Base):
+    """ The SQLAlchemy declarative model class for a Page object. """
+    __tablename__ = 'pages'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text, nullable=False, unique=True)
+    data = Column(Integer, nullable=False)
+
+    creator_id = Column(ForeignKey('users.id'), nullable=False)
+    creator = relationship('User', backref='created_pages')
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models/user.py b/docs/tutorials/wiki2/src/tests/tutorial/models/user.py
new file mode 100644
index 000000000..6bd3315d6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models/user.py
@@ -0,0 +1,29 @@
+import bcrypt
+from sqlalchemy import (
+    Column,
+    Integer,
+    Text,
+)
+
+from .meta import Base
+
+
+class User(Base):
+    """ The SQLAlchemy declarative model class for a User object. """
+    __tablename__ = 'users'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text, nullable=False, unique=True)
+    role = Column(Text, nullable=False)
+
+    password_hash = Column(Text)
+
+    def set_password(self, pw):
+        pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
+        self.password_hash = pwhash
+
+    def check_password(self, pw):
+        if self.password_hash is not None:
+            expected_hash = self.password_hash
+            actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
+            return expected_hash == actual_hash
+        return False
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/routes.py b/docs/tutorials/wiki2/src/tests/tutorial/routes.py
new file mode 100644
index 000000000..f0a8b7f96
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/routes.py
@@ -0,0 +1,56 @@
+from pyramid.httpexceptions import (
+    HTTPNotFound,
+    HTTPFound,
+)
+from pyramid.security import (
+    Allow,
+    Everyone,
+)
+
+from .models import Page
+
+def includeme(config):
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.add_route('view_wiki', '/')
+    config.add_route('login', '/login')
+    config.add_route('logout', '/logout')
+    config.add_route('view_page', '/{pagename}', factory=page_factory)
+    config.add_route('add_page', '/add_page/{pagename}',
+                     factory=new_page_factory)
+    config.add_route('edit_page', '/{pagename}/edit_page',
+                     factory=page_factory)
+
+def new_page_factory(request):
+    pagename = request.matchdict['pagename']
+    if request.dbsession.query(Page).filter_by(name=pagename).count() > 0:
+        next_url = request.route_url('edit_page', pagename=pagename)
+        raise HTTPFound(location=next_url)
+    return NewPage(pagename)
+
+class NewPage(object):
+    def __init__(self, pagename):
+        self.pagename = pagename
+
+    def __acl__(self):
+        return [
+            (Allow, 'role:editor', 'create'),
+            (Allow, 'role:basic', 'create'),
+        ]
+
+def page_factory(request):
+    pagename = request.matchdict['pagename']
+    page = request.dbsession.query(Page).filter_by(name=pagename).first()
+    if page is None:
+        raise HTTPNotFound
+    return PageResource(page)
+
+class PageResource(object):
+    def __init__(self, page):
+        self.page = page
+
+    def __acl__(self):
+        return [
+            (Allow, Everyone, 'view'),
+            (Allow, 'role:editor', 'edit'),
+            (Allow, str(self.page.creator_id), 'edit'),
+        ]
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/scripts/__init__.py b/docs/tutorials/wiki2/src/tests/tutorial/scripts/__init__.py
new file mode 100644
index 000000000..5bb534f79
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/scripts/__init__.py
@@ -0,0 +1 @@
+# package
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
new file mode 100644
index 000000000..f3c0a6fef
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
@@ -0,0 +1,57 @@
+import os
+import sys
+import transaction
+
+from pyramid.paster import (
+    get_appsettings,
+    setup_logging,
+    )
+
+from pyramid.scripts.common import parse_vars
+
+from ..models.meta import Base
+from ..models import (
+    get_engine,
+    get_session_factory,
+    get_tm_session,
+    )
+from ..models import Page, User
+
+
+def usage(argv):
+    cmd = os.path.basename(argv[0])
+    print('usage: %s <config_uri> [var=value]\n'
+          '(example: "%s development.ini")' % (cmd, cmd))
+    sys.exit(1)
+
+
+def main(argv=sys.argv):
+    if len(argv) < 2:
+        usage(argv)
+    config_uri = argv[1]
+    options = parse_vars(argv[2:])
+    setup_logging(config_uri)
+    settings = get_appsettings(config_uri, options=options)
+
+    engine = get_engine(settings)
+    Base.metadata.create_all(engine)
+
+    session_factory = get_session_factory(engine)
+
+    with transaction.manager:
+        dbsession = get_tm_session(session_factory, transaction.manager)
+
+        editor = User(name='editor', role='editor')
+        editor.set_password('editor')
+        dbsession.add(editor)
+
+        basic = User(name='basic', role='basic')
+        basic.set_password('basic')
+        dbsession.add(basic)
+
+        page = Page(
+            name='FrontPage',
+            creator=editor,
+            data='This is the front page',
+        )
+        dbsession.add(page)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/security.py b/docs/tutorials/wiki2/src/tests/tutorial/security.py
new file mode 100644
index 000000000..25cff7b05
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/security.py
@@ -0,0 +1,40 @@
+from pyramid.authentication import AuthTktAuthenticationPolicy
+from pyramid.authorization import ACLAuthorizationPolicy
+from pyramid.security import (
+    Authenticated,
+    Everyone,
+)
+
+from .models import User
+
+
+class MyAuthenticationPolicy(AuthTktAuthenticationPolicy):
+    def authenticated_userid(self, request):
+        user = request.user
+        if user is not None:
+            return user.id
+
+    def effective_principals(self, request):
+        principals = [Everyone]
+        user = request.user
+        if user is not None:
+            principals.append(Authenticated)
+            principals.append(str(user.id))
+            principals.append('role:' + user.role)
+        return principals
+
+def get_user(request):
+    user_id = request.unauthenticated_userid
+    if user_id is not None:
+        user = request.dbsession.query(User).get(user_id)
+        return user
+
+def includeme(config):
+    settings = config.get_settings()
+    authn_policy = MyAuthenticationPolicy(
+        settings['auth.secret'],
+        hashalg='sha512',
+    )
+    config.set_authentication_policy(authn_policy)
+    config.set_authorization_policy(ACLAuthorizationPolicy())
+    config.add_request_method(get_user, 'user', reify=True)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki2/src/tests/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/static/pyramid.png b/docs/tutorials/wiki2/src/tests/tutorial/static/pyramid.png
new file mode 100644
index 000000000..4ab837be9
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/static/theme.css b/docs/tutorials/wiki2/src/tests/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/templates/404.jinja2 b/docs/tutorials/wiki2/src/tests/tutorial/templates/404.jinja2
new file mode 100644
index 000000000..37b0a16b6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/templates/404.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid tutorial wiki</span> <span class="smaller">(based on TurboGears 20-Minute Wiki)</span></h1>
+  <p class="lead"><span class="font-semi-bold">404</span> Page Not Found</p>
+</div>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/templates/edit.jinja2 b/docs/tutorials/wiki2/src/tests/tutorial/templates/edit.jinja2
new file mode 100644
index 000000000..7db25c674
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/templates/edit.jinja2
@@ -0,0 +1,20 @@
+{% extends 'layout.jinja2' %}
+
+{% block subtitle %}Edit {{pagename}} - {% endblock subtitle %}
+
+{% block content %}
+<p>
+Editing <strong>{{pagename}}</strong>
+</p>
+<p>You can return to the
+<a href="{{request.route_url('view_page', pagename='FrontPage')}}">FrontPage</a>.
+</p>
+<form action="{{ save_url }}" method="post">
+<div class="form-group">
+    <textarea class="form-control" name="body" rows="10" cols="60">{{ pagedata }}</textarea>
+</div>
+<div class="form-group">
+    <button type="submit" name="form.submitted" value="Save" class="btn btn-default">Save</button>
+</div>
+</form>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/templates/layout.jinja2 b/docs/tutorials/wiki2/src/tests/tutorial/templates/layout.jinja2
new file mode 100644
index 000000000..44d14304e
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/templates/layout.jinja2
@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="{{request.locale_name}}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="{{request.static_url('tutorial:static/pyramid-16x16.png')}}">
+
+    <title>{% block subtitle %}{% endblock %}Pyramid tutorial wiki (based on TurboGears 20-Minute Wiki)</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="{{request.static_url('tutorial:static/theme.css')}}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="{{request.static_url('tutorial:static/pyramid.png')}}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+            {% if request.user is none %}
+            <p class="pull-right">
+            <a href="{{ request.route_url('login') }}">Login</a>
+            </p>
+            {% else %}
+            <p class="pull-right">
+            {{request.user.name}} <a href="{{request.route_url('logout')}}">Logout</a>
+            </p>
+            {% endif %}
+            {% block content %}{% endblock %}
+            </div>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/templates/login.jinja2 b/docs/tutorials/wiki2/src/tests/tutorial/templates/login.jinja2
new file mode 100644
index 000000000..1806de0ff
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/templates/login.jinja2
@@ -0,0 +1,26 @@
+{% extends 'layout.jinja2' %}
+
+{% block title %}Login - {% endblock title %}
+
+{% block content %}
+<p>
+<strong>
+    Login
+</strong><br>
+{{ message }}
+</p>
+<form action="{{ url }}" method="post">
+<input type="hidden" name="next" value="{{ next_url }}">
+<div class="form-group">
+    <label for="login">Username</label>
+    <input type="text" name="login" value="{{ login }}">
+</div>
+<div class="form-group">
+    <label for="password">Password</label>
+    <input type="password" name="password">
+</div>
+<div class="form-group">
+    <button type="submit" name="form.submitted" value="Log In" class="btn btn-default">Log In</button>
+</div>
+</form>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/templates/view.jinja2 b/docs/tutorials/wiki2/src/tests/tutorial/templates/view.jinja2
new file mode 100644
index 000000000..94419e228
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/templates/view.jinja2
@@ -0,0 +1,18 @@
+{% extends 'layout.jinja2' %}
+
+{% block subtitle %}{{page.name}} - {% endblock subtitle %}
+
+{% block content %}
+<p>{{ content|safe }}</p>
+<p>
+<a href="{{ edit_url }}">
+    Edit this page
+</a>
+</p>
+<p>
+    Viewing <strong>{{page.name}}</strong>, created by <strong>{{page.creator.name}}</strong>.
+</p>
+<p>You can return to the
+<a href="{{request.route_url('view_page', pagename='FrontPage')}}">FrontPage</a>.
+</p>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests.py b/docs/tutorials/wiki2/src/tests/tutorial/tests.py
deleted file mode 100644
index 98a4969e9..000000000
--- a/docs/tutorials/wiki2/src/tests/tutorial/tests.py
+++ /dev/null
@@ -1,266 +0,0 @@
-import unittest
-
-from pyramid import testing
-
-
-def _initTestingDB():
-    from tutorial.models import DBSession
-    from tutorial.models import Base
-    from sqlalchemy import create_engine
-    engine = create_engine('sqlite:///:memory:')
-    DBSession.configure(bind=engine)
-    Base.metadata.bind = engine
-    Base.metadata.create_all(engine)
-    return DBSession
-
-def _registerRoutes(config):
-    config.add_route('view_page', '{pagename}')
-    config.add_route('edit_page', '{pagename}/edit_page')
-    config.add_route('add_page', 'add_page/{pagename}')
-
-
-class PageModelTests(unittest.TestCase):
-
-    def setUp(self):
-        self.session = _initTestingDB()
-
-    def tearDown(self):
-        self.session.remove()
-
-    def _getTargetClass(self):
-        from tutorial.models import Page
-        return Page
-
-    def _makeOne(self, name='SomeName', data='some data'):
-        return self._getTargetClass()(name, data)
-
-    def test_constructor(self):
-        instance = self._makeOne()
-        self.assertEqual(instance.name, 'SomeName')
-        self.assertEqual(instance.data, 'some data')
-
-class InitializeSqlTests(unittest.TestCase):
-
-    def setUp(self):
-        from tutorial.models import DBSession
-        DBSession.remove()
-
-    def tearDown(self):
-        from tutorial.models import DBSession
-        DBSession.remove()
-
-    def _callFUT(self, engine):
-        from tutorial.models import initialize_sql
-        return initialize_sql(engine)
-
-    def test_it(self):
-        from sqlalchemy import create_engine
-        engine = create_engine('sqlite:///:memory:')
-        self._callFUT(engine)
-        from tutorial.models import DBSession, Page
-        self.assertEqual(DBSession.query(Page).one().data,
-            'This is the front page')
-
-class ViewWikiTests(unittest.TestCase):
-    def setUp(self):
-        self.config = testing.setUp()
-
-    def tearDown(self):
-        testing.tearDown()
-
-    def _callFUT(self, request):
-        from tutorial.views import view_wiki
-        return view_wiki(request)
-
-    def test_it(self):
-        _registerRoutes(self.config)
-        request = testing.DummyRequest()
-        response = self._callFUT(request)
-        self.assertEqual(response.location, 'http://example.com/FrontPage')
-
-class ViewPageTests(unittest.TestCase):
-    def setUp(self):
-        self.session = _initTestingDB()
-        self.config = testing.setUp()
-
-    def tearDown(self):
-        self.session.remove()
-        testing.tearDown()
-
-    def _callFUT(self, request):
-        from tutorial.views import view_page
-        return view_page(request)
-
-    def test_it(self):
-        from tutorial.models import Page
-        request = testing.DummyRequest()
-        request.matchdict['pagename'] = 'IDoExist'
-        page = Page('IDoExist', 'Hello CruelWorld IDoExist')
-        self.session.add(page)
-        _registerRoutes(self.config)
-        info = self._callFUT(request)
-        self.assertEqual(info['page'], page)
-        self.assertEqual(
-            info['content'],
-            '<div class="document">\n'
-            '<p>Hello <a href="http://example.com/add_page/CruelWorld">'
-            'CruelWorld</a> '
-            '<a href="http://example.com/IDoExist">'
-            'IDoExist</a>'
-            '</p>\n</div>\n')
-        self.assertEqual(info['edit_url'],
-            'http://example.com/IDoExist/edit_page')
-
-class AddPageTests(unittest.TestCase):
-    def setUp(self):
-        self.session = _initTestingDB()
-        self.config = testing.setUp()
-        self.config.begin()
-
-    def tearDown(self):
-        self.session.remove()
-        testing.tearDown()
-
-    def _callFUT(self, request):
-        from tutorial.views import add_page
-        return add_page(request)
-
-    def test_it_notsubmitted(self):
-        _registerRoutes(self.config)
-        request = testing.DummyRequest()
-        request.matchdict = {'pagename':'AnotherPage'}
-        info = self._callFUT(request)
-        self.assertEqual(info['page'].data,'')
-        self.assertEqual(info['save_url'],
-                         'http://example.com/add_page/AnotherPage')
-
-    def test_it_submitted(self):
-        from tutorial.models import Page
-        _registerRoutes(self.config)
-        request = testing.DummyRequest({'form.submitted':True,
-                                        'body':'Hello yo!'})
-        request.matchdict = {'pagename':'AnotherPage'}
-        self._callFUT(request)
-        page = self.session.query(Page).filter_by(name='AnotherPage').one()
-        self.assertEqual(page.data, 'Hello yo!')
-
-class EditPageTests(unittest.TestCase):
-    def setUp(self):
-        self.session = _initTestingDB()
-        self.config = testing.setUp()
-
-    def tearDown(self):
-        self.session.remove()
-        testing.tearDown()
-
-    def _callFUT(self, request):
-        from tutorial.views import edit_page
-        return edit_page(request)
-
-    def test_it_notsubmitted(self):
-        from tutorial.models import Page
-        _registerRoutes(self.config)
-        request = testing.DummyRequest()
-        request.matchdict = {'pagename':'abc'}
-        page = Page('abc', 'hello')
-        self.session.add(page)
-        info = self._callFUT(request)
-        self.assertEqual(info['page'], page)
-        self.assertEqual(info['save_url'],
-            'http://example.com/abc/edit_page')
-
-    def test_it_submitted(self):
-        from tutorial.models import Page
-        _registerRoutes(self.config)
-        request = testing.DummyRequest({'form.submitted':True,
-            'body':'Hello yo!'})
-        request.matchdict = {'pagename':'abc'}
-        page = Page('abc', 'hello')
-        self.session.add(page)
-        response = self._callFUT(request)
-        self.assertEqual(response.location, 'http://example.com/abc')
-        self.assertEqual(page.data, 'Hello yo!')
-
-class FunctionalTests(unittest.TestCase):
-
-    viewer_login = '/login?login=viewer&password=viewer' \
-                   '&came_from=FrontPage&form.submitted=Login'
-    viewer_wrong_login = '/login?login=viewer&password=incorrect' \
-                   '&came_from=FrontPage&form.submitted=Login'
-    editor_login = '/login?login=editor&password=editor' \
-                   '&came_from=FrontPage&form.submitted=Login'
-
-    def setUp(self):
-        from tutorial import main
-        settings = { 'sqlalchemy.url': 'sqlite:///:memory:'}
-        app = main({}, **settings)
-        from webtest import TestApp
-        self.testapp = TestApp(app)
-
-    def tearDown(self):
-        del self.testapp
-        from tutorial.models import DBSession
-        DBSession.remove()
-
-    def test_root(self):
-        res = self.testapp.get('/', status=302)
-        self.assertTrue(not res.body)
-
-    def test_FrontPage(self):
-        res = self.testapp.get('/FrontPage', status=200)
-        self.assertTrue('FrontPage' in res.body)
-
-    def test_unexisting_page(self):
-        res = self.testapp.get('/SomePage', status=404)
-
-    def test_successful_log_in(self):
-        res = self.testapp.get(self.viewer_login, status=302)
-        self.assertTrue(res.location == 'FrontPage')
-
-    def test_failed_log_in(self):
-        res = self.testapp.get(self.viewer_wrong_login, status=200)
-        self.assertTrue('login' in res.body)
-
-    def test_logout_link_present_when_logged_in(self):
-        self.testapp.get(self.viewer_login, status=302)
-        res = self.testapp.get('/FrontPage', status=200)
-        self.assertTrue('Logout' in res.body)
-
-    def test_logout_link_not_present_after_logged_out(self):
-        self.testapp.get(self.viewer_login, status=302)
-        self.testapp.get('/FrontPage', status=200)
-        res = self.testapp.get('/logout', status=302)
-        self.assertTrue('Logout' not in res.body)
-
-    def test_anonymous_user_cannot_edit(self):
-        res = self.testapp.get('/FrontPage/edit_page', status=200)
-        self.assertTrue('Login' in res.body)
-
-    def test_anonymous_user_cannot_add(self):
-        res = self.testapp.get('/add_page/NewPage', status=200)
-        self.assertTrue('Login' in res.body)
-
-    def test_viewer_user_cannot_edit(self):
-        self.testapp.get(self.viewer_login, status=302)
-        res = self.testapp.get('/FrontPage/edit_page', status=200)
-        self.assertTrue('Login' in res.body)
-
-    def test_viewer_user_cannot_add(self):
-        self.testapp.get(self.viewer_login, status=302)
-        res = self.testapp.get('/add_page/NewPage', status=200)
-        self.assertTrue('Login' in res.body)
-
-    def test_editors_member_user_can_edit(self):
-        self.testapp.get(self.editor_login, status=302)
-        res = self.testapp.get('/FrontPage/edit_page', status=200)
-        self.assertTrue('Editing' in res.body)
-
-    def test_editors_member_user_can_add(self):
-        self.testapp.get(self.editor_login, status=302)
-        res = self.testapp.get('/add_page/NewPage', status=200)
-        self.assertTrue('Editing' in res.body)
-
-    def test_editors_member_user_can_view(self):
-        self.testapp.get(self.editor_login, status=302)
-        res = self.testapp.get('/FrontPage', status=200)
-        self.assertTrue('FrontPage' in res.body)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests/__init__.py b/docs/tutorials/wiki2/src/tests/tutorial/tests/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/tests/__init__.py
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests/test_functional.py b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_functional.py
new file mode 100644
index 000000000..715768b2e
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_functional.py
@@ -0,0 +1,122 @@
+import transaction
+import unittest
+import webtest
+
+
+class FunctionalTests(unittest.TestCase):
+
+    basic_login = (
+        '/login?login=basic&password=basic'
+        '&next=FrontPage&form.submitted=Login')
+    basic_wrong_login = (
+        '/login?login=basic&password=incorrect'
+        '&next=FrontPage&form.submitted=Login')
+    editor_login = (
+        '/login?login=editor&password=editor'
+        '&next=FrontPage&form.submitted=Login')
+
+    @classmethod
+    def setUpClass(cls):
+        from tutorial.models.meta import Base
+        from tutorial.models import (
+            User,
+            Page,
+            get_tm_session,
+        )
+        from tutorial import main
+
+        settings = {
+            'sqlalchemy.url': 'sqlite://',
+            'auth.secret': 'seekrit',
+        }
+        app = main({}, **settings)
+        cls.testapp = webtest.TestApp(app)
+
+        session_factory = app.registry['dbsession_factory']
+        cls.engine = session_factory.kw['bind']
+        Base.metadata.create_all(bind=cls.engine)
+
+        with transaction.manager:
+            dbsession = get_tm_session(session_factory, transaction.manager)
+            editor = User(name='editor', role='editor')
+            editor.set_password('editor')
+            basic = User(name='basic', role='basic')
+            basic.set_password('basic')
+            page1 = Page(name='FrontPage', data='This is the front page')
+            page1.creator = editor
+            page2 = Page(name='BackPage', data='This is the back page')
+            page2.creator = basic
+            dbsession.add_all([basic, editor, page1, page2])
+
+    @classmethod
+    def tearDownClass(cls):
+        from tutorial.models.meta import Base
+        Base.metadata.drop_all(bind=cls.engine)
+
+    def test_root(self):
+        res = self.testapp.get('/', status=302)
+        self.assertEqual(res.location, 'http://localhost/FrontPage')
+
+    def test_FrontPage(self):
+        res = self.testapp.get('/FrontPage', status=200)
+        self.assertTrue(b'FrontPage' in res.body)
+
+    def test_unexisting_page(self):
+        self.testapp.get('/SomePage', status=404)
+
+    def test_successful_log_in(self):
+        res = self.testapp.get(self.basic_login, status=302)
+        self.assertEqual(res.location, 'http://localhost/FrontPage')
+
+    def test_failed_log_in(self):
+        res = self.testapp.get(self.basic_wrong_login, status=200)
+        self.assertTrue(b'login' in res.body)
+
+    def test_logout_link_present_when_logged_in(self):
+        self.testapp.get(self.basic_login, status=302)
+        res = self.testapp.get('/FrontPage', status=200)
+        self.assertTrue(b'Logout' in res.body)
+
+    def test_logout_link_not_present_after_logged_out(self):
+        self.testapp.get(self.basic_login, status=302)
+        self.testapp.get('/FrontPage', status=200)
+        res = self.testapp.get('/logout', status=302)
+        self.assertTrue(b'Logout' not in res.body)
+
+    def test_anonymous_user_cannot_edit(self):
+        res = self.testapp.get('/FrontPage/edit_page', status=302).follow()
+        self.assertTrue(b'Login' in res.body)
+
+    def test_anonymous_user_cannot_add(self):
+        res = self.testapp.get('/add_page/NewPage', status=302).follow()
+        self.assertTrue(b'Login' in res.body)
+
+    def test_basic_user_cannot_edit_front(self):
+        self.testapp.get(self.basic_login, status=302)
+        res = self.testapp.get('/FrontPage/edit_page', status=302).follow()
+        self.assertTrue(b'Login' in res.body)
+
+    def test_basic_user_can_edit_back(self):
+        self.testapp.get(self.basic_login, status=302)
+        res = self.testapp.get('/BackPage/edit_page', status=200)
+        self.assertTrue(b'Editing' in res.body)
+
+    def test_basic_user_can_add(self):
+        self.testapp.get(self.basic_login, status=302)
+        res = self.testapp.get('/add_page/NewPage', status=200)
+        self.assertTrue(b'Editing' in res.body)
+
+    def test_editors_member_user_can_edit(self):
+        self.testapp.get(self.editor_login, status=302)
+        res = self.testapp.get('/FrontPage/edit_page', status=200)
+        self.assertTrue(b'Editing' in res.body)
+
+    def test_editors_member_user_can_add(self):
+        self.testapp.get(self.editor_login, status=302)
+        res = self.testapp.get('/add_page/NewPage', status=200)
+        self.assertTrue(b'Editing' in res.body)
+
+    def test_editors_member_user_can_view(self):
+        self.testapp.get(self.editor_login, status=302)
+        res = self.testapp.get('/FrontPage', status=200)
+        self.assertTrue(b'FrontPage' in res.body)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests/test_views.py b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_views.py
new file mode 100644
index 000000000..2c945ab33
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_views.py
@@ -0,0 +1,168 @@
+import unittest
+import transaction
+
+from pyramid import testing
+
+
+def dummy_request(dbsession):
+    return testing.DummyRequest(dbsession=dbsession)
+
+
+class BaseTest(unittest.TestCase):
+    def setUp(self):
+        from ..models import get_tm_session
+        self.config = testing.setUp(settings={
+            'sqlalchemy.url': 'sqlite:///:memory:'
+        })
+        self.config.include('..models')
+        self.config.include('..routes')
+
+        session_factory = self.config.registry['dbsession_factory']
+        self.session = get_tm_session(session_factory, transaction.manager)
+
+        self.init_database()
+
+    def init_database(self):
+        from ..models.meta import Base
+        session_factory = self.config.registry['dbsession_factory']
+        engine = session_factory.kw['bind']
+        Base.metadata.create_all(engine)
+
+    def tearDown(self):
+        testing.tearDown()
+        transaction.abort()
+
+    def makeUser(self, name, role, password='dummy'):
+        from ..models import User
+        user = User(name=name, role=role)
+        user.set_password(password)
+        return user
+
+    def makePage(self, name, data, creator):
+        from ..models import Page
+        return Page(name=name, data=data, creator=creator)
+
+
+class ViewWikiTests(unittest.TestCase):
+    def setUp(self):
+        self.config = testing.setUp()
+        self.config.include('..routes')
+
+    def tearDown(self):
+        testing.tearDown()
+
+    def _callFUT(self, request):
+        from tutorial.views.default import view_wiki
+        return view_wiki(request)
+
+    def test_it(self):
+        request = testing.DummyRequest()
+        response = self._callFUT(request)
+        self.assertEqual(response.location, 'http://example.com/FrontPage')
+
+
+class ViewPageTests(BaseTest):
+    def _callFUT(self, request):
+        from tutorial.views.default import view_page
+        return view_page(request)
+
+    def test_it(self):
+        from ..routes import PageResource
+
+        # add a page to the db
+        user = self.makeUser('foo', 'editor')
+        page = self.makePage('IDoExist', 'Hello CruelWorld IDoExist', user)
+        self.session.add_all([page, user])
+
+        # create a request asking for the page we've created
+        request = dummy_request(self.session)
+        request.context = PageResource(page)
+
+        # call the view we're testing and check its behavior
+        info = self._callFUT(request)
+        self.assertEqual(info['page'], page)
+        self.assertEqual(
+            info['content'],
+            '<div class="document">\n'
+            '<p>Hello <a href="http://example.com/add_page/CruelWorld">'
+            'CruelWorld</a> '
+            '<a href="http://example.com/IDoExist">'
+            'IDoExist</a>'
+            '</p>\n</div>\n')
+        self.assertEqual(info['edit_url'],
+                         'http://example.com/IDoExist/edit_page')
+
+
+class AddPageTests(BaseTest):
+    def _callFUT(self, request):
+        from tutorial.views.default import add_page
+        return add_page(request)
+
+    def test_it_pageexists(self):
+        from ..models import Page
+        from ..routes import NewPage
+        request = testing.DummyRequest({'form.submitted': True,
+                                        'body': 'Hello yo!'},
+                                       dbsession=self.session)
+        request.user = self.makeUser('foo', 'editor')
+        request.context = NewPage('AnotherPage')
+        self._callFUT(request)
+        pagecount = self.session.query(Page).filter_by(name='AnotherPage').count()
+        self.assertGreater(pagecount, 0)
+
+    def test_it_notsubmitted(self):
+        from ..routes import NewPage
+        request = dummy_request(self.session)
+        request.user = self.makeUser('foo', 'editor')
+        request.context = NewPage('AnotherPage')
+        info = self._callFUT(request)
+        self.assertEqual(info['pagedata'], '')
+        self.assertEqual(info['save_url'],
+                         'http://example.com/add_page/AnotherPage')
+
+    def test_it_submitted(self):
+        from ..models import Page
+        from ..routes import NewPage
+        request = testing.DummyRequest({'form.submitted': True,
+                                        'body': 'Hello yo!'},
+                                       dbsession=self.session)
+        request.user = self.makeUser('foo', 'editor')
+        request.context = NewPage('AnotherPage')
+        self._callFUT(request)
+        page = self.session.query(Page).filter_by(name='AnotherPage').one()
+        self.assertEqual(page.data, 'Hello yo!')
+
+
+class EditPageTests(BaseTest):
+    def _callFUT(self, request):
+        from tutorial.views.default import edit_page
+        return edit_page(request)
+
+    def makeContext(self, page):
+        from ..routes import PageResource
+        return PageResource(page)
+
+    def test_it_notsubmitted(self):
+        user = self.makeUser('foo', 'editor')
+        page = self.makePage('abc', 'hello', user)
+        self.session.add_all([page, user])
+
+        request = dummy_request(self.session)
+        request.context = self.makeContext(page)
+        info = self._callFUT(request)
+        self.assertEqual(info['pagename'], 'abc')
+        self.assertEqual(info['save_url'],
+                         'http://example.com/abc/edit_page')
+
+    def test_it_submitted(self):
+        user = self.makeUser('foo', 'editor')
+        page = self.makePage('abc', 'hello', user)
+        self.session.add_all([page, user])
+
+        request = testing.DummyRequest({'form.submitted': True,
+                                        'body': 'Hello yo!'},
+                                       dbsession=self.session)
+        request.context = self.makeContext(page)
+        response = self._callFUT(request)
+        self.assertEqual(response.location, 'http://example.com/abc')
+        self.assertEqual(page.data, 'Hello yo!')
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/views/__init__.py b/docs/tutorials/wiki2/src/tests/tutorial/views/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/views/__init__.py
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/views/auth.py b/docs/tutorials/wiki2/src/tests/tutorial/views/auth.py
new file mode 100644
index 000000000..2b993b430
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/views/auth.py
@@ -0,0 +1,46 @@
+from pyramid.httpexceptions import HTTPFound
+from pyramid.security import (
+    remember,
+    forget,
+    )
+from pyramid.view import (
+    forbidden_view_config,
+    view_config,
+)
+
+from ..models import User
+
+
+@view_config(route_name='login', renderer='../templates/login.jinja2')
+def login(request):
+    next_url = request.params.get('next', request.referrer)
+    if not next_url:
+        next_url = request.route_url('view_wiki')
+    message = ''
+    login = ''
+    if 'form.submitted' in request.params:
+        login = request.params['login']
+        password = request.params['password']
+        user = request.dbsession.query(User).filter_by(name=login).first()
+        if user is not None and user.check_password(password):
+            headers = remember(request, user.id)
+            return HTTPFound(location=next_url, headers=headers)
+        message = 'Failed login'
+
+    return dict(
+        message=message,
+        url=request.route_url('login'),
+        next_url=next_url,
+        login=login,
+        )
+
+@view_config(route_name='logout')
+def logout(request):
+    headers = forget(request)
+    next_url = request.route_url('view_wiki')
+    return HTTPFound(location=next_url, headers=headers)
+
+@forbidden_view_config()
+def forbidden_view(request):
+    next_url = request.route_url('login', _query={'next': request.url})
+    return HTTPFound(location=next_url)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/views/default.py b/docs/tutorials/wiki2/src/tests/tutorial/views/default.py
new file mode 100644
index 000000000..9358993ea
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/views/default.py
@@ -0,0 +1,64 @@
+import cgi
+import re
+from docutils.core import publish_parts
+
+from pyramid.httpexceptions import HTTPFound
+from pyramid.view import view_config
+
+from ..models import Page
+
+# regular expression used to find WikiWords
+wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")
+
+@view_config(route_name='view_wiki')
+def view_wiki(request):
+    next_url = request.route_url('view_page', pagename='FrontPage')
+    return HTTPFound(location=next_url)
+
+@view_config(route_name='view_page', renderer='../templates/view.jinja2',
+             permission='view')
+def view_page(request):
+    page = request.context.page
+
+    def add_link(match):
+        word = match.group(1)
+        exists = request.dbsession.query(Page).filter_by(name=word).all()
+        if exists:
+            view_url = request.route_url('view_page', pagename=word)
+            return '<a href="%s">%s</a>' % (view_url, cgi.escape(word))
+        else:
+            add_url = request.route_url('add_page', pagename=word)
+            return '<a href="%s">%s</a>' % (add_url, cgi.escape(word))
+
+    content = publish_parts(page.data, writer_name='html')['html_body']
+    content = wikiwords.sub(add_link, content)
+    edit_url = request.route_url('edit_page', pagename=page.name)
+    return dict(page=page, content=content, edit_url=edit_url)
+
+@view_config(route_name='edit_page', renderer='../templates/edit.jinja2',
+             permission='edit')
+def edit_page(request):
+    page = request.context.page
+    if 'form.submitted' in request.params:
+        page.data = request.params['body']
+        next_url = request.route_url('view_page', pagename=page.name)
+        return HTTPFound(location=next_url)
+    return dict(
+        pagename=page.name,
+        pagedata=page.data,
+        save_url=request.route_url('edit_page', pagename=page.name),
+        )
+
+@view_config(route_name='add_page', renderer='../templates/edit.jinja2',
+             permission='create')
+def add_page(request):
+    pagename = request.context.pagename
+    if 'form.submitted' in request.params:
+        body = request.params['body']
+        page = Page(name=pagename, data=body)
+        page.creator = request.user
+        request.dbsession.add(page)
+        next_url = request.route_url('view_page', pagename=pagename)
+        return HTTPFound(location=next_url)
+    save_url = request.route_url('add_page', pagename=pagename)
+    return dict(pagename=pagename, pagedata='', save_url=save_url)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/views/notfound.py b/docs/tutorials/wiki2/src/tests/tutorial/views/notfound.py
new file mode 100644
index 000000000..69d6e2804
--- /dev/null
+++ b/docs/tutorials/wiki2/src/tests/tutorial/views/notfound.py
@@ -0,0 +1,7 @@
+from pyramid.view import notfound_view_config
+
+
+@notfound_view_config(renderer='../templates/404.jinja2')
+def notfound_view(request):
+    request.response.status = 404
+    return {}
diff --git a/docs/tutorials/wiki2/src/views/MANIFEST.in b/docs/tutorials/wiki2/src/views/MANIFEST.in
index 81beba1b1..42cd299b5 100644
--- a/docs/tutorials/wiki2/src/views/MANIFEST.in
+++ b/docs/tutorials/wiki2/src/views/MANIFEST.in
@@ -1,2 +1,2 @@
 include *.txt *.ini *.cfg *.rst
-recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml
+recursive-include tutorial *.ico *.png *.css *.gif *.jpg *.jinja2 *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/tutorials/wiki2/src/views/README.txt b/docs/tutorials/wiki2/src/views/README.txt
index d41f7f90f..5b0101e5f 100644
--- a/docs/tutorials/wiki2/src/views/README.txt
+++ b/docs/tutorials/wiki2/src/views/README.txt
@@ -1,4 +1,14 @@
 tutorial README
+==================
 
+Getting Started
+---------------
 
+- cd <directory containing this file>
+
+- $VENV/bin/pip install -e .
+
+- $VENV/bin/initialize_tutorial_db development.ini
+
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/views/development.ini b/docs/tutorials/wiki2/src/views/development.ini
index 3b615f635..22b733e10 100644
--- a/docs/tutorials/wiki2/src/views/development.ini
+++ b/docs/tutorials/wiki2/src/views/development.ini
@@ -1,32 +1,42 @@
-[app:tutorial]
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
+
+[app:main]
 use = egg:tutorial
-reload_templates = true
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = true
-default_locale_name = en
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
-
-[pipeline:main]
-pipeline =
-    egg:WebError#evalerror
-    tm
-    tutorial
-
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+    pyramid_tm
+
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
 
 [server:main]
-use = egg:Paste#http
-host = 0.0.0.0
+use = egg:waitress#main
+host = 127.0.0.1
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
-keys = root, sqlalchemy
+keys = root, tutorial, sqlalchemy
 
 [handlers]
 keys = console
@@ -38,6 +48,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [logger_sqlalchemy]
 level = INFO
 handlers =
@@ -53,6 +68,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/views/production.ini b/docs/tutorials/wiki2/src/views/production.ini
index 0fdc38811..d2ecfe22a 100644
--- a/docs/tutorials/wiki2/src/views/production.ini
+++ b/docs/tutorials/wiki2/src/views/production.ini
@@ -1,43 +1,28 @@
-[app:tutorial]
-use = egg:tutorial
-reload_templates = false
-debug_authorization = false
-debug_notfound = false
-debug_routematch = false
-debug_templates = false
-default_locale_name = en
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html
+###
 
-[filter:weberror]
-use = egg:WebError#error_catcher
-debug = false
-;error_log = 
-;show_exceptions_in_wsgi_errors = true
-;smtp_server = localhost
-;error_email = janitor@example.com
-;smtp_username = janitor
-;smtp_password = "janitor's password"
-;from_address = paste@localhost
-;error_subject_prefix = "Pyramid Error"
-;smtp_use_tls =
-;error_message =
+[app:main]
+use = egg:tutorial
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
 
-[pipeline:main]
-pipeline =
-    weberror
-    tm
-    tutorial
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
-use = egg:Paste#http
+use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -72,6 +57,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/views/setup.cfg b/docs/tutorials/wiki2/src/views/setup.cfg
deleted file mode 100644
index 23b2ad983..000000000
--- a/docs/tutorials/wiki2/src/views/setup.cfg
+++ /dev/null
@@ -1,27 +0,0 @@
-[nosetests]
-match=^test
-nocapture=1
-cover-package=tutorial
-with-coverage=1
-cover-erase=1
-
-[compile_catalog]
-directory = tutorial/locale
-domain = tutorial
-statistics = true
-
-[extract_messages]
-add_comments = TRANSLATORS:
-output_file = tutorial/locale/tutorial.pot
-width = 80
-
-[init_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-
-[update_catalog]
-domain = tutorial
-input_file = tutorial/locale/tutorial.pot
-output_dir = tutorial/locale
-previous = true
diff --git a/docs/tutorials/wiki2/src/views/setup.py b/docs/tutorials/wiki2/src/views/setup.py
index ae9869d50..def3ce1f6 100644
--- a/docs/tutorials/wiki2/src/views/setup.py
+++ b/docs/tutorials/wiki2/src/views/setup.py
@@ -1,35 +1,42 @@
 import os
-import sys
 
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
+    'bcrypt',
+    'docutils',
     'pyramid',
+    'pyramid_jinja2',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
     'SQLAlchemy',
     'transaction',
-    'repoze.tm2>=1.0b1', # default_commit_veto
     'zope.sqlalchemy',
-    'WebError',
-    'docutils',
+    'waitress',
     ]
 
-if sys.version_info[:3] < (2,5,0):
-    requires.append('pysqlite')
+tests_require = [
+    'WebTest >= 1.3.1',  # py3 compat
+    'pytest',  # includes virtualenv
+    'pytest-cov',
+    ]
 
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Programming Language :: Python",
-        "Framework :: Pylons",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          "Programming Language :: Python",
+          "Framework :: Pyramid",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+      ],
       author='',
       author_email='',
       url='',
@@ -37,12 +44,14 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      extras_require={
+          'testing': tests_require,
+      },
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
+      [console_scripts]
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
-      paster_plugins=['pyramid'],
       )
-
diff --git a/docs/tutorials/wiki2/src/views/tutorial/__init__.py b/docs/tutorials/wiki2/src/views/tutorial/__init__.py
index ad89c124e..4dab44823 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/__init__.py
@@ -1,25 +1,12 @@
 from pyramid.config import Configurator
-from sqlalchemy import engine_from_config
 
-from tutorial.models import initialize_sql
 
 def main(global_config, **settings):
-    """ This function returns a WSGI application.
+    """ This function returns a Pyramid WSGI application.
     """
-    engine = engine_from_config(settings, 'sqlalchemy.')
-    initialize_sql(engine)
     config = Configurator(settings=settings)
-    config.add_static_view('static', 'tutorial:static')
-    config.add_route('view_wiki', '/')
-    config.add_route('view_page', '/{pagename}')
-    config.add_route('add_page', '/add_page/{pagename}')
-    config.add_route('edit_page', '/{pagename}/edit_page')
-    config.add_view('tutorial.views.view_wiki', route_name='view_wiki')
-    config.add_view('tutorial.views.view_page', route_name='view_page',
-                    renderer='tutorial:templates/view.pt')
-    config.add_view('tutorial.views.add_page', route_name='add_page',
-                    renderer='tutorial:templates/edit.pt')
-    config.add_view('tutorial.views.edit_page', route_name='edit_page',
-                    renderer='tutorial:templates/edit.pt')
+    config.include('pyramid_jinja2')
+    config.include('.models')
+    config.include('.routes')
+    config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models.py b/docs/tutorials/wiki2/src/views/tutorial/models.py
deleted file mode 100644
index 960c14941..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/models.py
+++ /dev/null
@@ -1,41 +0,0 @@
-import transaction
-
-from sqlalchemy import Column
-from sqlalchemy import Integer
-from sqlalchemy import Text
-
-from sqlalchemy.exc import IntegrityError
-from sqlalchemy.ext.declarative import declarative_base
-
-from sqlalchemy.orm import scoped_session
-from sqlalchemy.orm import sessionmaker
-
-from zope.sqlalchemy import ZopeTransactionExtension
-
-DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
-Base = declarative_base()
-
-class Page(Base):
-    """ The SQLAlchemy declarative model class for a Page object. """
-    __tablename__ = 'pages'
-    id = Column(Integer, primary_key=True)
-    name = Column(Text, unique=True)
-    data = Column(Text)
-
-    def __init__(self, name, data):
-        self.name = name
-        self.data = data
-
-def initialize_sql(engine):
-    DBSession.configure(bind=engine)
-    Base.metadata.bind = engine
-    Base.metadata.create_all(engine)
-    try:
-        transaction.begin()
-        session = DBSession()
-        page = Page('FrontPage', 'initial data')
-        session.add(page)
-        transaction.commit()
-    except IntegrityError:
-        # already created
-        pass
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/views/tutorial/models/__init__.py
new file mode 100644
index 000000000..a8871f6f5
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/models/__init__.py
@@ -0,0 +1,74 @@
+from sqlalchemy import engine_from_config
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import configure_mappers
+import zope.sqlalchemy
+
+# import or define all models here to ensure they are attached to the
+# Base.metadata prior to any initialization routines
+from .page import Page # flake8: noqa
+from .user import User # flake8: noqa
+
+# run configure_mappers after defining all of the models to ensure
+# all relationships can be setup
+configure_mappers()
+
+
+def get_engine(settings, prefix='sqlalchemy.'):
+    return engine_from_config(settings, prefix)
+
+
+def get_session_factory(engine):
+    factory = sessionmaker()
+    factory.configure(bind=engine)
+    return factory
+
+
+def get_tm_session(session_factory, transaction_manager):
+    """
+    Get a ``sqlalchemy.orm.Session`` instance backed by a transaction.
+
+    This function will hook the session to the transaction manager which
+    will take care of committing any changes.
+
+    - When using pyramid_tm it will automatically be committed or aborted
+      depending on whether an exception is raised.
+
+    - When using scripts you should wrap the session in a manager yourself.
+      For example::
+
+          import transaction
+
+          engine = get_engine(settings)
+          session_factory = get_session_factory(engine)
+          with transaction.manager:
+              dbsession = get_tm_session(session_factory, transaction.manager)
+
+    """
+    dbsession = session_factory()
+    zope.sqlalchemy.register(
+        dbsession, transaction_manager=transaction_manager)
+    return dbsession
+
+
+def includeme(config):
+    """
+    Initialize the model for a Pyramid app.
+
+    Activate this setup using ``config.include('tutorial.models')``.
+
+    """
+    settings = config.get_settings()
+
+    # use pyramid_tm to hook the transaction lifecycle to the request
+    config.include('pyramid_tm')
+
+    session_factory = get_session_factory(get_engine(settings))
+    config.registry['dbsession_factory'] = session_factory
+
+    # make request.dbsession available for use in Pyramid
+    config.add_request_method(
+        # r.tm is the transaction manager used by pyramid_tm
+        lambda r: get_tm_session(session_factory, r.tm),
+        'dbsession',
+        reify=True
+    )
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models/meta.py b/docs/tutorials/wiki2/src/views/tutorial/models/meta.py
new file mode 100644
index 000000000..fc3e8f1dd
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/models/meta.py
@@ -0,0 +1,16 @@
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.schema import MetaData
+
+# Recommended naming convention used by Alembic, as various different database
+# providers will autogenerate vastly different names making migrations more
+# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+NAMING_CONVENTION = {
+    "ix": 'ix_%(column_0_label)s',
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s"
+}
+
+metadata = MetaData(naming_convention=NAMING_CONVENTION)
+Base = declarative_base(metadata=metadata)
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models/page.py b/docs/tutorials/wiki2/src/views/tutorial/models/page.py
new file mode 100644
index 000000000..4dd5b5721
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/models/page.py
@@ -0,0 +1,20 @@
+from sqlalchemy import (
+    Column,
+    ForeignKey,
+    Integer,
+    Text,
+)
+from sqlalchemy.orm import relationship
+
+from .meta import Base
+
+
+class Page(Base):
+    """ The SQLAlchemy declarative model class for a Page object. """
+    __tablename__ = 'pages'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text, nullable=False, unique=True)
+    data = Column(Integer, nullable=False)
+
+    creator_id = Column(ForeignKey('users.id'), nullable=False)
+    creator = relationship('User', backref='created_pages')
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models/user.py b/docs/tutorials/wiki2/src/views/tutorial/models/user.py
new file mode 100644
index 000000000..6bd3315d6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/models/user.py
@@ -0,0 +1,29 @@
+import bcrypt
+from sqlalchemy import (
+    Column,
+    Integer,
+    Text,
+)
+
+from .meta import Base
+
+
+class User(Base):
+    """ The SQLAlchemy declarative model class for a User object. """
+    __tablename__ = 'users'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text, nullable=False, unique=True)
+    role = Column(Text, nullable=False)
+
+    password_hash = Column(Text)
+
+    def set_password(self, pw):
+        pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
+        self.password_hash = pwhash
+
+    def check_password(self, pw):
+        if self.password_hash is not None:
+            expected_hash = self.password_hash
+            actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
+            return expected_hash == actual_hash
+        return False
diff --git a/docs/tutorials/wiki2/src/views/tutorial/routes.py b/docs/tutorials/wiki2/src/views/tutorial/routes.py
new file mode 100644
index 000000000..72df58efe
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/routes.py
@@ -0,0 +1,6 @@
+def includeme(config):
+    config.add_static_view('static', 'static', cache_max_age=3600)
+    config.add_route('view_wiki', '/')
+    config.add_route('view_page', '/{pagename}')
+    config.add_route('add_page', '/add_page/{pagename}')
+    config.add_route('edit_page', '/{pagename}/edit_page')
diff --git a/docs/tutorials/wiki2/src/views/tutorial/scripts/__init__.py b/docs/tutorials/wiki2/src/views/tutorial/scripts/__init__.py
new file mode 100644
index 000000000..5bb534f79
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/scripts/__init__.py
@@ -0,0 +1 @@
+# package
diff --git a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
new file mode 100644
index 000000000..f3c0a6fef
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
@@ -0,0 +1,57 @@
+import os
+import sys
+import transaction
+
+from pyramid.paster import (
+    get_appsettings,
+    setup_logging,
+    )
+
+from pyramid.scripts.common import parse_vars
+
+from ..models.meta import Base
+from ..models import (
+    get_engine,
+    get_session_factory,
+    get_tm_session,
+    )
+from ..models import Page, User
+
+
+def usage(argv):
+    cmd = os.path.basename(argv[0])
+    print('usage: %s <config_uri> [var=value]\n'
+          '(example: "%s development.ini")' % (cmd, cmd))
+    sys.exit(1)
+
+
+def main(argv=sys.argv):
+    if len(argv) < 2:
+        usage(argv)
+    config_uri = argv[1]
+    options = parse_vars(argv[2:])
+    setup_logging(config_uri)
+    settings = get_appsettings(config_uri, options=options)
+
+    engine = get_engine(settings)
+    Base.metadata.create_all(engine)
+
+    session_factory = get_session_factory(engine)
+
+    with transaction.manager:
+        dbsession = get_tm_session(session_factory, transaction.manager)
+
+        editor = User(name='editor', role='editor')
+        editor.set_password('editor')
+        dbsession.add(editor)
+
+        basic = User(name='basic', role='basic')
+        basic.set_password('basic')
+        dbsession.add(basic)
+
+        page = Page(
+            name='FrontPage',
+            creator=editor,
+            data='This is the front page',
+        )
+        dbsession.add(page)
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/favicon.ico b/docs/tutorials/wiki2/src/views/tutorial/static/favicon.ico
deleted file mode 100644
index 71f837c9e..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/static/favicon.ico
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/footerbg.png b/docs/tutorials/wiki2/src/views/tutorial/static/footerbg.png
deleted file mode 100644
index 1fbc873da..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/static/footerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/headerbg.png b/docs/tutorials/wiki2/src/views/tutorial/static/headerbg.png
deleted file mode 100644
index 0596f2020..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/static/headerbg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/ie6.css b/docs/tutorials/wiki2/src/views/tutorial/static/ie6.css
deleted file mode 100644
index b7c8493d8..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/static/ie6.css
+++ /dev/null
@@ -1,8 +0,0 @@
-* html img,
-* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
-this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
-this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
-);}
-#wrap{display:table;height:100%}
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/middlebg.png b/docs/tutorials/wiki2/src/views/tutorial/static/middlebg.png
deleted file mode 100644
index 2369cfb7d..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/static/middlebg.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/pylons.css b/docs/tutorials/wiki2/src/views/tutorial/static/pylons.css
deleted file mode 100644
index fd1914d8d..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/static/pylons.css
+++ /dev/null
@@ -1,65 +0,0 @@
-html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */
-vertical-align:baseline;background:transparent;}
-body{line-height:1;}
-ol,ul{list-style:none;}
-blockquote,q{quotes:none;}
-blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;}
-:focus{outline:0;}
-ins{text-decoration:none;}
-del{text-decoration:line-through;}
-table{border-collapse:collapse;border-spacing:0;}
-sub{vertical-align:sub;font-size:smaller;line-height:normal;}
-sup{vertical-align:super;font-size:smaller;line-height:normal;}
-ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;}
-ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;}
-li{display:list-item;}
-ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;}
-ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;}
-ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;}
-.hidden{display:none;}
-p{line-height:1.5em;}
-h1{font-size:1.75em;line-height:1.7em;font-family:helvetica,verdana;}
-h2{font-size:1.5em;line-height:1.7em;font-family:helvetica,verdana;}
-h3{font-size:1.25em;line-height:1.7em;font-family:helvetica,verdana;}
-h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;}
-html,body{width:100%;height:100%;}
-body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;}
-a{color:#1b61d6;text-decoration:none;}
-a:hover{color:#e88f00;text-decoration:underline;}
-body h1,
-body h2,
-body h3,
-body h4,
-body h5,
-body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;}
-#wrap{min-height:100%;}
-#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;}
-#header{background:#000000;top:0;font-size:14px;}
-#footer{bottom:0;background:#000000 url(footerbg.png) repeat-x 0 top;position:relative;margin-top:-40px;clear:both;}
-.header,.footer{width:750px;margin-right:auto;margin-left:auto;}
-.wrapper{width:100%}
-#top,#top-small,#bottom{width:100%;}
-#top{color:#000000;height:230px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#top-small{color:#000000;height:60px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
-#bottom{color:#222;background-color:#ffffff;}
-.top,.top-small,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;}
-.top{padding-top:40px;}
-.top-small{padding-top:10px;}
-#middle{width:100%;height:100px;background:url(middlebg.png) repeat-x;border-top:2px solid #ffffff;border-bottom:2px solid #b2b2b2;}
-.app-welcome{margin-top:25px;}
-.app-name{color:#000000;font-weight:bold;}
-.bottom{padding-top:50px;}
-#left{width:350px;float:left;padding-right:25px;}
-#right{width:350px;float:right;padding-left:25px;}
-.align-left{text-align:left;}
-.align-right{text-align:right;}
-.align-center{text-align:center;}
-ul.links{margin:0;padding:0;}
-ul.links li{list-style-type:none;font-size:14px;}
-form{border-style:none;}
-fieldset{border-style:none;}
-input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;}
-input[type=text],input[type=password]{width:205px;}
-input[type=submit]{background-color:#ddd;font-weight:bold;}
-/*Opera Fix*/
-body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;}
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/pyramid-16x16.png b/docs/tutorials/wiki2/src/views/tutorial/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/static/pyramid-16x16.png
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/pyramid-small.png b/docs/tutorials/wiki2/src/views/tutorial/static/pyramid-small.png
deleted file mode 100644
index a5bc0ade7..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/static/pyramid-small.png
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/pyramid.png b/docs/tutorials/wiki2/src/views/tutorial/static/pyramid.png
index 347e05549..4ab837be9 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/static/pyramid.png
+++ b/docs/tutorials/wiki2/src/views/tutorial/static/pyramid.png
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/theme.css b/docs/tutorials/wiki2/src/views/tutorial/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/tutorials/wiki2/src/views/tutorial/static/transparent.gif b/docs/tutorials/wiki2/src/views/tutorial/static/transparent.gif
deleted file mode 100644
index 0341802e5..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/static/transparent.gif
+++ /dev/null
diff --git a/docs/tutorials/wiki2/src/views/tutorial/templates/404.jinja2 b/docs/tutorials/wiki2/src/views/tutorial/templates/404.jinja2
new file mode 100644
index 000000000..37b0a16b6
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/templates/404.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid tutorial wiki</span> <span class="smaller">(based on TurboGears 20-Minute Wiki)</span></h1>
+  <p class="lead"><span class="font-semi-bold">404</span> Page Not Found</p>
+</div>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/views/tutorial/templates/edit.jinja2 b/docs/tutorials/wiki2/src/views/tutorial/templates/edit.jinja2
new file mode 100644
index 000000000..7db25c674
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/templates/edit.jinja2
@@ -0,0 +1,20 @@
+{% extends 'layout.jinja2' %}
+
+{% block subtitle %}Edit {{pagename}} - {% endblock subtitle %}
+
+{% block content %}
+<p>
+Editing <strong>{{pagename}}</strong>
+</p>
+<p>You can return to the
+<a href="{{request.route_url('view_page', pagename='FrontPage')}}">FrontPage</a>.
+</p>
+<form action="{{ save_url }}" method="post">
+<div class="form-group">
+    <textarea class="form-control" name="body" rows="10" cols="60">{{ pagedata }}</textarea>
+</div>
+<div class="form-group">
+    <button type="submit" name="form.submitted" value="Save" class="btn btn-default">Save</button>
+</div>
+</form>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/views/tutorial/templates/edit.pt b/docs/tutorials/wiki2/src/views/tutorial/templates/edit.pt
deleted file mode 100644
index 3f2039cb6..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/templates/edit.pt
+++ /dev/null
@@ -1,58 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
-      xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>${page.name} - Pyramid tutorial wiki (based on
-    TurboGears 20-Minute Wiki)</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon"
-        href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/pylons.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/ie6.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top-small">
-      <div class="top-small align-center">
-        <div>
-          <img width="220" height="50" alt="pyramid"
-        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
-        </div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-right">
-        <div id="left" class="app-welcome align-left">
-          Editing <b><span tal:replace="page.name">Page Name Goes
-            Here</span></b><br/>
-          You can return to the
-          <a href="${request.application_url}">FrontPage</a>.<br/>
-        </div>
-        <div id="right" class="app-welcome align-right"></div>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <form action="${save_url}" method="post">
-          <textarea name="body" tal:content="page.data" rows="10"
-                    cols="60"/><br/>
-          <input type="submit" name="form.submitted" value="Save"/>
-        </form>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer"
-         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
-</html>
diff --git a/docs/tutorials/wiki2/src/views/tutorial/templates/layout.jinja2 b/docs/tutorials/wiki2/src/views/tutorial/templates/layout.jinja2
new file mode 100644
index 000000000..71785157f
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/templates/layout.jinja2
@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html lang="{{request.locale_name}}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="{{request.static_url('tutorial:static/pyramid-16x16.png')}}">
+
+    <title>{% block subtitle %}{% endblock %}Pyramid tutorial wiki (based on TurboGears 20-Minute Wiki)</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="{{request.static_url('tutorial:static/theme.css')}}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="{{request.static_url('tutorial:static/pyramid.png')}}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            <div class="content">
+            {% block content %}{% endblock %}
+            </div>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt
deleted file mode 100644
index d98420680..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt
+++ /dev/null
@@ -1,75 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>The Pyramid Web Application Development Framework</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon" href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
-  <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton|Nobile:regular,i,b,bi&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet" href="${request.static_url('tutorial:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top">
-      <div class="top align-center">
-        <div><img src="${request.static_url('tutorial:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-center">
-        <p class="app-welcome">
-          Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web application development framework.
-        </p>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div id="left" class="align-right">
-          <h2>Search documentation</h2>
-          <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/dev/search.html">
-                <input type="text" id="q" name="q" value="" />
-                <input type="submit" id="x" value="Go" />
-            </form>
-        </div>
-        <div id="right" class="align-left">
-          <h2>Pyramid links</h2>
-          <ul class="links">
-            <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#narrative-documentation">Narrative Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#api-documentation">API Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#tutorials">Tutorials</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#change-history">Change History</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#sample-applications">Sample Applications</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#support-and-development">Support and Development</a>
-            </li>
-            <li>
-              <a href="irc://irc.freenode.net#pyramid">IRC Channel</a>
-            </li>
-            </ul>
-        </div>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
-</html>
diff --git a/docs/tutorials/wiki2/src/views/tutorial/templates/view.jinja2 b/docs/tutorials/wiki2/src/views/tutorial/templates/view.jinja2
new file mode 100644
index 000000000..94419e228
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/templates/view.jinja2
@@ -0,0 +1,18 @@
+{% extends 'layout.jinja2' %}
+
+{% block subtitle %}{{page.name}} - {% endblock subtitle %}
+
+{% block content %}
+<p>{{ content|safe }}</p>
+<p>
+<a href="{{ edit_url }}">
+    Edit this page
+</a>
+</p>
+<p>
+    Viewing <strong>{{page.name}}</strong>, created by <strong>{{page.creator.name}}</strong>.
+</p>
+<p>You can return to the
+<a href="{{request.route_url('view_page', pagename='FrontPage')}}">FrontPage</a>.
+</p>
+{% endblock content %}
diff --git a/docs/tutorials/wiki2/src/views/tutorial/templates/view.pt b/docs/tutorials/wiki2/src/views/tutorial/templates/view.pt
deleted file mode 100644
index 423c1d5a1..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/templates/view.pt
+++ /dev/null
@@ -1,61 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
-      xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>${page.name} - Pyramid tutorial wiki (based on
-    TurboGears 20-Minute Wiki)</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon"
-        href="${request.static_url('tutorial:static/favicon.ico')}" />
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/pylons.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet"
-        href="${request.static_url('tutorial:static/ie6.css')}"
-        type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top-small">
-      <div class="top-small align-center">
-        <div>
-          <img width="220" height="50" alt="pyramid"
-        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
-        </div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-right">
-        <div id="left" class="app-welcome align-left">
-          Viewing <b><span tal:replace="page.name">Page Name
-              Goes Here</span></b><br/>
-          You can return to the
-          <a href="${request.application_url}">FrontPage</a>.<br/>
-        </div>
-        <div id="right" class="app-welcome align-right"></div>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div tal:replace="structure content">
-          Page text goes here.
-        </div>
-        <p>
-          <a tal:attributes="href edit_url" href="">
-            Edit this page
-          </a>
-        </p>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer"
-         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
-  </div>
-</body>
-</html>
diff --git a/docs/tutorials/wiki2/src/views/tutorial/tests.py b/docs/tutorials/wiki2/src/views/tutorial/tests.py
index 0bc343833..99e95efd3 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/tests.py
@@ -1,139 +1,65 @@
 import unittest
+import transaction
 
 from pyramid import testing
 
-def _initTestingDB():
-    from tutorial.models import DBSession
-    from tutorial.models import Base
-    from sqlalchemy import create_engine
-    engine = create_engine('sqlite://')
-    DBSession.configure(bind=engine)
-    Base.metadata.bind = engine
-    Base.metadata.create_all(engine)
-    return DBSession
-
-def _registerRoutes(config):
-    config.add_route('view_page', '{pagename}')
-    config.add_route('edit_page', '{pagename}/edit_page')
-    config.add_route('add_page', 'add_page/{pagename}')
-
-class ViewWikiTests(unittest.TestCase):
+
+def dummy_request(dbsession):
+    return testing.DummyRequest(dbsession=dbsession)
+
+
+class BaseTest(unittest.TestCase):
     def setUp(self):
-        self.config = testing.setUp()
+        self.config = testing.setUp(settings={
+            'sqlalchemy.url': 'sqlite:///:memory:'
+        })
+        self.config.include('.models')
+        settings = self.config.get_settings()
 
-    def tearDown(self):
-        testing.tearDown()
+        from .models import (
+            get_engine,
+            get_session_factory,
+            get_tm_session,
+            )
 
-    def _callFUT(self, request):
-        from tutorial.views import view_wiki
-        return view_wiki(request)
+        self.engine = get_engine(settings)
+        session_factory = get_session_factory(self.engine)
 
-    def test_it(self):
-        _registerRoutes(self.config)
-        request = testing.DummyRequest()
-        response = self._callFUT(request)
-        self.assertEqual(response.location, 'http://example.com/FrontPage')
+        self.session = get_tm_session(session_factory, transaction.manager)
 
-class ViewPageTests(unittest.TestCase):
-    def setUp(self):
-        self.session = _initTestingDB()
-        self.config = testing.setUp()
+    def init_database(self):
+        from .models.meta import Base
+        Base.metadata.create_all(self.engine)
 
     def tearDown(self):
-        self.session.remove()
-        testing.tearDown()
-        
-    def _callFUT(self, request):
-        from tutorial.views import view_page
-        return view_page(request)
-
-    def test_it(self):
-        from tutorial.models import Page
-        request = testing.DummyRequest()
-        request.matchdict['pagename'] = 'IDoExist'
-        page = Page('IDoExist', 'Hello CruelWorld IDoExist')
-        self.session.add(page)
-        _registerRoutes(self.config)
-        info = self._callFUT(request)
-        self.assertEqual(info['page'], page)
-        self.assertEqual(
-            info['content'], 
-            '<div class="document">\n'
-            '<p>Hello <a href="http://example.com/add_page/CruelWorld">'
-            'CruelWorld</a> '
-            '<a href="http://example.com/IDoExist">'
-            'IDoExist</a>'
-            '</p>\n</div>\n')
-        self.assertEqual(info['edit_url'],
-                         'http://example.com/IDoExist/edit_page')
-        
-    
-class AddPageTests(unittest.TestCase):
-    def setUp(self):
-        self.session = _initTestingDB()
-        self.config = testing.setUp()
-        self.config.begin()
+        from .models.meta import Base
 
-    def tearDown(self):
-        self.session.remove()
         testing.tearDown()
+        transaction.abort()
+        Base.metadata.drop_all(self.engine)
+
+
+class TestMyViewSuccessCondition(BaseTest):
 
-    def _callFUT(self, request):
-        from tutorial.views import add_page
-        return add_page(request)
-
-    def test_it_notsubmitted(self):
-        _registerRoutes(self.config)
-        request = testing.DummyRequest()
-        request.matchdict = {'pagename':'AnotherPage'}
-        info = self._callFUT(request)
-        self.assertEqual(info['page'].data,'')
-        self.assertEqual(info['save_url'],
-                         'http://example.com/add_page/AnotherPage')
-        
-    def test_it_submitted(self):
-        from tutorial.models import Page
-        _registerRoutes(self.config)
-        request = testing.DummyRequest({'form.submitted':True,
-                                        'body':'Hello yo!'})
-        request.matchdict = {'pagename':'AnotherPage'}
-        self._callFUT(request)
-        page = self.session.query(Page).filter_by(name='AnotherPage').one()
-        self.assertEqual(page.data, 'Hello yo!')
-
-class EditPageTests(unittest.TestCase):
     def setUp(self):
-        self.session = _initTestingDB()
-        self.config = testing.setUp()
+        super(TestMyViewSuccessCondition, self).setUp()
+        self.init_database()
 
-    def tearDown(self):
-        self.session.remove()
-        testing.tearDown()
+        from .models import MyModel
+
+        model = MyModel(name='one', value=55)
+        self.session.add(model)
+
+    def test_passing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info['one'].name, 'one')
+        self.assertEqual(info['project'], 'tutorial')
+
+
+class TestMyViewFailureCondition(BaseTest):
 
-    def _callFUT(self, request):
-        from tutorial.views import edit_page
-        return edit_page(request)
-
-    def test_it_notsubmitted(self):
-        from tutorial.models import Page
-        _registerRoutes(self.config)
-        request = testing.DummyRequest()
-        request.matchdict = {'pagename':'abc'}
-        page = Page('abc', 'hello')
-        self.session.add(page)
-        info = self._callFUT(request)
-        self.assertEqual(info['page'], page)
-        self.assertEqual(info['save_url'],
-                         'http://example.com/abc/edit_page')
-        
-    def test_it_submitted(self):
-        from tutorial.models import Page
-        _registerRoutes(self.config)
-        request = testing.DummyRequest({'form.submitted':True,
-                                        'body':'Hello yo!'})
-        request.matchdict = {'pagename':'abc'}
-        page = Page('abc', 'hello')
-        self.session.add(page)
-        response = self._callFUT(request)
-        self.assertEqual(response.location, 'http://example.com/abc')
-        self.assertEqual(page.data, 'Hello yo!')
+    def test_failing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info.status_int, 500)
diff --git a/docs/tutorials/wiki2/src/views/tutorial/views.py b/docs/tutorials/wiki2/src/views/tutorial/views.py
deleted file mode 100644
index f3d7f4a99..000000000
--- a/docs/tutorials/wiki2/src/views/tutorial/views.py
+++ /dev/null
@@ -1,65 +0,0 @@
-import re
-
-from docutils.core import publish_parts
-
-from pyramid.httpexceptions import HTTPFound, HTTPNotFound
-from pyramid.url import route_url
-
-from tutorial.models import DBSession
-from tutorial.models import Page
-
-# regular expression used to find WikiWords
-wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")
-
-def view_wiki(request):
-    return HTTPFound(location = route_url('view_page', request,
-                                          pagename='FrontPage'))
-
-def view_page(request):
-    pagename = request.matchdict['pagename']
-    session = DBSession()
-    page = session.query(Page).filter_by(name=pagename).first()
-    if page is None:
-        return HTTPNotFound('No such page')
-
-    def check(match):
-        word = match.group(1)
-        exists = session.query(Page).filter_by(name=word).all()
-        if exists:
-            view_url = route_url('view_page', request, pagename=word)
-            return '<a href="%s">%s</a>' % (view_url, word)
-        else:
-            add_url = route_url('add_page', request, pagename=word)
-            return '<a href="%s">%s</a>' % (add_url, word)
-
-    content = publish_parts(page.data, writer_name='html')['html_body']
-    content = wikiwords.sub(check, content)
-    edit_url = route_url('edit_page', request, pagename=pagename)
-    return dict(page=page, content=content, edit_url=edit_url)
-
-def add_page(request):
-    name = request.matchdict['pagename']
-    if 'form.submitted' in request.params:
-        session = DBSession()
-        body = request.params['body']
-        page = Page(name, body)
-        session.add(page)
-        return HTTPFound(location = route_url('view_page', request,
-                                              pagename=name))
-    save_url = route_url('add_page', request, pagename=name)
-    page = Page('', '')
-    return dict(page=page, save_url=save_url)
-
-def edit_page(request):
-    name = request.matchdict['pagename']
-    session = DBSession()
-    page = session.query(Page).filter_by(name=name).one()
-    if 'form.submitted' in request.params:
-        page.data = request.params['body']
-        session.add(page)
-        return HTTPFound(location = route_url('view_page', request,
-                                              pagename=name))
-    return dict(
-        page=page,
-        save_url = route_url('edit_page', request, pagename=name),
-        )
diff --git a/docs/tutorials/wiki2/src/views/tutorial/views/__init__.py b/docs/tutorials/wiki2/src/views/tutorial/views/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/views/__init__.py
diff --git a/docs/tutorials/wiki2/src/views/tutorial/views/default.py b/docs/tutorials/wiki2/src/views/tutorial/views/default.py
new file mode 100644
index 000000000..bb6300b75
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/views/default.py
@@ -0,0 +1,73 @@
+import cgi
+import re
+from docutils.core import publish_parts
+
+from pyramid.httpexceptions import (
+    HTTPFound,
+    HTTPNotFound,
+    )
+
+from pyramid.view import view_config
+
+from ..models import Page, User
+
+# regular expression used to find WikiWords
+wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")
+
+@view_config(route_name='view_wiki')
+def view_wiki(request):
+    next_url = request.route_url('view_page', pagename='FrontPage')
+    return HTTPFound(location=next_url)
+
+@view_config(route_name='view_page', renderer='../templates/view.jinja2')
+def view_page(request):
+    pagename = request.matchdict['pagename']
+    page = request.dbsession.query(Page).filter_by(name=pagename).first()
+    if page is None:
+        raise HTTPNotFound('No such page')
+
+    def add_link(match):
+        word = match.group(1)
+        exists = request.dbsession.query(Page).filter_by(name=word).all()
+        if exists:
+            view_url = request.route_url('view_page', pagename=word)
+            return '<a href="%s">%s</a>' % (view_url, cgi.escape(word))
+        else:
+            add_url = request.route_url('add_page', pagename=word)
+            return '<a href="%s">%s</a>' % (add_url, cgi.escape(word))
+
+    content = publish_parts(page.data, writer_name='html')['html_body']
+    content = wikiwords.sub(add_link, content)
+    edit_url = request.route_url('edit_page', pagename=page.name)
+    return dict(page=page, content=content, edit_url=edit_url)
+
+@view_config(route_name='edit_page', renderer='../templates/edit.jinja2')
+def edit_page(request):
+    pagename = request.matchdict['pagename']
+    page = request.dbsession.query(Page).filter_by(name=pagename).one()
+    if 'form.submitted' in request.params:
+        page.data = request.params['body']
+        next_url = request.route_url('view_page', pagename=page.name)
+        return HTTPFound(location=next_url)
+    return dict(
+        pagename=page.name,
+        pagedata=page.data,
+        save_url=request.route_url('edit_page', pagename=page.name),
+        )
+
+@view_config(route_name='add_page', renderer='../templates/edit.jinja2')
+def add_page(request):
+    pagename = request.matchdict['pagename']
+    if request.dbsession.query(Page).filter_by(name=pagename).count() > 0:
+        next_url = request.route_url('edit_page', pagename=pagename)
+        return HTTPFound(location=next_url)
+    if 'form.submitted' in request.params:
+        body = request.params['body']
+        page = Page(name=pagename, data=body)
+        page.creator = (
+            request.dbsession.query(User).filter_by(name='editor').one())
+        request.dbsession.add(page)
+        next_url = request.route_url('view_page', pagename=pagename)
+        return HTTPFound(location=next_url)
+    save_url = request.route_url('add_page', pagename=pagename)
+    return dict(pagename=pagename, pagedata='', save_url=save_url)
diff --git a/docs/tutorials/wiki2/src/views/tutorial/views/notfound.py b/docs/tutorials/wiki2/src/views/tutorial/views/notfound.py
new file mode 100644
index 000000000..69d6e2804
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/views/notfound.py
@@ -0,0 +1,7 @@
+from pyramid.view import notfound_view_config
+
+
+@notfound_view_config(renderer='../templates/404.jinja2')
+def notfound_view(request):
+    request.response.status = 404
+    return {}
diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst
index 7a4e65529..e923ff9cb 100644
--- a/docs/tutorials/wiki2/tests.rst
+++ b/docs/tutorials/wiki2/tests.rst
@@ -1,74 +1,108 @@
+.. _wiki2_adding_tests:
+
 ============
 Adding Tests
 ============
 
-We will now add tests for the models and the views and a few functional
-tests in the ``tests.py``.  Tests ensure that an application works, and
-that it continues to work after some changes are made in the future.
+We will now add tests for the models and views as well as a few functional
+tests in a new ``tests`` subpackage.  Tests ensure that an application works,
+and that it continues to work when changes are made in the future.
 
-Testing the Models
-==================
+The file ``tests.py`` was generated as part of the ``alchemy`` scaffold, but it
+is a common practice to put tests into a ``tests`` subpackage, especially as
+projects grow in size and complexity.  Each module in the test subpackage
+should contain tests for its corresponding module in our application.  Each
+corresponding pair of modules should have the same names, except the test
+module should have the prefix ``test_``.
 
-We write a test class for the model class ``Page`` and another test class
-for the ``initialize_sql`` function.
+Start by deleting ``tests.py``, then create a new directory to contain our new
+tests as well as a new empty file ``tests/__init__.py``.
 
-To do so, we'll retain the ``tutorial.tests.ViewTests`` class provided as a
-result of the ``pyramid_routesalchemy`` project generator.  We'll add two
-test classes: one for the ``Page`` model named ``PageModelTests``, one for the
-``initialize_sql`` function named ``InitializeSqlTests``.
+.. warning::
 
-Testing the Views
-=================
+   It is very important when refactoring a Python module into a package to be
+   sure to delete the cache files (``.pyc`` files or ``__pycache__`` folders)
+   sitting around! Python will prioritize the cache files before traversing
+   into folders, using the old code, and you will wonder why none of your
+   changes are working!
+
+
+Test the views
+==============
+
+We'll create a new ``tests/test_views.py`` file, adding a ``BaseTest`` class
+used as the base for other test classes. Next we'll add tests for each view
+function we previously added to our application. We'll add four test classes:
+``ViewWikiTests``, ``ViewPageTests``, ``AddPageTests``, and ``EditPageTests``.
+These test the ``view_wiki``, ``view_page``, ``add_page``, and ``edit_page``
+views.
 
-We'll modify our ``tests.py`` file, adding tests for each view function we
-added above.  As a result, we'll *delete* the ``ViewTests`` test in the file,
-and add four other test classes: ``ViewWikiTests``, ``ViewPageTests``,
-``AddPageTests``, and ``EditPageTests``.  These test the ``view_wiki``,
-``view_page``, ``add_page``, and ``edit_page`` views respectively.
 
 Functional tests
 ================
 
-We test the whole application, covering security aspects that are not
-tested in the unit tests, like logging in, logging out, checking that
-the ``viewer`` user cannot add or edit pages, but the ``editor`` user
-can, and so on.
+We'll test the whole application, covering security aspects that are not tested
+in the unit tests, like logging in, logging out, checking that the ``basic``
+user cannot edit pages that it didn't create but the ``editor`` user can, and
+so on.
 
-Viewing the results of all our edits to ``tests.py``
-====================================================
 
-Once we're done with the ``tests.py`` module, it will look a lot like the
-below:
+View the results of all our edits to ``tests`` subpackage
+=========================================================
 
-.. literalinclude:: src/tests/tutorial/tests.py
+Open ``tutorial/tests/test_views.py``, and edit it such that it appears as
+follows:
+
+.. literalinclude:: src/tests/tutorial/tests/test_views.py
    :linenos:
    :language: python
 
-Running the Tests
+Open ``tutorial/tests/test_functional.py``, and edit it such that it appears as
+follows:
+
+.. literalinclude:: src/tests/tutorial/tests/test_functional.py
+   :linenos:
+   :language: python
+
+
+.. note::
+
+   We're utilizing the excellent WebTest_ package to do functional testing of
+   the application. This is defined in the ``tests_require`` section of our
+   ``setup.py``. Any other dependencies needed only for testing purposes can be
+   added there and will be installed automatically when running
+   ``setup.py test``.
+
+
+Running the tests
 =================
 
-We can run these tests by using ``setup.py test`` in the same way we did in
-:ref:`running_tests`.  Assuming our shell's current working directory is the
-"tutorial" distribution directory:
+We can run these tests similarly to how we did in :ref:`running_tests`:
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
-   $ ../bin/python setup.py test -q
+   $ $VENV/bin/py.test -q
 
 On Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test -q
 
-The expected result looks something like:
+The expected result should look like the following:
 
 .. code-block:: text
 
    ......................
-   ----------------------------------------------------------------------
-   Ran 22 tests in 2.700s
+   22 passed, 1 pytest-warnings in 5.81 seconds
+
+.. note:: If you use Python 3 during this tutorial, you will see deprecation
+   warnings in the output, which we will choose to ignore. In making this
+   tutorial run on both Python 2 and 3, the authors prioritized simplicity and
+   focus for the learner over accommodating warnings. In your own app or as
+   extra credit, you may choose to either drop Python 2 support or hack your
+   code to work without warnings on both Python 2 and 3.
 
-   OK
+.. _webtest: http://docs.pylonsproject.org/projects/webtest/en/latest/