Merge pull request #3556 from stevepiercy/docs-synch-cookiecutter-pr-71

Update docs to sync with cookiecutter master branch

1 files changed, 71 insertions, 66 deletions

diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 58bef5701..043f77754 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``
@@ -262,10 +263,11 @@ Here's sample output from a test run on Unix:
 .. code-block:: bash
 
     $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 ``test_it.py`` module in the ``tests`` package in your ``cookiecutter``-generated project.
+Within this project generated by the ``pyramid-cookiecutter-starter`` cookiecutter, only a few sample tests exist.
 
 .. note::
 
@@ -287,7 +289,7 @@ path to the module on which we want to run tests and coverage.
 
 .. code-block:: bash
 
-    $VENV/bin/pytest --cov=myproject myproject/tests.py -q
+    $VENV/bin/pytest --cov=myproject myproject tests -q
 
 .. seealso:: See ``pytest``'s documentation for :ref:`pytest:usage` or invoke
    ``pytest -h`` to see its full set of options.
@@ -402,8 +404,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 +414,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 +465,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 +473,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
@@ -533,6 +536,8 @@ The ``myproject`` project we've generated has the following directory structure:
     ├── .gitignore
     ├── CHANGES.txt
     ├── MANIFEST.in
+    ├── README.txt
+    ├── development.ini
     ├── myproject
     │   ├── __init__.py
     │   ├── routes.py
@@ -544,16 +549,37 @@ The ``myproject`` project we've generated has the following directory structure:
     │   │   ├── 404.jinja2
     │   │   ├── layout.jinja2
     │   │   └── mytemplate.jinja2
-    │   ├── tests.py
     │   └── views
     │       ├── __init__.py
     │       ├── default.py
     │       └── notfound.py
-    ├── README.txt
-    ├── development.ini
     ├── production.ini
     ├── pytest.ini
-    └── setup.py
+    ├── setup.py
+    └── tests
+        ├── __init__.py
+        └── test_it.py
+
+
+.. index::
+   single: tests
+
+``test_it.py``
+~~~~~~~~~~~~~~
+
+The ``test_it.py`` module in the ``tests`` package includes tests for your application.
+
+.. literalinclude:: myproject/tests/test_it.py
+   :language: python
+   :linenos:
+
+This sample ``test_it.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 example.
+
+See :ref:`testing_chapter` for more information about writing :app:`Pyramid` unit tests.
 
 
 The ``myproject`` :term:`Project`
@@ -589,6 +615,8 @@ describe, run, and test your application.
 #. ``setup.py`` is the file you'll use to test and distribute your application.
    It is a standard :term:`Setuptools` ``setup.py`` file.
 
+#. ``tests`` package which contains unit and functional test code for the application.
+
 .. index::
    single: PasteDeploy
    single: ini file
@@ -701,9 +729,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 +747,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 +801,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(exclude=['tests'])`` 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,8 +845,6 @@ 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 ``routes.py`` module, which contains routing code for the application.
 
 #. A ``views`` package, which contains view code for the application.
@@ -850,7 +876,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 +950,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 +977,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
@@ -1037,27 +1065,6 @@ It inherits the HTML provided by ``layout.jinja2``, replacing the content block
 
 
 .. index::
-   single: tests.py
-
-``tests.py``
-~~~~~~~~~~~~
-
-The ``tests.py`` module includes tests for your application.
-
-.. literalinclude:: myproject/myproject/tests.py
-   :language: python
-   :linenos:
-
-This sample ``tests.py`` file has one unit test and one functional test 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
-example.
-
-See :ref:`testing_chapter` for more information about writing :app:`Pyramid`
-unit tests.
-
-.. index::
    pair: modifying; package structure
 
 .. _modifying_package_structure:
@@ -1159,11 +1166,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``, or finally polling to detect changes to the filesystem.
 
 Monitoring Custom Files
 ~~~~~~~~~~~~~~~~~~~~~~~