From 34a7a85436e1545356345affc21dd1a564635469 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Sun, 7 Oct 2018 03:41:55 -0700
Subject: Make pytest an extra dependency in setup.py. Add paragraph on
 Setuptools extras. Carry forward previous setup.py changes.

---
 docs/quick_tutorial/unit_testing.rst | 46 ++++++++++++++++++++++++------------
 1 file changed, 31 insertions(+), 15 deletions(-)

(limited to 'docs/quick_tutorial/unit_testing.rst')

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>`_.
-- 
cgit v1.2.3