Update models and view application sections

1 files changed, 67 insertions, 47 deletions

diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst
index 3f1cdf007..81dd25862 100644
--- a/docs/tutorials/wiki/definingmodels.rst
+++ b/docs/tutorials/wiki/definingmodels.rst
@@ -25,65 +25,85 @@ It is always fine to do this as long as you don't care about the content of the
 The database itself will be recreated as necessary.
 
 
-Edit ``models.py``
-------------------
+Edit ``models`` package
+-----------------------
 
 .. note::
 
-  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.
+    There is nothing special about the package name ``models``.
+    A project may have many models throughout its codebase in arbitrarily named files and directories.
+    Files that implement models often have ``model`` in their names, 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:
+Open ``tutorial/models/__init__.py`` file and edit it to look like the following:
 
-.. literalinclude:: src/models/tutorial/models.py
+.. literalinclude:: src/models/tutorial/models/__init__.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.
-
-Then we'll add an import at the top for the :class:`persistent.Persistent` class.  We'll use this for a new ``Page`` class in a moment.
-
-Then we'll add a ``Wiki`` class.  We want it to inherit from the
-:class:`persistent.mapping.PersistentMapping` class because it provides
-mapping behavior, and it makes sure that our Wiki page is stored as a
-"first-class" persistent object in our ZODB database.
-
-Our ``Wiki`` class should have two attributes set to ``None`` at
-class scope: ``__parent__`` and ``__name__``.  If a model has a
-``__parent__`` attribute of ``None`` in a traversal-based :app:`Pyramid`
-application, it means that it's the :term:`root` model.  The ``__name__``
-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.
-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 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
-``models.py`` file so that the :term:`root` :term:`resource` of our
-application is a Wiki instance.  We'll also slot a single page object (the
-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.
+Remove the ``MyModel`` class from the generated ``models/__init__.py`` file.
+The ``MyModel`` class is only a sample and we're not going to use it.
+
+Next we add an import at the top for the :class:`persistent.Persistent` class.
+We will use this for a new ``Page`` class in a moment.
+
+.. literalinclude:: src/models/tutorial/models/__init__.py
+    :lines: 1-2
+    :lineno-match:
+    :emphasize-lines: 1
+    :language: py
+
+Then we add a ``Wiki`` class.
+
+.. literalinclude:: src/models/tutorial/models/__init__.py
+    :lines: 4-6
+    :lineno-match:
+    :language: py
+
+We want it to inherit from the :class:`persistent.mapping.PersistentMapping` class because it provides mapping behavior.
+It also makes sure that our ``Wiki`` page is stored as a "first-class" persistent object in our ZODB database.
+
+Our ``Wiki`` class should have two attributes set to ``None`` at class scope: ``__parent__`` and ``__name__``.
+If a model has a ``__parent__`` attribute of ``None`` in a traversal-based :app:`Pyramid` application, it means that it is the :term:`root` model.
+The ``__name__`` of the root model is also always ``None``.
+
+Now we add a ``Page`` class.
+
+.. literalinclude:: src/models/tutorial/models/__init__.py
+    :lines: 8-10
+    :lineno-match:
+    :language: py
+
+This class should inherit from the :class:`persistent.Persistent` class.
+We will 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.
+
+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 do not specify these here.
+Instead both ``__name__`` and ``__parent__`` will be set by a :term:`view` function when a ``Page`` is added to our ``Wiki`` mapping.
+We will create this function in the next chapter.
+
+As a last step, edit the ``appmaker`` function.
+
+.. literalinclude:: src/models/tutorial/models/__init__.py
+    :lines: 12-20
+    :lineno-match:
+    :emphasize-lines: 4-8
+    :language: py
+
+The :term:`root` :term:`resource` of our application is a Wiki instance.
+
+We will also slot a single page object (the 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.
+
 
 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 (See
-:ref:`wiki-start-the-application`), you'll wind
-up with a Python traceback on your console that ends with this exception:
+We cannot.
+At this point, our system is in a "non-runnable" state
+We will 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 (See :ref:`wiki-start-the-application`), you will wind up with a Python traceback on your console that ends with this exception:
 
 .. code-block:: text