Update project.rst and its cookiecutter project files

- Update output to reflect current cookiecutter
- Fix minor typos
- Use new links to PyPA for MANIFEST.in description and usage
- Add missing keyword "keywords" to setup.py whirlwind description
- Flip order of `install_requires` and `extras_require` to align with order in setup.py
- Update line numbers and code references
- Add watchman under hupper and rewrite paragraph @mmerickel should review

7 files changed, 58 insertions, 46 deletions

diff --git a/docs/narr/myproject/README.txt b/docs/narr/myproject/README.txt
index 2ffc0acba..6c5a0fee0 100644
--- a/docs/narr/myproject/README.txt
+++ b/docs/narr/myproject/README.txt
@@ -1,4 +1,4 @@
-MyProject
+myproject
 =========
 
 Getting Started
@@ -6,7 +6,7 @@ Getting Started
 
 - Change directory into your newly created project.
 
-    cd MyProject
+    cd myproject
 
 - Create a Python virtual environment.
 
diff --git a/docs/narr/myproject/myproject/tests.py b/docs/narr/myproject/myproject/tests.py
index 05ccadcfb..48f0095ad 100644
--- a/docs/narr/myproject/myproject/tests.py
+++ b/docs/narr/myproject/myproject/tests.py
@@ -14,7 +14,13 @@ class ViewTests(unittest.TestCase):
         from .views.default import my_view
         request = testing.DummyRequest()
         info = my_view(request)
-        self.assertEqual(info['project'], 'MyProject')
+        self.assertEqual(info['project'], 'myproject')
+
+    def test_notfound_view(self):
+        from .views.notfound import notfound_view
+        request = testing.DummyRequest()
+        info = notfound_view(request)
+        self.assertEqual(info, {})
 
 
 class FunctionalTests(unittest.TestCase):
@@ -27,3 +33,7 @@ class FunctionalTests(unittest.TestCase):
     def test_root(self):
         res = self.testapp.get('/', status=200)
         self.assertTrue(b'Pyramid' in res.body)
+
+    def test_notfound(self):
+        res = self.testapp.get('/badurl', status=404)
+        self.assertTrue(res.status_code == 404)
diff --git a/docs/narr/myproject/myproject/views/default.py b/docs/narr/myproject/myproject/views/default.py
index 8324cfe32..619ce1c0f 100644
--- a/docs/narr/myproject/myproject/views/default.py
+++ b/docs/narr/myproject/myproject/views/default.py
@@ -1,6 +1,6 @@
 from pyramid.view import view_config
 
 
-@view_config(route_name='home', renderer='../templates/mytemplate.jinja2')
+@view_config(route_name='home', renderer='myproject:templates/mytemplate.jinja2')
 def my_view(request):
     return {'project': 'myproject'}
diff --git a/docs/narr/myproject/myproject/views/notfound.py b/docs/narr/myproject/myproject/views/notfound.py
index 69d6e2804..5abebb277 100644
--- a/docs/narr/myproject/myproject/views/notfound.py
+++ b/docs/narr/myproject/myproject/views/notfound.py
@@ -1,7 +1,7 @@
 from pyramid.view import notfound_view_config
 
 
-@notfound_view_config(renderer='../templates/404.jinja2')
+@notfound_view_config(renderer='myproject:templates/404.jinja2')
 def notfound_view(request):
     request.response.status = 404
     return {}
diff --git a/docs/narr/myproject/pytest.ini b/docs/narr/myproject/pytest.ini
index b1b5f4c38..332cf0d04 100644
--- a/docs/narr/myproject/pytest.ini
+++ b/docs/narr/myproject/pytest.ini
@@ -1,3 +1,3 @@
 [pytest]
 testpaths = myproject
