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

Docs quick tutorial update

28 files changed, 377 insertions, 230 deletions

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
+      )