Merge pull request #3379 from stevepiercy/docs-quick-tutorial-update

Docs quick tutorial update

37 files changed, 402 insertions, 257 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 8f94eeaca..aef0263a8 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -43,19 +43,17 @@ Glossary
      <http://svn.repoze.org>`_.  Pyramid was originally known as
      :mod:`repoze.bfg`.
 
-   setuptools
-     `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_
+   Setuptools
+     `Setuptools <https://setuptools.readthedocs.io/en/latest/>`_
      builds on Python's ``distutils`` to provide easier building,
-     distribution, and installation of libraries and applications.  As of
-     this writing, setuptools runs under Python 2, but not under Python 3.
-     You can use :term:`distribute` under Python 3 instead.
+     distribution, and installation of libraries and applications.
 
    distribute
-     `Distribute <https://pypi.org/project/distribute/>`_ is a fork of
-     :term:`setuptools` which runs on both Python 2 and Python 3.
+     `Distribute <https://pypi.org/project/distribute/>`_ is a fork of :term:`Setuptools` which runs on both Python 2 and Python 3.
+     It is now in legacy state because :term:`Setuptools` now runs on both Python 2 and 3.
 
    pkg_resources
-     A module which ships with :term:`setuptools` and :term:`distribute` that
+     A module which ships with :term:`Setuptools` and :term:`distribute` that
      provides an API for addressing "asset files" within a Python
      :term:`package`.  Asset files are static files, template files, etc;
      basically anything non-Python-source that lives in a Python package can
@@ -103,7 +101,7 @@ Glossary
      ``easy_install``.
 
    entry point
-     A :term:`setuptools` indirection, defined within a setuptools
+     A :term:`Setuptools` indirection, defined within a Setuptools
      :term:`distribution` setup.py.  It is usually a name which refers
      to a function somewhere in a package which is held by the
      distribution.
@@ -111,7 +109,7 @@ Glossary
    dotted Python name
      A reference to a Python object by name using a string, in the form
      ``path.to.modulename:attributename``.  Often used in Pyramid and