-python_files = *.py
+python_files = test*.py
diff --git a/docs/narr/myproject/setup.py b/docs/narr/myproject/setup.py
index 1ee272270..40aa2c53b 100644
--- a/docs/narr/myproject/setup.py
+++ b/docs/narr/myproject/setup.py
@@ -25,7 +25,7 @@ tests_require = [
 setup(
     name='myproject',
     version='0.0',
-    description='MyProject',
+    description='myproject',
     long_description=README + '\n\n' + CHANGES,
     classifiers=[
         'Programming Language :: Python',
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 58bef5701..480f9b63d 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -117,7 +117,7 @@ On Unix:
     # Create a new virtual environment...
     python3 -m venv $VENV
     # ...where we upgrade packaging tools.
-    env/bin/pip install --upgrade pip setuptools
+    $VENV/bin/pip install --upgrade pip setuptools
 
 Or on Windows:
 
@@ -208,11 +208,12 @@ Elided output from a run of this command on Unix is shown below:
 .. code-block:: bash
 
     Running setup.py develop for myproject
-    Successfully installed Jinja2-2.8 Mako-1.0.6 MarkupSafe-0.23 \
-    PasteDeploy-1.5.2 Pygments-2.1.3 WebOb-1.7.0 myproject pyramid-1.7.3 \
-    pyramid-debugtoolbar-3.0.5 pyramid-jinja2-2.7 pyramid-mako-1.0.2 \
-    repoze.lru-0.6 translationstring-1.3 venusian-1.0 waitress-1.0.1 \
-    zope.deprecation-4.2.0 zope.interface-4.3.3
+    Successfully installed Jinja2-2.10.3 Mako-1.1.0 MarkupSafe-1.1.1 \
+    PasteDeploy-2.0.1 Pygments-2.5.2 hupper-1.9.1 myproject plaster-1.0 \
+    plaster-pastedeploy-0.7 pyramid-1.10.4 pyramid-debugtoolbar-4.5.1 \
+    pyramid-jinja2-2.8 pyramid-mako-1.1.0 repoze.lru-0.7 \
+    translationstring-1.3 venusian-3.0.0 waitress-1.4.1 webob-1.8.5 \
+    zope.deprecation-4.4.0 zope.interface-4.7.1
 
 This will install a :term:`distribution` representing your project into the
 virtual environment interpreter's library set so it can be found by ``import``
@@ -263,9 +264,9 @@ Here's sample output from a test run on Unix:
 
     $VENV/bin/pytest -q
     ..
-    2 passed in 0.47 seconds
+    4 passed in 0.45 seconds
 
-The tests themselves are found in the ``tests.py`` module in your ``cookiecutter``-generated project.  Within a project generated by the ``pyramid-cookiecutter-starter`` cookiecutter, only two sample tests exist.
+The tests themselves are found in the ``tests.py`` module in your ``cookiecutter``-generated project.  Within this project generated by the ``pyramid-cookiecutter-starter`` cookiecutter, only a few sample tests exist.
 
 .. note::
 
@@ -402,8 +403,8 @@ For example, on Unix:
 .. code-block:: text
 
     $VENV/bin/pserve development.ini --reload
-    Starting subprocess with file monitor
-    Starting server in PID 16601.
+    Starting monitor for PID 36224.
+    Starting server in PID 36224.
     Serving on http://localhost:6543
     Serving on http://localhost:6543
 
@@ -412,9 +413,10 @@ files, you'll see the server restart automatically:
 
 .. code-block:: text
 
-    development.ini changed; reloading...
-    -------------------- Restarting --------------------
-    Starting server in PID 16602.
+    /file-path-to/myproject/development.ini changed; reloading ...
+    Gracefully killing the server.
+    Starting monitor for PID 36286.
+    Starting server in PID 36286.
     Serving on http://localhost:6543
     Serving on http://localhost:6543
 
@@ -462,7 +464,7 @@ browsing from a system that does not have debugging access.  By default, for
 security reasons, only a browser originating from ``localhost`` (``127.0.0.1``)
 can see the debug toolbar.  To allow your browser on a remote system to access
 the server, add a line within the ``[app:main]`` section of the
-``development.ini`` file in the form ``debugtoolbar.hosts = X .X.X.X``.  For
+``development.ini`` file in the form ``debugtoolbar.hosts = X.X.X.X``.  For
 example, if your Pyramid application is running on a remote system, and you're
 browsing from a host with the IP address ``192.168.1.1``, you'd add something
 like this to enable the toolbar when your system contacts Pyramid:
@@ -470,7 +472,7 @@ like this to enable the toolbar when your system contacts Pyramid:
 .. code-block:: ini
 
     [app:main]
-    # .. other settings ...
+    # ... other settings ...
     debugtoolbar.hosts = 192.168.1.1
 
 For more information about what the debug toolbar allows you to do, see the
@@ -701,9 +703,8 @@ specifies the non-Python files that should be included when a
 setup.py sdist``.  Due to the information contained in the default
 ``MANIFEST.in``, an sdist of your Pyramid project will include ``.txt`` files,
 ``.ini`` files, ``.rst`` files, graphics files, and template files, as well as
-``.py`` files.  See
-https://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template
-for more information about the syntax and usage of ``MANIFEST.in``.
+``.py`` files.
+See the Python Packaging Authority's Python Packaging User Guide `Including files in source distributions with MANIFEST.in <https://packaging.python.org/guides/using-manifest-in/>`_ for more information about the syntax and usage of ``MANIFEST.in``.
 
 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
@@ -720,9 +721,8 @@ 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
 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.
+statements necessary to include your new files.
+In the aforementioned Python Packaging User Guide, see `MANIFEST.in commands <https://packaging.python.org/guides/using-manifest-in/#manifest-in-commands>`_ for more information about how to do this.
 
 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
@@ -775,15 +775,17 @@ together. The ``classifiers`` field is a list of `Trove classifiers
 <https://pypi.org/pypi?%3Aaction=list_classifiers>`_ describing your
 application.  ``author`` and ``author_email`` are text fields which probably
 don't need any description. ``url`` is a field that should point at your
-application project's URL (if any). ``packages=find_packages()`` causes all
+application project's URL (if any).
+``keywords`` are keywords that describe your project.
+``packages=find_packages()`` causes all
 packages within the project to be found when packaging the application.
 ``include_package_data`` will include non-Python files when the application is
 packaged if those files are checked into version control. ``zip_safe=False``
 indicates that this package is not safe to use as a zipped egg; instead it will
-always unpack as a directory, which is more convenient. ``install_requires``
-indicates that this package depends on the ``pyramid`` package.
-``extras_require`` is a Python dictionary that defines what is required to be
-installed for running tests. We examined ``entry_points`` in our discussion of
+always unpack as a directory, which is more convenient.
+``extras_require`` is a Python dictionary that defines what is required to be installed for running tests.
+``install_requires`` indicates that this package depends on the ``pyramid`` package.
+We examined ``entry_points`` in our discussion of
 the ``development.ini`` file; this file defines the ``main`` entry point that
 represents our project's application.
 
@@ -817,7 +819,7 @@ The ``myproject`` :term:`package` lives inside the ``myproject``
 #. A ``templates`` directory, which contains :term:`Jinja2` (or other types
    of) templates.
 
-#. A ``tests.py`` module, which contains unit test code for the application.
+#. A ``tests.py`` module, which contains unit and functional test code for the application.
 
 #. A ``routes.py`` module, which contains routing code for the application.
 
@@ -850,7 +852,7 @@ also informs Python that the directory which contains it is a *package*.
 #. Line 1 imports the :term:`Configurator` class from :mod:`pyramid.config`
    that we use later.
 
-#. Lines 4-12 define a function named ``main`` that returns a :app:`Pyramid`
+#. Lines 4-11 define a function named ``main`` that returns a :app:`Pyramid`
    WSGI application.  This function is meant to be called by the
    :term:`PasteDeploy` framework as a result of running ``pserve``.
 
@@ -924,11 +926,13 @@ route named ``home`` to the URL pattern ``/``, this route will match when a
 visitor visits the root URL.  The view_config decorator also names a
 ``renderer``, which in this case is a template that will be used to render the
 result of the view callable.  This particular view declaration points at
-``../templates/mytemplate.jinja2``, which is an :term:`asset specification` that
+``myproject:templates/mytemplate.jinja2``, which is an :term:`asset specification` that
 specifies the ``mytemplate.jinja2`` file within the ``templates`` directory of the
-``myproject`` package.  The asset specification could have also been specified
-as ``myproject:templates/mytemplate.jinja2``; the leading package name and colon is
-optional.  The template file pointed to is a :term:`Jinja2` template
+``myproject`` package.
+There is a second form of asset specification: a relative asset specification.
+Instead of using an "absolute" asset specification which includes the package name, in certain circumstances you can omit the package name from the specification.
+For example, you might be able to use ``../templates/mytemplate.jinja2``.
+The template file pointed to is a :term:`Jinja2` template
 file (``templates/mytemplate.jinja2``).
 
 This view callable function is handed a single piece of information: the
@@ -949,7 +953,7 @@ Now let's look at ``notfound.py``.
    :linenos:
 
 This file is similar to ``default.py``.
-It merely returns a ``404`` response status and an empty dictionary to the template at ``../templates/404.jinja2``.
+It merely returns a ``404`` response status and an empty dictionary to the template at ``myproject:templates/404.jinja2``.
 
 .. note:: When the application is run with the cookiecutter's :ref:`default
    development.ini <myproject_ini>` configuration, :ref:`logging is set up
@@ -1048,7 +1052,7 @@ The ``tests.py`` module includes tests for your application.
    :language: python
    :linenos:
 
-This sample ``tests.py`` file has one unit test and one functional test defined
+This sample ``tests.py`` file has two unit tests and two functional tests defined
 within it. These tests are executed when you run ``pytest -q``. You may add
 more tests here as you build your application. You are not required to write
 tests to use :app:`Pyramid`. This file is simply provided for convenience and
@@ -1159,11 +1163,9 @@ inotify support
 ~~~~~~~~~~~~~~~
 
 By default ``hupper`` will poll the filesystem for changes to all Python
-code. This can be pretty inefficient in larger projects. To be nicer to your
-hard drive, you should install the
-`watchdog <https://pythonhosted.org/watchdog/>`_ package in development.
-``hupper`` will automatically use ``watchdog`` to more efficiently poll the
-filesystem.
+code. This can be pretty inefficient in larger projects.
+To be nicer to your hard drive, you should install either the `watchman <https://facebook.github.io/watchman/>`_ or `watchdog <https://pythonhosted.org/watchdog/>`_ package in development.
+``hupper`` will use, in order of preference for efficiency, if available, ``watchman``, ``watchdog``, then finally ``inotify`` to poll the filesystem.
 
 Monitoring Custom Files
 ~~~~~~~~~~~~~~~~~~~~~~~