11 files changed, 69 insertions, 56 deletions
diff --git a/docs/narr/advanced-features.rst b/docs/narr/advanced-features.rst
index 191996c27..b169aad95 100644
--- a/docs/narr/advanced-features.rst
+++ b/docs/narr/advanced-features.rst
@@ -51,7 +51,7 @@ This approach allows you to develop view code that is simpler, more easily under
 Stop Worrying About Transactions
 --------------------------------
 
-:app:`Pyramid`\ 's :term:`cookiecutter`\ s render projects that include a *transaction management* system.  When you use this system, you can stop worrying about when to commit your changes, :app:`Pyramid` handles it for you. The system will commit at the end of a request or abort if there was an exception.
+:app:`Pyramid`\ 's :term:`cookiecutter` renders projects that include a *transaction management* system.  When you use this system, you can stop worrying about when to commit your changes, :app:`Pyramid` handles it for you. The system will commit at the end of a request or abort if there was an exception.
 
 Why is that a good thing? Imagine a situation where you manually commit a change to your persistence layer. It's very likely that other framework code will run *after* your changes are done. If an error happens in that other code, you can easily wind up with inconsistent data if you're not extremely careful.
 
@@ -327,4 +327,4 @@ Here's an example of using :app:`Pyramid`\ 's :term:`introspector` from within a
 
 .. seealso::
 
-    See also :ref:`using_introspection`.
-\ No newline at end of file
+    See also :ref:`using_introspection`.
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 2b0b90b4a..06594dbb7 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -27,8 +27,8 @@ asset:
   package.
 
 The use of assets is quite common in most web development projects.  For
-example, when you create a :app:`Pyramid` application using one of the
-available :term:`cookiecutter`\ s, as described in :ref:`creating_a_project`, the directory
+example, when you create a :app:`Pyramid` application using the
+:term:`cookiecutter`, as described in :ref:`creating_a_project`, the directory
 representing the application contains a Python :term:`package`. Within that
 Python package, there are directories full of files which are static assets.
 For example, there's a ``static`` directory which contains ``.css``, ``.js``,
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 98e34fea2..f8ca8366b 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -298,8 +298,8 @@ By defining the ``setup`` callable, we will create the module ``myapp.lib.pshell
         # start a transaction which can be used in the shell
         request.tm.begin()
 
-        # if using the alchemy cookiecutter, the dbsession is connected
-        # to the transaction manager above
+        # if using the SQLAlchemy backend from our cookiecutter, the dbsession is
+        # connected to the transaction manager above
         env['tm'] = request.tm
         env['dbsession'] = request.dbsession
         try:
diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst
index abedb25b9..9883713cb 100644
--- a/docs/narr/cookiecutters.rst
+++ b/docs/narr/cookiecutters.rst
@@ -2,16 +2,24 @@
 
 Pyramid cookiecutters
 =====================
+A :term:`cookiecutter` is a command-line utility that creates projects from :ref:`cookiecutters <cookiecutter:readme>` (project templates).
+
+The Pyramid cookiecutter replaced the deprecated Pyramid scaffolds, and should be used going forward.
+
+`pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_
 
 .. versionadded:: 1.8
+    Added cookiecutter support.
 
-A :term:`cookiecutter` is a command-line utility that creates projects from :ref:`cookiecutters <cookiecutter:readme>` (project templates), e.g., creating a Python package project from a Python package project template.
+.. deprecated:: 1.8
+    Scaffolds may be removed in a future version of Pyramid.
 
-Pyramid cookiecutters have replaced the now deprecated Pyramid scaffolds, and should be used going forward. Pyramid cookiecutters released under the Pylons Project include:
+.. versionchanged:: 1.10
+    Merged features from ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` into the single cookiecutter to rule them all, ``pyramid-cookiecutter-starter``.
 
