Update narr/project.rst and /myproject starter cookiecutter source files

1 files changed, 78 insertions, 46 deletions

diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index f41e155e7..fb5a241db 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -525,21 +525,27 @@ The ``myproject`` project we've generated has the following directory structure:
 
 .. code-block:: text
 
-    myproject/
+    myproject
     ├── .coveragerc
+    ├── .gitignore
     ├── CHANGES.txt
     ├── MANIFEST.in
     ├── myproject
     │   ├── __init__.py
+    │   ├── routes.py
     │   ├── static
     │   │   ├── pyramid-16x16.png
     │   │   ├── pyramid.png
     │   │   └── theme.css
     │   ├── templates
+    │   │   ├── 404.jinja2
     │   │   ├── layout.jinja2
     │   │   └── mytemplate.jinja2
     │   ├── tests.py
-    │   └── views.py
+    │   └── views
+    │       ├── __init__.py
+    │       ├── default.py
+    │       └── notfound.py
     ├── README.txt
     ├── development.ini
     ├── production.ini
@@ -557,6 +563,8 @@ describe, run, and test your application.
 
 #. ``.coveragerc`` configures coverage when running tests.
 
+#. ``.gitignore`` tells git which files and directories to ignore from source code version control.
+
 #. ``CHANGES.txt`` describes the changes you've made to the application.  It is
    conventionally written in :term:`reStructuredText` format.
 
@@ -810,7 +818,9 @@ The ``myproject`` :term:`package` lives inside the ``myproject``
 
 #. A ``tests.py`` module, which contains unit test code for the application.
 
-#. A ``views.py`` module, which contains view code for the application.
+#. A ``views`` package, which contains view code for the application.
+
+#. A ``static`` directory, which contains static files, including images and CSS.
 
 These are purely conventions established by the cookiecutter. :app:`Pyramid`
 doesn't insist that you name things in any particular way. However, it's
@@ -848,31 +858,53 @@ also informs Python that the directory which contains it is a *package*.
    Line 8 adds support for Jinja2 templating bindings, allowing us to
    specify renderers with the ``.jinja2`` extension.
 
-   Line 9 registers a static view, which will serve up the files from the
-   ``myproject:static`` :term:`asset specification` (the ``static`` directory
-   of the ``myproject`` package).
+   Line 9 includes the ``routes.py`` module.
 
-   Line 10 adds a :term:`route` to the configuration.  This route is later used
-   by a view in the ``views`` module.
-
-   Line 11 calls ``config.scan()``, which picks up view registrations declared
+   Line 10 calls ``config.scan()``, which picks up view registrations declared
    elsewhere in the package (in this case, in the ``views.py`` module).
 