-     setuptools configurations.  A variant is used in dotted names within
+     Setuptools configurations.  A variant is used in dotted names within
      configurator method arguments that name objects (such as the "add_view"
      method's "view" and "context" attributes): the colon (``:``) is not
      used; in its place is a dot.
@@ -977,7 +975,7 @@ Glossary
    distutils
      The standard system for packaging and distributing Python packages.  See
      https://docs.python.org/2/distutils/index.html for more information.
-     :term:`setuptools` is actually an *extension* of the Distutils.
+     :term:`Setuptools` is actually an *extension* of the Distutils.
 
    exception response
      A :term:`response` that is generated as the result of a raised exception
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 06594dbb7..d1d64f0c3 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -735,7 +735,7 @@ feature, a :term:`Configurator` API exists named
 - A directory of static files served up by an instance of the
   ``pyramid.static.static_view`` helper class.
 
-- Any other asset (or set of assets) addressed by code that uses the setuptools
+- Any other asset (or set of assets) addressed by code that uses the Setuptools
   :term:`pkg_resources` API.
 
 .. index::
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index f8ca8366b..7af6bba43 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -896,7 +896,7 @@ See :ref:`logging_chapter` for more information on logging within
 Making Your Script into a Console Script
 ----------------------------------------
 
-A "console script" is :term:`setuptools` terminology for a script that gets
+A "console script" is :term:`Setuptools` terminology for a script that gets
 installed into the ``bin`` directory of a Python :term:`virtual environment`
 (or "base" Python environment) when a :term:`distribution` which houses that
 script is installed. Because it's installed into the ``bin`` directory of a
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index dbf5dc2eb..248b432d3 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -117,7 +117,7 @@ following options:
    ``py`` that allows users to run any installed version of Python.
 
 .. warning:: After you install Python on Windows, you might need to add the
-   directory where Python and other programs—such as pip, setuptools, and
+   directory where Python and other programs—such as pip, :term:`Setuptools`, and
    cookiecutter—are installed to your environment's ``Path``. This will make it
    possible to invoke them from a command prompt.
 
diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst
index 8a0d505b3..ac8f7fdca 100644
--- a/docs/narr/paste.rst
+++ b/docs/narr/paste.rst
@@ -48,7 +48,7 @@ The line in ``[app:main]`` above that says ``use = egg:myproject`` is actually
 shorthand for a longer spelling: ``use = egg:myproject#main``.  The ``#main``
 part is omitted for brevity, as ``#main`` is a default defined by PasteDeploy.
 ``egg:myproject#main`` is a string which has meaning to PasteDeploy.  It points
-at a :term:`setuptools` :term:`entry point` named ``main`` defined in the
+at a :term:`Setuptools` :term:`entry point` named ``main`` defined in the
 ``myproject`` project.
 
 Take a look at the generated ``setup.py`` file for this project.
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 84fd8e31f..725263407 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -587,7 +587,7 @@ describe, run, and test your application.
 #. ``pytest.ini`` is a configuration file for running tests.
 
 #. ``setup.py`` is the file you'll use to test and distribute your application.
-   It is a standard :term:`setuptools` ``setup.py`` file.
+   It is a standard :term:`Setuptools` ``setup.py`` file.
 
 .. index::
    single: PasteDeploy
@@ -711,7 +711,7 @@ Without the presence of a ``MANIFEST.in`` file or without checking your source
 code into a version control repository, ``setup.py sdist`` places only *Python
 source files* (files ending with a ``.py`` extension) into tarballs generated
 by ``python setup.py sdist``.  This means, for example, if your project was not
-checked into a setuptools-compatible source control system, and your project
+checked into a Setuptools-compatible source control system, and your project
 directory didn't contain a ``MANIFEST.in`` file that told the ``sdist``
 machinery to include ``*.pt`` files, the ``myproject/templates/mytemplate.pt``
 file would not be included in the generated tarball.
@@ -720,20 +720,20 @@ Projects generated by Pyramid cookiecutters include a default ``MANIFEST.in`` fi
 The ``MANIFEST.in`` file contains declarations which tell it to include files
 like ``*.pt``, ``*.css`` and ``*.js`` in the generated tarball. If you include
 files with extensions other than the files named in the project's
-``MANIFEST.in`` and you don't make use of a setuptools-compatible version
+``MANIFEST.in`` and you don't make use of a Setuptools-compatible version
 control system, you'll need to edit the ``MANIFEST.in`` file and include the
 statements necessary to include your new files.  See
 https://docs.python.org/2/distutils/sourcedist.html#principle for more
 information about how to do this.
 
-You can also delete ``MANIFEST.in`` from your project and rely on a setuptools
+You can also delete ``MANIFEST.in`` from your project and rely on a :term:`Setuptools`
 feature which simply causes all files checked into a version control system to
 be put into the generated tarball.  To allow this to happen, check all the
 files that you'd like to be distributed along with your application's Python
 files into Subversion.  After you do this, when you rerun ``setup.py sdist``,
 all files checked into the version control system will be included in the
 tarball.  If you don't use Subversion, and instead use a different version
-control system, you may need to install a setuptools add-on such as
+control system, you may need to install a :term:`Setuptools` add-on such as
 ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly.
 
 .. index::
@@ -742,7 +742,7 @@ control system, you may need to install a setuptools add-on such as
 ``setup.py``
 ~~~~~~~~~~~~
 
-The ``setup.py`` file is a :term:`setuptools` setup file.  It is meant to be
+The ``setup.py`` file is a :term:`Setuptools` setup file.  It is meant to be
 used to define requirements for installing dependencies for your package and
 testing, as well as distributing your application.
 
@@ -760,13 +760,13 @@ Our generated ``setup.py`` looks like this:
    :language: python
    :linenos:
 
-The ``setup.py`` file calls the setuptools ``setup`` function, which does
+The ``setup.py`` file calls the :term:`Setuptools` ``setup`` function, which does
 various things depending on the arguments passed to ``pip`` on the command
 line.
 
 Within the arguments to this function call, information about your application
 is kept.  While it's beyond the scope of this documentation to explain
-everything about setuptools setup files, we'll provide a whirlwind tour of what
+everything about :term:`Setuptools` setup files, we'll provide a whirlwind tour of what
 exists in this file in this section.
 
 Your application's name can be any string; it is specified in the ``name``
diff --git a/docs/narr/scaffolding.rst b/docs/narr/scaffolding.rst
index 083d831cc..47eb2c658 100644
--- a/docs/narr/scaffolding.rst
+++ b/docs/narr/scaffolding.rst
@@ -21,11 +21,11 @@ Basics
 
 A scaffold template is just a bunch of source files and directories on disk. A
 small definition class points at this directory.  It is in turn pointed at by a
-:term:`setuptools` "entry point" which registers the scaffold so it can be
+:term:`Setuptools` "entry point" which registers the scaffold so it can be
 found by the ``pcreate`` command.
 
 To create a scaffold template, create a Python :term:`distribution` to house
-the scaffold which includes a ``setup.py`` that relies on the ``setuptools``
+the scaffold which includes a ``setup.py`` that relies on the :term:`Setuptools`
 package.  See `Packaging and Distributing Projects
 <https://packaging.python.org/tutorials/packaging-projects/>`_ for more information
 about how to do this.  For example, we'll pretend the distribution you create
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index 05c2ed7f6..1e2c71cf0 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -19,7 +19,7 @@ Once you have a standard Python environment setup, getting started with Pyramid
 is a breeze. Unfortunately "standard" is not so simple in Python. For this
 Quick Tour, it means `Python <https://www.python.org/downloads/>`_, :mod:`python:venv` (or `virtualenv for
 Python 2.7 <https://virtualenv.pypa.io/en/stable/>`_),
-`pip <https://pypi.org/project/pip/>`_, and `setuptools
+`pip <https://pypi.org/project/pip/>`_, and `Setuptools
 <https://pypi.org/project/setuptools/>`_.
 
 To save a little bit of typing and to be certain that we use the modules,
diff --git a/docs/quick_tutorial/authentication/setup.py b/docs/quick_tutorial/authentication/setup.py
index a5117af5a..05104b158 100644
--- a/docs/quick_tutorial/authentication/setup.py
+++ b/docs/quick_tutorial/authentication/setup.py
@@ -4,13 +4,20 @@ requires = [
     'bcrypt',
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/authorization/setup.py b/docs/quick_tutorial/authorization/setup.py
index a5117af5a..05104b158 100644
--- a/docs/quick_tutorial/authorization/setup.py
+++ b/docs/quick_tutorial/authorization/setup.py
@@ -4,13 +4,20 @@ requires = [
     'bcrypt',
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/databases.rst b/docs/quick_tutorial/databases.rst
index dcf411d23..5ba23e937 100644
--- a/docs/quick_tutorial/databases.rst
+++ b/docs/quick_tutorial/databases.rst
@@ -41,108 +41,100 @@ Objectives
 Steps
 =====
 
-#. We are going to use the forms step as our starting point:
+#.  We are going to use the forms step as our starting point:
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       cd ..; cp -r forms databases; cd databases
+        cd ..; cp -r forms databases; cd databases
 
-#. We need to add some dependencies in ``databases/setup.py`` as well as an
-   "entry point" for the command-line script:
+#.  We need to add some dependencies in ``databases/setup.py`` as well as an :term:`entry point` for the command-line script:
 
-   .. literalinclude:: databases/setup.py
-    :linenos:
+    .. literalinclude:: databases/setup.py
+        :linenos:
+        :emphasize-lines: 8-9, 11, 25-26
 
-   .. note::
+    .. note:: We aren't yet doing ``$VENV/bin/pip install -e .`` because we need to write a script and update configuration first.
 
-     We aren't yet doing ``$VENV/bin/pip install -e .`` as we will change it
-     later.
+#.  Our configuration file at ``databases/development.ini`` wires together some new pieces:
 
-#. Our configuration file at ``databases/development.ini`` wires together some
-   new pieces:
+    .. literalinclude:: databases/development.ini
+        :language: ini
 
-   .. literalinclude:: databases/development.ini
-       :language: ini
+#.  This engine configuration now needs to be read into the application through changes in ``databases/tutorial/__init__.py``:
 
-#. This engine configuration now needs to be read into the application through
-   changes in ``databases/tutorial/__init__.py``:
+    .. literalinclude:: databases/tutorial/__init__.py
+        :linenos:
 
-   .. literalinclude:: databases/tutorial/__init__.py
-       :linenos:
+#.  Make a command-line script at ``databases/tutorial/initialize_db.py`` to initialize the database:
 
-#. Make a command-line script at ``databases/tutorial/initialize_db.py`` to
-   initialize the database:
+    .. literalinclude:: databases/tutorial/initialize_db.py
+        :linenos:
 
-   .. literalinclude:: databases/tutorial/initialize_db.py
-       :linenos:
+#.  Now that we've got all the pieces ready, and because we changed ``setup.py``, we now install all the goodies:
 
-#. Since ``setup.py`` changed, we now run it:
+    .. code-block:: bash
 
-   .. code-block:: bash
+        $VENV/bin/pip install -e .
 
-       $VENV/bin/pip install -e .
+#.  The script references some models in ``databases/tutorial/models.py``:
 
-#. The script references some models in ``databases/tutorial/models.py``:
+    .. literalinclude:: databases/tutorial/models.py
+        :linenos:
 
-   .. literalinclude:: databases/tutorial/models.py
-       :linenos:
+#.  Let's run this console script, thus producing our database and table:
 
-#. Let's run this console script, thus producing our database and table:
+    .. code-block:: bash
 
-   .. code-block:: bash
+        $VENV/bin/initialize_tutorial_db development.ini
 
-       $VENV/bin/initialize_tutorial_db development.ini
-
-       2016-04-16 13:01:33,055 INFO  [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
-       2016-04-16 13:01:33,055 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
-       2016-04-16 13:01:33,056 INFO  [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
-       2016-04-16 13:01:33,056 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
-       2016-04-16 13:01:33,057 INFO  [sqlalchemy.engine.base.Engine][MainThread] PRAGMA table_info("wikipages")
-       2016-04-16 13:01:33,057 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
-       2016-04-16 13:01:33,058 INFO  [sqlalchemy.engine.base.Engine][MainThread]
-       CREATE TABLE wikipages (
+        2016-04-16 13:01:33,055 INFO  [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
+        2016-04-16 13:01:33,055 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
+        2016-04-16 13:01:33,056 INFO  [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
+        2016-04-16 13:01:33,056 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
+        2016-04-16 13:01:33,057 INFO  [sqlalchemy.engine.base.Engine][MainThread] PRAGMA table_info("wikipages")
+        2016-04-16 13:01:33,057 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
+        2016-04-16 13:01:33,058 INFO  [sqlalchemy.engine.base.Engine][MainThread]
+        CREATE TABLE wikipages (
                uid INTEGER NOT NULL,
                title TEXT,
                body TEXT,
                PRIMARY KEY (uid),
                UNIQUE (title)
-       )
+        )
 
 
-       2016-04-16 13:01:33,058 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
-       2016-04-16 13:01:33,059 INFO  [sqlalchemy.engine.base.Engine][MainThread] COMMIT
-       2016-04-16 13:01:33,062 INFO  [sqlalchemy.engine.base.Engine][MainThread] BEGIN (implicit)
-       2016-04-16 13:01:33,062 INFO  [sqlalchemy.engine.base.Engine][MainThread] INSERT INTO wikipages (title, body) VALUES (?, ?)
-       2016-04-16 13:01:33,063 INFO  [sqlalchemy.engine.base.Engine][MainThread] ('Root', '<p>Root</p>')
-       2016-04-16 13:01:33,063 INFO  [sqlalchemy.engine.base.Engine][MainThread] COMMIT
+        2016-04-16 13:01:33,058 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
+        2016-04-16 13:01:33,059 INFO  [sqlalchemy.engine.base.Engine][MainThread] COMMIT
+        2016-04-16 13:01:33,062 INFO  [sqlalchemy.engine.base.Engine][MainThread] BEGIN (implicit)
+        2016-04-16 13:01:33,062 INFO  [sqlalchemy.engine.base.Engine][MainThread] INSERT INTO wikipages (title, body) VALUES (?, ?)
+        2016-04-16 13:01:33,063 INFO  [sqlalchemy.engine.base.Engine][MainThread] ('Root', '<p>Root</p>')
+        2016-04-16 13:01:33,063 INFO  [sqlalchemy.engine.base.Engine][MainThread] COMMIT
 
-#. With our data now driven by SQLAlchemy queries, we need to update our
-   ``databases/tutorial/views.py``:
+#.  With our data now driven by SQLAlchemy queries, we need to update our ``databases/tutorial/views.py``:
 
-   .. literalinclude:: databases/tutorial/views.py
-       :linenos:
+    .. literalinclude:: databases/tutorial/views.py
+        :linenos:
 
-#. Our tests in ``databases/tutorial/tests.py`` changed to include SQLAlchemy
-   bootstrapping:
+#.  Our tests in ``databases/tutorial/tests.py`` changed to include SQLAlchemy bootstrapping:
 
-   .. literalinclude:: databases/tutorial/tests.py
-       :linenos:
+    .. literalinclude:: databases/tutorial/tests.py
+        :linenos:
 
-#. Run the tests in your package using ``pytest``:
+#.  Run the tests in your package using ``pytest``:
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       $VENV/bin/pytest tutorial/tests.py -q
-       ..
-       2 passed in 1.41 seconds
+        $VENV/bin/pytest tutorial/tests.py -q
+        ..
+        2 passed in 1.41 seconds
 
-#. Run your Pyramid application with:
+#.  Run your Pyramid application with:
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       $VENV/bin/pserve development.ini --reload
+        $VENV/bin/pserve development.ini --reload
 
-#. Open http://localhost:6543/ in a browser.
+#.  Open http://localhost:6543/ in a browser.
 
 
 Analysis
diff --git a/docs/quick_tutorial/databases/setup.py b/docs/quick_tutorial/databases/setup.py
index 13d1d6637..29dede2af 100644
--- a/docs/quick_tutorial/databases/setup.py
+++ b/docs/quick_tutorial/databases/setup.py
@@ -4,6 +4,7 @@ requires = [
     'deform',
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'pyramid_tm',
     'sqlalchemy',
     'waitress',
@@ -12,10 +13,16 @@ requires = [
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
       initialize_tutorial_db = tutorial.initialize_db:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst
index b49dd1f97..a13d153d8 100644
--- a/docs/quick_tutorial/debugtoolbar.rst
+++ b/docs/quick_tutorial/debugtoolbar.rst
@@ -32,30 +32,39 @@ Objectives
 Steps
 =====
 
-#. First we copy the results of the previous step, as well as install the
-   ``pyramid_debugtoolbar`` package:
+#.  First we copy the results of the previous step.
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       cd ..; cp -r ini debugtoolbar; cd debugtoolbar
-       $VENV/bin/pip install -e .
-       $VENV/bin/pip install pyramid_debugtoolbar
+        cd ..; cp -r ini debugtoolbar; cd debugtoolbar
 
-#. Our ``debugtoolbar/development.ini`` gets a configuration entry for
-   ``pyramid.includes``:
+#.  Add ``pyramid_debugtoolbar`` to our project's dependencies in ``setup.py``:
 
-   .. literalinclude:: debugtoolbar/development.ini
-       :language: ini
-       :linenos:
+    .. literalinclude:: debugtoolbar/setup.py
+        :language: python
+        :linenos:
+        :emphasize-lines: 5
 
-#. Run the WSGI application with:
+#.  Install our project and its newly added dependency.
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       $VENV/bin/pserve development.ini --reload
+        $VENV/bin/pip install -e .
 
-#. Open http://localhost:6543/ in your browser. See the handy
-   toolbar on the right.
+#.  Our ``debugtoolbar/development.ini`` gets a configuration entry for ``pyramid.includes``:
+
+    .. literalinclude:: debugtoolbar/development.ini
+        :language: ini
+        :linenos:
+
+#.  Run the WSGI application with:
+
+    .. code-block:: bash
+
+        $VENV/bin/pserve development.ini --reload
+
+#.  Open http://localhost:6543/ in your browser.
+    See the handy toolbar on the right.
 
 
 Analysis
@@ -93,24 +102,24 @@ temporarily.
 Extra credit
 ============
 
-#. Why don't we add ``pyramid_debugtoolbar`` to the list of
-   ``install_requires`` dependencies in ``debugtoolbar/setup.py``?
+#.  We added ``pyramid_debugtoolbar`` to the list of ``install_requires`` dependencies in ``debugtoolbar/setup.py`` because this tutorial is for development and educational purposes only.
+    In what cases would you *not* want to add ``pyramid_debugtoolbar`` to your dependencies?
 
-#. Introduce a bug into your application. Change:
+#.  Introduce a bug into your application. Change:
 
-   .. code-block:: python
+    .. code-block:: python
 
-       def hello_world(request):
-           return Response('<body><h1>Hello World!</h1></body>')
+        def hello_world(request):
+            return Response('<body><h1>Hello World!</h1></body>')
 
-   to:
+    to:
 
-   .. code-block:: python
+    .. code-block:: python
 
-       def hello_world(request):
-           return xResponse('<body><h1>Hello World!</h1></body>')
+        def hello_world(request):
+            return xResponse('<body><h1>Hello World!</h1></body>')
 
-   Save, and visit http://localhost:6543/ again. Notice the nice traceback
-   display. On the lowest line, click the "screen" icon to the right, and try
-   typing the variable names ``request`` and ``Response``. What else can you
-   discover?
+    Save, and visit http://localhost:6543/ again.
+    Notice the nice traceback display.
+    On the lowest line, click the "screen" icon to the right, and try typing the variable names ``request`` and ``Response``.
+    What else can you discover?
diff --git a/docs/quick_tutorial/debugtoolbar/setup.py b/docs/quick_tutorial/debugtoolbar/setup.py
index a93cf6a73..a947e20d8 100644
--- a/docs/quick_tutorial/debugtoolbar/setup.py
+++ b/docs/quick_tutorial/debugtoolbar/setup.py
@@ -2,6 +2,7 @@ from setuptools import setup
 
 requires = [
     'pyramid',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
@@ -11,4 +12,4 @@ setup(name='tutorial',
       [paste.app_factory]
       main = tutorial:main
       """,
-)
\ No newline at end of file
+      )
diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst
index be0cb64ac..7d759b72d 100644
--- a/docs/quick_tutorial/forms.rst
+++ b/docs/quick_tutorial/forms.rst
@@ -31,77 +31,72 @@ Objectives
 Steps
 =====
 
-#. First we copy the results of the ``view_classes`` step:
+#.  First we copy the results of the ``view_classes`` step:
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       cd ..; cp -r view_classes forms; cd forms
+        cd ..; cp -r view_classes forms; cd forms
 
-#. Let's edit ``forms/setup.py`` to declare a dependency on Deform (which then
-   pulls in Colander as a dependency:
+#.  Let's edit ``forms/setup.py`` to declare a dependency on Deform, which in turn pulls in Colander as a dependency:
 
-   .. literalinclude:: forms/setup.py
-       :emphasize-lines: 4
-       :linenos:
+    .. literalinclude:: forms/setup.py
+        :emphasize-lines: 4
+        :linenos:
 
-#. We can now install our project in development mode:
+#.  We can now install our project in development mode:
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       $VENV/bin/pip install -e .
+        $VENV/bin/pip install -e .
 
-#. Register a static view in ``forms/tutorial/__init__.py`` for Deform's CSS,
-   JavaScript, etc., as well as our demo wiki page's views:
+#.  Register a static view in ``forms/tutorial/__init__.py`` for Deform's CSS, JavaScript, etc., as well as our demo wiki page's views:
 
-   .. literalinclude:: forms/tutorial/__init__.py
-       :linenos:
+    .. literalinclude:: forms/tutorial/__init__.py
+        :linenos:
 
-#. Implement the new views, as well as the form schemas and some dummy data, in
-   ``forms/tutorial/views.py``:
+#.  Implement the new views, as well as the form schemas and some dummy data, in ``forms/tutorial/views.py``:
 
-   .. literalinclude:: forms/tutorial/views.py
-       :linenos:
+    .. literalinclude:: forms/tutorial/views.py
+        :linenos:
 
-#. A template for the top of the "wiki" in ``forms/tutorial/wiki_view.pt``:
+#.  A template for the top of the "wiki" in ``forms/tutorial/wiki_view.pt``:
 
-   .. literalinclude:: forms/tutorial/wiki_view.pt
-       :language: html
-       :linenos:
+    .. literalinclude:: forms/tutorial/wiki_view.pt
+        :language: html
+        :linenos:
 
-#. Another template for adding/editing in
-   ``forms/tutorial/wikipage_addedit.pt``:
+#.  Another template for adding/editing in ``forms/tutorial/wikipage_addedit.pt``:
 
-   .. literalinclude:: forms/tutorial/wikipage_addedit.pt
-       :language: html
-       :linenos:
+    .. literalinclude:: forms/tutorial/wikipage_addedit.pt
+        :language: html
+        :linenos:
 
-#. Add a template at ``forms/tutorial/wikipage_view.pt`` for viewing a wiki
-   page:
+#.  Add a template at ``forms/tutorial/wikipage_view.pt`` for viewing a wiki page:
 
-   .. literalinclude:: forms/tutorial/wikipage_view.pt
-       :language: html
-       :linenos:
+    .. literalinclude:: forms/tutorial/wikipage_view.pt
+        :language: html
+        :linenos:
 
-#. Our tests in ``forms/tutorial/tests.py`` don't run, so let's modify them:
+#.  Our tests in ``forms/tutorial/tests.py`` don't run, so let's modify them:
 
-   .. literalinclude:: forms/tutorial/tests.py
-       :linenos:
+    .. literalinclude:: forms/tutorial/tests.py
+        :linenos:
 
-#. Run the tests:
+#.  Run the tests:
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       $VENV/bin/pytest tutorial/tests.py -q
-       ..
-       6 passed in 0.81 seconds
+        $VENV/bin/pytest tutorial/tests.py -q
+        ..
+        6 passed in 0.81 seconds
 
-#. Run your Pyramid application with:
+#.  Run your Pyramid application with:
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       $VENV/bin/pserve development.ini --reload
+        $VENV/bin/pserve development.ini --reload
 
-#. Open http://localhost:6543/ in a browser.
+#.  Open http://localhost:6543/ in a browser.
 
 
 Analysis
diff --git a/docs/quick_tutorial/forms/setup.py b/docs/quick_tutorial/forms/setup.py
index 968889e74..e911d5bb8 100644
--- a/docs/quick_tutorial/forms/setup.py
+++ b/docs/quick_tutorial/forms/setup.py
@@ -4,13 +4,20 @@ requires = [
     'deform',
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/functional_testing.rst b/docs/quick_tutorial/functional_testing.rst
index 7c4dcee26..d3ada3793 100644
--- a/docs/quick_tutorial/functional_testing.rst
+++ b/docs/quick_tutorial/functional_testing.rst
@@ -31,31 +31,40 @@ Objectives
 Steps
 =====
 
-#. First we copy the results of the previous step, as well as install the
-   ``webtest`` package:
+#.  First we copy the results of the previous step.
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       cd ..; cp -r unit_testing functional_testing; cd functional_testing
-       $VENV/bin/pip install -e .
-       $VENV/bin/pip install webtest
+        cd ..; cp -r unit_testing functional_testing; cd functional_testing
 
-#. Let's extend ``functional_testing/tutorial/tests.py`` to include a
-   functional test:
+#.  Add ``webtest`` to our project's dependencies in ``setup.py`` as a :term:`Setuptools` "extra":
 
-   .. literalinclude:: functional_testing/tutorial/tests.py
-       :linenos:
+    .. literalinclude:: functional_testing/setup.py
+        :language: python
+        :linenos:
+        :emphasize-lines: 14
 
-   Be sure this file is not executable, or ``pytest`` may not include your
-   tests.
+#.  Install our project and its newly added dependency.
+    Note that we use the extra specifier ``[test]`` to install testing requirements.
+
+    .. code-block:: bash
+
+        $VENV/bin/pip install -e .[test]
+
+#.  Let's extend ``functional_testing/tutorial/tests.py`` to include a functional test:
+
+    .. literalinclude:: functional_testing/tutorial/tests.py
+        :linenos:
+
+    Be sure this file is not executable, or ``pytest`` may not include your tests.
    
-#. Now run the tests:
+#.  Now run the tests:
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       $VENV/bin/pytest tutorial/tests.py -q
-       ..
-       2 passed in 0.25 seconds
+        $VENV/bin/pytest tutorial/tests.py -q
+        ..
+        2 passed in 0.25 seconds
 
 
 Analysis
diff --git a/docs/quick_tutorial/functional_testing/setup.py b/docs/quick_tutorial/functional_testing/setup.py
index a93cf6a73..c0d3dee8f 100644
--- a/docs/quick_tutorial/functional_testing/setup.py
+++ b/docs/quick_tutorial/functional_testing/setup.py
@@ -2,13 +2,20 @@ from setuptools import setup
 
 requires = [
     'pyramid',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
\ No newline at end of file
+      )
diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst
index ce92914fe..90f66009c 100644
--- a/docs/quick_tutorial/ini.rst
+++ b/docs/quick_tutorial/ini.rst
@@ -11,19 +11,16 @@ simpler, better application running.
 Background
 ==========
 
-Pyramid has a first-class concept of :ref:`configuration <configuration_narr>`
-distinct from code. This approach is optional, but its presence makes it
-distinct from other Python web frameworks. It taps into Python's ``setuptools``
-library, which establishes conventions for installing and providing "entry
-points" for Python projects. Pyramid uses an entry point to let a Pyramid
-application know where to find the WSGI app.
+Pyramid has a first-class concept of :ref:`configuration <configuration_narr>` distinct from code.
+This approach is optional, but its presence makes it distinct from other Python web frameworks.
+It taps into Python's :term:`Setuptools` library, which establishes conventions for installing and providing ":term:`entry point`\ s" for Python projects.
+Pyramid uses an :term:`entry point` to let a Pyramid application know where to find the WSGI app.
 
 
 Objectives
 ==========
 
-- Modify our ``setup.py`` to have an entry point telling Pyramid the location
-  of the WSGI app.
+- Modify our ``setup.py`` to have an :term:`entry point` telling Pyramid the location of the WSGI app.
 
 - Create an application driven by an ``.ini`` file.
 
@@ -41,8 +38,7 @@ Steps
 
        cd ..; cp -r package ini; cd ini
 
-#. Our ``ini/setup.py`` needs a setuptools "entry point" in the ``setup()``
-   function:
+#. Our ``ini/setup.py`` needs a :term:`Setuptools` :term:`entry point` in the ``setup()`` function:
 
    .. literalinclude:: ini/setup.py
        :linenos:
@@ -89,8 +85,7 @@ application. Processing then proceeds as described in the Pyramid chapter on
 
 - ``pserve`` looks for ``[app:main]`` and finds ``use = egg:tutorial``.
 
-- The projects's ``setup.py`` has defined an "entry point" (lines 10-13) for the
-  project's "main" entry point of ``tutorial:main``.
+- The projects's ``setup.py`` has defined an :term:`entry point` (lines 10-13) for the project's "main" :term:`entry point` of ``tutorial:main``.
 
 - The ``tutorial`` package's ``__init__`` has a ``main`` function.
 
@@ -133,8 +128,7 @@ Extra credit
 #. Can we have multiple ``.ini`` configuration files for a project? Why might
    you want to do that?
 
-#. The entry point in ``setup.py`` didn't mention ``__init__.py`` when it
-   declared ``tutorial:main`` function. Why not?
+#. The :term:`entry point` in ``setup.py`` didn't mention ``__init__.py`` when it declared ``tutorial:main`` function. Why not?
 
 #. What is the purpose of ``**settings``? What does the ``**`` signify?
 
diff --git a/docs/quick_tutorial/ini/setup.py b/docs/quick_tutorial/ini/setup.py
index a93cf6a73..7a2677ebd 100644
--- a/docs/quick_tutorial/ini/setup.py
+++ b/docs/quick_tutorial/ini/setup.py
@@ -11,4 +11,4 @@ setup(name='tutorial',
       [paste.app_factory]
       main = tutorial:main
       """,
-)
\ No newline at end of file
+      )
diff --git a/docs/quick_tutorial/jinja2.rst b/docs/quick_tutorial/jinja2.rst
index 6c33e406e..23a9982d3 100644
--- a/docs/quick_tutorial/jinja2.rst
+++ b/docs/quick_tutorial/jinja2.rst
@@ -22,45 +22,55 @@ Objectives
 Steps
 =====
 
-#. In this step let's start by copying the ``view_class`` step's  directory,
-   and then installing the ``pyramid_jinja2`` add-on.
+#.  In this step let's start by copying the ``view_class`` step's directory from a few steps ago.
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       cd ..; cp -r view_classes jinja2; cd jinja2
-       $VENV/bin/pip install -e .
-       $VENV/bin/pip install pyramid_jinja2
+        cd ..; cp -r view_classes jinja2; cd jinja2
 
-#. We need to include ``pyramid_jinja2`` in ``jinja2/tutorial/__init__.py``:
+#.  Add ``pyramid_jinja2`` to our project's dependencies in ``setup.py``:
 
-   .. literalinclude:: jinja2/tutorial/__init__.py
-       :linenos:
+    .. literalinclude:: jinja2/setup.py
+        :language: python
+        :linenos:
+        :emphasize-lines: 7
 
-#. Our ``jinja2/tutorial/views.py`` simply changes its ``renderer``:
+#.  Install our project and its newly added dependency.
 
-   .. literalinclude:: jinja2/tutorial/views.py
-       :linenos:
+    .. code-block:: bash
 
-#. Add ``jinja2/tutorial/home.jinja2`` as a template:
+        $VENV/bin/pip install -e .
 
-   .. literalinclude:: jinja2/tutorial/home.jinja2
-       :language: html
+#.  We need to include ``pyramid_jinja2`` in ``jinja2/tutorial/__init__.py``:
 
-#. Now run the tests:
+    .. literalinclude:: jinja2/tutorial/__init__.py
+        :linenos:
 
-   .. code-block:: bash
+#.  Our ``jinja2/tutorial/views.py`` simply changes its ``renderer``:
 
-       $VENV/bin/pytest tutorial/tests.py -q
-       ....
-       4 passed in 0.40 seconds
+    .. literalinclude:: jinja2/tutorial/views.py
+        :linenos:
 
-#. Run your Pyramid application with:
+#.  Add ``jinja2/tutorial/home.jinja2`` as a template:
 
-   .. code-block:: bash
+    .. literalinclude:: jinja2/tutorial/home.jinja2
+        :language: html
 
-       $VENV/bin/pserve development.ini --reload
+#.  Now run the tests:
 
-#. Open http://localhost:6543/ in your browser.
+    .. code-block:: bash
+
+        $VENV/bin/pytest tutorial/tests.py -q
+        ....
+        4 passed in 0.40 seconds
+
+#.  Run your Pyramid application with:
+
+    .. code-block:: bash
+
+        $VENV/bin/pserve development.ini --reload
+
+#.  Open http://localhost:6543/ in your browser.
 
 
 Analysis
diff --git a/docs/quick_tutorial/jinja2/setup.py b/docs/quick_tutorial/jinja2/setup.py
index a93cf6a73..86f177866 100644
--- a/docs/quick_tutorial/jinja2/setup.py
+++ b/docs/quick_tutorial/jinja2/setup.py
@@ -2,13 +2,22 @@ from setuptools import setup
 
 requires = [
     'pyramid',
+    'pyramid_chameleon',
+    'pyramid_debugtoolbar',
+    'pyramid_jinja2',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
\ No newline at end of file
+      )
diff --git a/docs/quick_tutorial/json/setup.py b/docs/quick_tutorial/json/setup.py
index 744612371..3ad7f004e 100644
--- a/docs/quick_tutorial/json/setup.py
+++ b/docs/quick_tutorial/json/setup.py
@@ -3,13 +3,20 @@ from setuptools import setup
 requires = [
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/logging/setup.py b/docs/quick_tutorial/logging/setup.py
index 744612371..3ad7f004e 100644
--- a/docs/quick_tutorial/logging/setup.py
+++ b/docs/quick_tutorial/logging/setup.py
@@ -3,13 +3,20 @@ from setuptools import setup
 requires = [
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/more_view_classes.rst b/docs/quick_tutorial/more_view_classes.rst
index 684fb1c43..b7e724dcf 100644
--- a/docs/quick_tutorial/more_view_classes.rst
+++ b/docs/quick_tutorial/more_view_classes.rst
@@ -53,7 +53,7 @@ Objectives
 Steps
 =====
 
-#. First we copy the results of the previous step:
+#. First we copy the results of the ``templating`` step:
 
    .. code-block:: bash
 
diff --git a/docs/quick_tutorial/more_view_classes/setup.py b/docs/quick_tutorial/more_view_classes/setup.py
index 744612371..3ad7f004e 100644
--- a/docs/quick_tutorial/more_view_classes/setup.py
+++ b/docs/quick_tutorial/more_view_classes/setup.py
@@ -3,13 +3,20 @@ from setuptools import setup
 requires = [
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/package/setup.py b/docs/quick_tutorial/package/setup.py
index 77fedee2d..a59527bf4 100644
--- a/docs/quick_tutorial/package/setup.py
+++ b/docs/quick_tutorial/package/setup.py
@@ -7,4 +7,4 @@ requires = [
 
 setup(name='tutorial',
       install_requires=requires,
-)
+      )
diff --git a/docs/quick_tutorial/request_response/setup.py b/docs/quick_tutorial/request_response/setup.py
index a93cf6a73..3ad7f004e 100644
--- a/docs/quick_tutorial/request_response/setup.py
+++ b/docs/quick_tutorial/request_response/setup.py
@@ -2,13 +2,21 @@ from setuptools import setup
 
 requires = [
     'pyramid',
+    'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
\ No newline at end of file
+      )
diff --git a/docs/quick_tutorial/routing/setup.py b/docs/quick_tutorial/routing/setup.py
index 744612371..3ad7f004e 100644
--- a/docs/quick_tutorial/routing/setup.py
+++ b/docs/quick_tutorial/routing/setup.py
@@ -3,13 +3,20 @@ from setuptools import setup
 requires = [
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/sessions/setup.py b/docs/quick_tutorial/sessions/setup.py
index 744612371..3ad7f004e 100644
--- a/docs/quick_tutorial/sessions/setup.py
+++ b/docs/quick_tutorial/sessions/setup.py
@@ -3,13 +3,20 @@ from setuptools import setup
 requires = [
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/static_assets/setup.py b/docs/quick_tutorial/static_assets/setup.py
index 744612371..3ad7f004e 100644
--- a/docs/quick_tutorial/static_assets/setup.py
+++ b/docs/quick_tutorial/static_assets/setup.py
@@ -3,13 +3,20 @@ from setuptools import setup
 requires = [
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/templating/setup.py b/docs/quick_tutorial/templating/setup.py
index 744612371..3ad7f004e 100644
--- a/docs/quick_tutorial/templating/setup.py
+++ b/docs/quick_tutorial/templating/setup.py
@@ -3,13 +3,20 @@ from setuptools import setup
 requires = [
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/unit_testing.rst b/docs/quick_tutorial/unit_testing.rst
index 48cffd0e1..2e58ee8d9 100644
--- a/docs/quick_tutorial/unit_testing.rst
+++ b/docs/quick_tutorial/unit_testing.rst
@@ -43,28 +43,39 @@ Objectives
 Steps
 =====
 
-#. First we copy the results of the previous step, as well as install the
-   ``pytest`` package:
+#.  First we copy the results of the previous step.
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-       cd ..; cp -r debugtoolbar unit_testing; cd unit_testing
-       $VENV/bin/pip install -e .
-       $VENV/bin/pip install pytest
+        cd ..; cp -r debugtoolbar unit_testing; cd unit_testing
 
-#. Now we write a simple unit test in ``unit_testing/tutorial/tests.py``:
+#.  Add ``pytest`` to our project's dependencies in ``setup.py`` as a :term:`Setuptools` "extra":
 
-   .. literalinclude:: unit_testing/tutorial/tests.py
-       :linenos:
+    .. literalinclude:: unit_testing/setup.py
+        :language: python
+        :linenos:
+        :emphasize-lines: 11-15
 
-#. Now run the tests:
+#.  Install our project and its newly added dependency.
+    Note that we use the extra specifier ``[test]`` to install testing requirements.
 
-   .. code-block:: bash
+    .. code-block:: bash
 
+        $VENV/bin/pip install -e .[test]
 
-       $VENV/bin/pytest tutorial/tests.py -q
-       .
-       1 passed in 0.14 seconds
+#.  Now we write a simple unit test in ``unit_testing/tutorial/tests.py``:
+
+    .. literalinclude:: unit_testing/tutorial/tests.py
+        :linenos:
+
+#.  Now run the tests:
+
+    .. code-block:: bash
+
+
+        $VENV/bin/pytest tutorial/tests.py -q
+        .
+        1 passed in 0.14 seconds
 
 
 Analysis
@@ -91,6 +102,11 @@ Note that our use of ``pyramid.testing.setUp()`` and
 necessary when your test needs to make use of the ``config`` object (it's a
 Configurator) to add stuff to the configuration state before calling the view.
 
+Finally we've introduced the concept of :term:`Setuptools` extras.
+These are optional or recommended features that may be installed with an "extras" specifier.
+The specifier is the name of a key in a Python dictionary, and is surrounded by square brackets when invoked on the command line.
+The value for the key is a Python list of dependencies.
+
 
 Extra credit
 ============
@@ -114,4 +130,4 @@ Extra credit
 #. Why do we import the ``hello_world`` view function *inside* the
    ``test_hello_world`` method instead of at the top of the module?
 
-.. seealso:: See also :ref:`testing_chapter`
+.. seealso:: See also :ref:`testing_chapter` and `Setuptools Declaring "Extras" (optional features with their own dependencies) <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`_.
diff --git a/docs/quick_tutorial/unit_testing/setup.py b/docs/quick_tutorial/unit_testing/setup.py
index a93cf6a73..617c806aa 100644
--- a/docs/quick_tutorial/unit_testing/setup.py
+++ b/docs/quick_tutorial/unit_testing/setup.py
@@ -2,13 +2,19 @@ from setuptools import setup
 
 requires = [
     'pyramid',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
\ No newline at end of file
+      )
diff --git a/docs/quick_tutorial/view_classes/setup.py b/docs/quick_tutorial/view_classes/setup.py
index 744612371..3ad7f004e 100644
--- a/docs/quick_tutorial/view_classes/setup.py
+++ b/docs/quick_tutorial/view_classes/setup.py
@@ -3,13 +3,20 @@ from setuptools import setup
 requires = [
     'pyramid',
     'pyramid_chameleon',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
+      )
diff --git a/docs/quick_tutorial/views/setup.py b/docs/quick_tutorial/views/setup.py
index a93cf6a73..c0d3dee8f 100644
--- a/docs/quick_tutorial/views/setup.py
+++ b/docs/quick_tutorial/views/setup.py
@@ -2,13 +2,20 @@ from setuptools import setup
 
 requires = [
     'pyramid',
+    'pyramid_debugtoolbar',
     'waitress',
 ]
 
 setup(name='tutorial',
       install_requires=requires,
+      extras_require={
+          'test': [
+              'pytest',
+              'webtest',
+          ],
+      },
       entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
-)
\ No newline at end of file
+      )
diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
index 0005ba3cb..49ee6902e 100644
--- a/docs/tutorials/wiki/basiclayout.rst
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -21,7 +21,7 @@ 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
+configuration points at a :term:`Setuptools` :term:`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``.