-* `pyramid-cookiecutter-alchemy <https://github.com/Pylons/pyramid-cookiecutter-alchemy>`_
-* `pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_
-* `pyramid-cookiecutter-zodb <https://github.com/Pylons/pyramid-cookiecutter-zodb>`_
+.. deprecated:: 1.10
+    ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` are no longer supported.
+    Use ``pyramid-cookiecutter-starter`` going forward.
 
 .. seealso::
 
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index 1a6804792..ccf871ca8 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -190,7 +190,7 @@ The general pattern for extending an existing application looks something like
 this:
 
 - Create a new Python package.  The easiest way to do this is to create a new
-  :app:`Pyramid` application using a :term:`cookiecutter`.  See
+  :app:`Pyramid` application using our :term:`cookiecutter`.  See
   :ref:`creating_a_project` for more information.
 
 - In the new package, create Python files containing views and other overridden
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 743cb4abb..dbf5dc2eb 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -262,5 +262,4 @@ What Gets Installed
 When you install :app:`Pyramid`, various libraries such as WebOb, PasteDeploy,
 and others are installed.
 
-Additionally, as chronicled in :ref:`project_narr`, :term:`cookiecutter`\ s will be
-used, which make it easy to start a new :app:`Pyramid` project.
+Additionally, as chronicled in :ref:`project_narr`, our :term:`cookiecutter` will be used, which makes it easy to start a new :app:`Pyramid` project.
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 9293386f2..dada4e8bd 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -144,7 +144,7 @@ Develop interactively
 
 When your application has an error, an interactive debugger allows you to poke around from your browser to find out what happened.
 
-To use the :app:`Pyramid` debug toolbar, build your project with a :app:`Pyramid` :term:`cookiecutter`.
+To use the :app:`Pyramid` debug toolbar, build your project with our :term:`cookiecutter`.
 
 .. seealso::
 
diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index ce83cd3ee..7b60beda9 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -9,10 +9,10 @@ to send log messages to loggers that you've configured.
 
 .. warning::
 
-   This chapter assumes you've used a :term:`cookiecutter` to create a project
+   This chapter assumes you've used our :term:`cookiecutter` to create a project
    which contains ``development.ini`` and ``production.ini`` files which help
-   configure logging.  All of the Pyramid cookiecutters provided by the Pylons Project do
-   this.  If you're not using a cookiecutter, or if you've used a third-party
+   configure logging.  The Pyramid cookiecutter provided by the Pylons Project does
+   this.  If you're not using our cookiecutter, or if you've used a third-party
    cookiecutter which does not create these files, the configuration information in
    this chapter may not be applicable.
 
@@ -26,11 +26,11 @@ to send log messages to loggers that you've configured.
 Logging Configuration
 ---------------------
 
-A :app:`Pyramid` project created from a :term:`cookiecutter` is configured to allow
+A :app:`Pyramid` project created from our :term:`cookiecutter` is configured to allow
 you to send messages to :mod:`Python standard library logging package
 <logging>` loggers from within your application.  In particular, the
 :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created
-when you use a cookiecutter include a basic configuration for the Python
+when you use our cookiecutter include a basic configuration for the Python
 :mod:`logging` package.
 
 PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser
@@ -47,7 +47,7 @@ cookiecutter-generated ``.ini`` files do). ``setup_logging`` reads the logging
 configuration from the ini file upon which ``pserve`` was invoked.
 
 Default logging configuration is provided in both the default
-``development.ini`` and the ``production.ini`` files.  If you use ``pyramid-cookiecutter-starter`` to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration
+``development.ini`` and the ``production.ini`` files.  If you use our cookiecutter to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration
 in the ``development.ini`` file is as follows:
 
 .. literalinclude:: myproject/development.ini
@@ -75,7 +75,7 @@ that ask for a logger (via ``logging.getLogger``) that has a name which begins
 with anything except your project's package name (e.g., ``myproject``). The logger
 with the same name as your package name is reserved for your own usage in your
 :app:`Pyramid` application.  Its existence means that you can log to a known
-logging location from any :app:`Pyramid` application generated via a cookiecutter.
+logging location from any :app:`Pyramid` application generated via our cookiecutter.
 
 :app:`Pyramid` and many other libraries (such as Beaker, SQLAlchemy, Paste) log
 a number of messages to the root logger for debugging purposes. Switching the
@@ -88,9 +88,10 @@ root logger level to ``DEBUG`` reveals them:
     level = DEBUG
     handlers = console
 
-Some cookiecutters configure additional loggers for additional subsystems they use
-(such as SQLALchemy).  Take a look at the ``production.ini`` and
-``development.ini`` files rendered when you create a project from a cookiecutter.
+Some configurations of the :app:`Pyramid` cookiecutter configure additional loggers for
+additional subsystems they use (such as SQLAlchemy).  Take a look at the
+``production.ini`` and ``development.ini`` files rendered when you create a
+project from our cookiecutter.
 
 Sending Logging Messages
 ------------------------
diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst
index c02036f69..8a0d505b3 100644
--- a/docs/narr/paste.rst
+++ b/docs/narr/paste.rst
@@ -14,7 +14,7 @@ runner ``pserve``, as well as other commands such as ``pviews``, ``pshell``,
 PasteDeploy is not a particularly integral part of Pyramid.  It's possible to
 create a Pyramid application which does not use PasteDeploy at all.  We show a
 Pyramid application that doesn't use PasteDeploy in :ref:`firstapp_chapter`.
-However, all Pyramid cookiecutters render PasteDeploy configuration files, to
+However, the Pyramid cookiecutter renders PasteDeploy configuration files, to
 provide new developers with a standardized way of setting deployment values,
 and to provide new users with a standardized way of starting, stopping, and
 debugging an application.
@@ -75,7 +75,7 @@ In English, this entry point can thus be referred to as a "PasteDeploy
 application factory in the ``myproject`` project which has the entry point
 named ``main`` where the entry point refers to a ``main`` function in the
 ``mypackage`` module".  Indeed, if you open up the ``__init__.py`` module
-generated within any cookiecutter-generated package, you'll see a ``main``
+generated within the cookiecutter-generated package, you'll see a ``main``
 function.  This is the function called by :term:`PasteDeploy` when the
 ``pserve`` command is invoked against our application.  It accepts a global
 configuration object and *returns* an instance of our application.
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 5efc07e09..84fd8e31f 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -5,21 +5,21 @@ Creating a :app:`Pyramid` Project
 
 As we saw in :ref:`firstapp_chapter`, it's possible to create a :app:`Pyramid`
 application completely manually.  However, it's usually more convenient to use
-a :term:`cookiecutter` to generate a basic :app:`Pyramid` :term:`project`.
+our :term:`cookiecutter` to generate a basic :app:`Pyramid` :term:`project`.
 
 A project is a directory that contains at least one Python :term:`package`.
-You'll use a cookiecutter to create a project, and you'll create your application
-logic within a package that lives inside the project.  Even if your application
-is extremely simple, it is useful to place code that drives the application
-within a package, because (1) a package is more easily extended with new code,
-and (2) an application that lives inside a package can also be distributed more
-easily than one which does not live within a package.
+You'll use the :app:`Pyramid` cookiecutter to create a project, and you'll
+create your application logic within a package that lives inside the project.
+Even if your application is extremely simple, it is useful to place code that
+drives the application within a package, because (1) a package is more easily
+extended with new code, and (2) an application that lives inside a package can
+also be distributed more easily than one which does not live within a package.
 
-The Pylons Project provides several :app:`Pyramid` cookiecutters that you can use to generate a
-project.  Each cookiecutter makes different configuration assumptions about what
-type of application you're trying to construct.
+The Pylons Project provides a :app:`Pyramid` cookiecutter that you can use to
+generate a project.  Our cookiecutter allows several configuration options
+to generate the type of application you're trying to construct.
 
-These cookiecutters are rendered using the ``cookiecutter`` command that you may install.
+This cookiecutter is rendered using the ``cookiecutter`` command that you may install.
 
 .. seealso::
 
@@ -29,36 +29,34 @@ These cookiecutters are rendered using the ``cookiecutter`` command that you may
 .. index::
    single: cookiecutters
    single: pyramid-cookiecutter-starter
-   single: pyramid-cookiecutter-zodb
-   single: pyramid-cookiecutter-alchemy
 
 .. _additional_cookiecutters:
 
 :app:`Pyramid` cookiecutters
 ----------------------------
 
-Pyramid cookiecutters released under the Pylons Project differ from each other on a number of axes:
+The Pyramid cookiecutter released under the Pylons Project offers the following configuration options:
 
-- the persistence mechanism they offer (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`)
+- templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`)
 
-- the mechanism they use to map URLs to code (:term:`URL dispatch` or :term:`traversal`)
+- the persistence mechanism (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`)
 
-- templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`)
+- the mechanism of mapping URLs to code (:term:`URL dispatch` or :term:`traversal`)
 
 * `pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_
-* `pyramid-cookiecutter-alchemy <https://github.com/Pylons/pyramid-cookiecutter-alchemy>`_
-* `pyramid-cookiecutter-zodb <https://github.com/Pylons/pyramid-cookiecutter-zodb>`_
 
-These cookiecutters include:
+All configuration options offer a choice of templating language.
+
+The configuration of mapping URLs to code (routing) depends on the backend option selected, with additional variations as follows.
 
-``pyramid-cookiecutter-starter``
-    :term:`URL dispatch` for routing and either :term:`Jinja2`, :term:`Chameleon`, or :term:`Mako` for templating
+``none``
+    :term:`URL dispatch` for routing
 
-``pyramid-cookiecutter-alchemy``
-    SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, :term:`URL dispatch` for routing, and :term:`Jinja2` for templating.
+``sqlalchemy``
+    SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, :term:`URL dispatch` for routing, and :term:`Alembic` for database migrations
 
-``pyramid-cookiecutter-zodb``
-    :term:`ZODB` for persistent storage, :term:`traversal` for routing, and :term:`Chameleon` for templating
+``zodb``
+    :term:`ZODB` for persistent storage and :term:`traversal` for routing
 
 
 .. index::
