Merge branch 'ppaez-zodb-tutorial'

4 files changed, 85 insertions, 84 deletions

diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst
index 8352c5344..3d2d01061 100644
--- a/docs/tutorials/wiki/definingmodels.rst
+++ b/docs/tutorials/wiki/definingmodels.rst
@@ -127,22 +127,6 @@ When we're done changing ``tests.py``, it will look something like so:
    :linenos:
    :language: python
 
-Declaring Dependencies in Our ``setup.py`` File
------------------------------------------------
-
-Our application now depends on packages which are not dependencies of the
-original "tutorial" application as it was generated by the ``paster create``
-command.  We'll add these dependencies to our ``tutorial`` package's
-``setup.py`` file by assigning these dependencies to both the
-``install_requires`` and the ``tests_require`` parameters to the ``setup``
-function.  In particular, we require the ``docutils`` package.
-
-Our resulting ``setup.py`` should look like so:
-
-.. literalinclude:: src/models/setup.py
-   :linenos:
-   :language: python
-
 Running the Tests
 -----------------
 
diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst
index 31900233c..233e571f1 100644
--- a/docs/tutorials/wiki/definingviews.rst
+++ b/docs/tutorials/wiki/definingviews.rst
@@ -2,38 +2,26 @@
 Defining Views
 ==============
 
-Conventionally, :term:`view callable` objects are defined within a
-``views.py`` module in an :app:`Pyramid` application.  There is nothing
-automagically special about the filename ``views.py``.  Files implementing
-views 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.  A project may have many views throughout its codebase in
-arbitrarily-named files.  In this application, however, we'll be continuing
-to use the ``views.py`` module, because there's no reason to break
-convention.
-
-A :term:`view callable` in a :app:`Pyramid` application is typically a simple
-Python function that accepts a single parameter: :term:`request`.  A view
-callable is assumed to return a :term:`response` object.
-
-However, a :app:`Pyramid` view can also be defined as callable which accepts
-*two* arguments: a :term:`context` and a :term:`request`.  In :term:`url
-dispatch` based applications, the context resource is rarely used in the view
-body itself, so within code that uses URL-dispatch-only, it's common to
-define views as callables that accept only a ``request`` to avoid the visual
-"noise" of a ``context`` argument.  This application, however, uses
-:term:`traversal` to map URLs 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 it represents the persistent storage
-of our application.  For this reason, having ``context`` in the callable
-argument list is not "noise" to us; instead it's actually rather important
-within the view code we'll define in this application.
-
-The single-arg (``request`` -only) or two-arg (``context`` and ``request``)
-calling conventions will work in any :app:`Pyramid` application for any view;
-they can be used interchangeably as necessary.  We'll be using the
-two-argument ``(context, request)`` view callable argument list syntax in
-this application.
+A :term:`view callable` in a :term:`traversal` -based :app:`Pyramid`
+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
+   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
+   :app:`Pyramid` application; the calling conventions can be used
+   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
+   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
+   need the ``context`` within a view function that only takes
+   the request as a single argument, you can obtain it via
+   ``request.context``.
 
 We're going to define several :term:`view callable` functions then wire them
 into :app:`Pyramid` using some :term:`view configuration`.
@@ -42,6 +30,28 @@ 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.
+
+Our resulting ``setup.py`` should look like so:
+
+.. literalinclude:: src/views/setup.py
+   :linenos:
+   :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.
+
 Adding View Functions
 =====================
 
@@ -51,6 +61,14 @@ 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.
 
+.. 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.
+
 The ``view_wiki`` view function
 -------------------------------
 
@@ -173,7 +191,7 @@ 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
 a Page resource is the context, and a :term:`view name` exists as the result
-of traverasal named ``edit_page``, this view will be used.  We inform
+of traversal named ``edit_page``, this view will be used.  We inform
 :app:`Pyramid` this view will use the ``templates/edit.pt`` template file as
 a ``renderer``.
 
@@ -193,8 +211,8 @@ 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 Our Edits to ``views.py``
-===============================================
+Viewing the Result of all Our Edits to ``views.py``
+===================================================
 
 The result of all of our edits to ``views.py`` will leave it looking like
 this:
@@ -269,12 +287,38 @@ replicate within the body of this guide, however it is available `online
 
 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__`` file.  Any
+``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.
 
+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.
+
+- 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.
+
+- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser
+  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.
+
+- 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`.
+
 Testing the Views
 =================
 
@@ -319,29 +363,3 @@ The expected result looks something like:
    Ran 9 tests in 0.203s
    
    OK
-
-Viewing the Application in a Browser
-====================================
-
-Once we've completed our edits, 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.
-
-- 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.
-
-- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser
-  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.
-
-- 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`.
diff --git a/docs/tutorials/wiki/src/models/setup.py b/docs/tutorials/wiki/src/models/setup.py
index daa5e5eb1..2d540d65b 100644
--- a/docs/tutorials/wiki/src/models/setup.py
+++ b/docs/tutorials/wiki/src/models/setup.py
@@ -13,7 +13,6 @@ requires = [
     'repoze.retry',
     'ZODB3',
     'WebError',
-    'docutils',
     ]
 
 setup(name='tutorial',
@@ -21,9 +20,8 @@ setup(name='tutorial',
       description='tutorial',
       long_description=README + '\n\n' +  CHANGES,
       classifiers=[
-        "Intended Audience :: Developers",
-        "Framework :: Pylons",
         "Programming Language :: Python",
+        "Framework :: Pylons",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -34,8 +32,8 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      install_requires=requires,
-      tests_require=requires,
+      install_requires = requires,
+      tests_require= requires,
       test_suite="tutorial",
       entry_points = """\
       [paste.app_factory]
@@ -43,3 +41,4 @@ setup(name='tutorial',
       """,
       paster_plugins=['pyramid'],
       )
+
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index 874c49d4c..c5a452d11 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -262,7 +262,7 @@ to replicate within the body of this guide, however it is available `online
 
 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__`` file.  Any
+``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``