-   Line 12 returns a :term:`WSGI` application to the caller of the function
+   Line 11 returns a :term:`WSGI` application to the caller of the function
    (Pyramid's pserve).
 
+
+.. index::
+    single: routes.py
+
+.. _routes_py:
+
+``routes.py``
+~~~~~~~~~~~~~
+
+The ``routes.py`` module gets included by the ``main`` function in our ``__init__.py``.
+It registers a view and a route.
+
+.. literalinclude:: myproject/myproject/routes.py
+    :language: python
+    :linenos:
+
+Line 2 registers a static view, which will serve up the files from the ``myproject:static`` :term:`asset specification` (the ``static`` directory of the ``myproject`` package).
+
+Line 3 adds a :term:`route` to the configuration.  This route is later used by a view in the ``views`` module.
+
+
 .. index::
    single: views.py
 
-``views.py``
-~~~~~~~~~~~~
+``views`` package
+~~~~~~~~~~~~~~~~~
 
 Much of the heavy lifting in a :app:`Pyramid` application is done by *view
 callables*.  A :term:`view callable` is the main tool of a :app:`Pyramid` web
 application developer; it is a bit of code which accepts a :term:`request` and
 which returns a :term:`response`.
 
-.. literalinclude:: myproject/myproject/views.py
+Our project has a ``views`` package by virtue of it being a directory containing an ``__init__.py`` file.
+This ``__init__.py`` file happens to have no content, although it could as a project develops.
+
+We have two view modules in the ``views`` package.
+Let's look at ``default.py``.
+
+.. literalinclude:: myproject/myproject/views/default.py
    :language: python
    :linenos:
 
@@ -880,17 +912,17 @@ Lines 4-6 define and register a :term:`view callable` named ``my_view``.  The
 function named ``my_view`` is decorated with a ``view_config`` decorator (which
 is processed by the ``config.scan()`` line in our ``__init__.py``). The
 view_config decorator asserts that this view be found when a :term:`route`
-named ``home`` is matched.  In our case, because our ``__init__.py`` maps the
+named ``home`` is matched.  In our case, because our ``routes.py`` maps the
 route named ``home`` to the URL pattern ``/``, this route will match when a
 visitor visits the root URL.  The view_config decorator also names a
 ``renderer``, which in this case is a template that will be used to render the
 result of the view callable.  This particular view declaration points at
-``templates/mytemplate.pt``, which is an :term:`asset specification` that
-specifies the ``mytemplate.pt`` file within the ``templates`` directory of the
+``../templates/mytemplate.jinja2``, which is an :term:`asset specification` that
+specifies the ``mytemplate.jinja2`` file within the ``templates`` directory of the
 ``myproject`` package.  The asset specification could have also been specified
-as ``myproject:templates/mytemplate.pt``; the leading package name and colon is
+as ``myproject:templates/mytemplate.jinja2``; the leading package name and colon is
 optional.  The template file pointed to is a :term:`Jinja2` template
-file (``templates/my_template.jinja2``).
+file (``templates/mytemplate.jinja2``).
 
 This view callable function is handed a single piece of information: the
 :term:`request`.  The *request* is an instance of the :term:`WebOb` ``Request``
@@ -903,6 +935,15 @@ the HTML in a :term:`response`.
 
 .. note:: Dictionaries provide values to :term:`template`\s.
 
+Now let's look at ``notfound.py``.
+
+.. literalinclude:: myproject/myproject/views/notfound.py
+   :language: python
+   :linenos:
+
+This file is similar to ``default.py``.
+It merely returns a ``404`` response status and an empty dictionary to the template at ``../templates/404.jinja2``.
+
 .. note:: When the application is run with the cookiecutter's :ref:`default
    development.ini <myproject_ini>` configuration, :ref:`logging is set up
    <myproject_ini_logging>` to aid debugging.  If an exception is raised,
@@ -964,7 +1005,7 @@ This is the base layout content. It contains a single marker for content block.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is the content :term:`Jinja2` template that exists in the project.  It is referenced by the call to ``@view_config`` as the ``renderer``
-of the ``my_view`` view callable in the ``views.py`` file.  See
+of the ``my_view`` view callable in the ``views/default.py`` file.  See
 :ref:`views_which_use_a_renderer` for more information about renderers. It inherits ("extends") the HTML provided by ``layout.jinja2``, replacing the content block with its own content.
 
 .. literalinclude:: myproject/myproject/templates/mytemplate.jinja2
@@ -976,6 +1017,18 @@ functions themselves.  See :ref:`templates_used_directly` and
 :ref:`templates_used_as_renderers`.
 
 
+``templates/404.jinja2``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This template is similar to ``mytemplate.jinja2``, but with a few differences.
+It is referenced by the call to ``@notfound_view_config`` as the ``renderer`` of the ``notfound_view`` view callable in the ``views/notfound.py`` file.
+It inherits the HTML provided by ``layout.jinja2``, replacing the content block with its own content.
+
+.. literalinclude:: myproject/myproject/templates/404.jinja2
+   :language: jinja
+   :linenos:
+
+
 .. index::
    single: tests.py
 
@@ -1015,32 +1068,11 @@ cookiecutter, you can decide to lay your code out any way you see fit.
 For example, the configuration method named
 :meth:`~pyramid.config.Configurator.add_view` requires you to pass a
 :term:`dotted Python name` or a direct object reference as the class or
-function to be used as a view.  By default, the ``starter`` cookiecutter would have
-you add view functions to the ``views.py`` module in your package. However, you
-might be more comfortable creating a ``views`` *directory*, and adding a single
-file for each view.
-
-If your project package name was ``myproject`` and you wanted to arrange all
-your views in a Python subpackage within the ``myproject`` :term:`package`
-named ``views`` instead of within a single ``views.py`` file, you might do the
-following.
-
-- Create a ``views`` directory inside your ``myproject`` package directory (the
-  same directory which holds ``views.py``).
-
-- Create a file within the new ``views`` directory named ``__init__.py``.  (It
-  can be empty.  This just tells Python that the ``views`` directory is a
-  *package*.)
-
-- *Move* the content from the existing ``views.py`` file to a file inside the
-  new ``views`` directory named, say, ``blog.py``.  Because the ``templates``
-  directory remains in the ``myproject`` package, the template :term:`asset
-  specification` values in ``blog.py`` must now be fully qualified with the
-  project's package name (``myproject:templates/blog.pt``).
-
-You can then continue to add view callable functions to the ``blog.py`` module,
-but you can also add other ``.py`` files which contain view callable functions
-to the ``views`` directory.  As long as you use the ``@view_config`` directive
+function to be used as a view.
+By default, the ``starter`` cookiecutter would have you create a ``views`` directory, and add a single file for each view or collection of related views.
+However, you might be more comfortable creating a single ``views.py`` module in your package and add view functions to it.
+
+Whatever structure you prefer, as long as you use the ``@view_config`` directive
 to register views in conjunction with ``config.scan()``, they will be picked up
 automatically when the application is restarted.