@@ -77,7 +75,7 @@ In :ref:`installing_chapter`, you created a virtual Python environment via the
 
 We assume that you :ref:`previously installed cookiecutter <cookiecutters>`, following its installation instructions.
 
-We'll choose ``pyramid-cookiecutter-starter`` to start the project.  When we invoke ``cookiecutter``, it will create a directory that represents our project.
+When we invoke ``cookiecutter``, it will create a directory that represents our project.
 
 We assume our current working directory is the value of ``VENV``.
 
@@ -100,6 +98,11 @@ If prompted for the first item, accept the default ``yes`` by hitting return.
     2 - chameleon
     3 - mako
     Choose from 1, 2, 3 [1]: 1
+    Select backend:
+    1 - none
+    2 - sqlalchemy
+    3 - zodb
+    Choose from 1, 2, 3 [1]: 1
 
 We then run through the following commands.
 
@@ -818,6 +821,8 @@ The ``myproject`` :term:`package` lives inside the ``myproject``
 
 #. A ``tests.py`` module, which contains unit test code for the application.
 
+#. A ``routes.py`` module, which contains routing 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.
@@ -853,7 +858,7 @@ also informs Python that the directory which contains it is a *package*.
 
    Within this function, application configuration is performed.
 
-   Line 7 creates an instance of a :term:`Configurator`.
+   Line 7 opens a context manager with an instance of a :term:`Configurator`.
 
    Line 8 adds support for Jinja2 templating bindings, allowing us to
    specify renderers with the ``.jinja2`` extension.
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index e78c524ff..89dc6e0f1 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -345,7 +345,7 @@ against your ``mypackage`` package during application initialization.
 
 .. note::
    This is only an example.  In particular, it is not necessary to cause
-   ``DBSession.remove`` to be called in an application generated from a
+   ``DBSession.remove`` to be called in an application generated from the
    :app:`Pyramid` cookiecutter, because these all use the ``pyramid_tm`` package.
    The cleanup done by ``DBSession.remove`` is unnecessary when ``pyramid_tm``
    :term:`middleware` is configured into the application.