Update Windows docs

- Installation overhauled
- update project.rst to remove duplication
- Windows paths never end with "\" except for a drive name, for example C:\
- use backslashes for paths
- backslashes cannot be used for line continuation on Windows
- update extra packages for Windows
- Python now has a Windows launcher

6 files changed, 32 insertions, 38 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 59ef9210d..2a25ad84d 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -122,15 +122,20 @@ following options:
    possible to invoke them from a command prompt.
 
    To do so, search for "Environment Variables" on your computer (on Windows
-   10, it is under ``System Properties`` --> ``Advanced``) and append that
-   directory to the end of the ``Path`` environment variable, separating each
-   path segment with a semi-colon (;) or use the GUI to add New or Edit
-   existing path segments. Example segments should look like
+   10, it is under ``System Properties`` --> ``Advanced``) and add that
+   directory to the ``Path`` environment variable, using the GUI to edit path
+   segments.
+
+   Example segments should look like
    ``C:\Users\<username>\AppData\Local\Programs\Python3x-32``, where you have
-   your username instead of the bracketed example, and your version of Python
-   and whether it is 32- or 64-bit. Additionally ensure you have the path
-   segment ending with ``\Scripts``, i.e.,
-   ``C:\Users\<username>\AppData\Local\Programs\Python3x-32\Scripts``.
+   your username instead of ``<username>``, and your version of Python and
+   whether it is 32- or 64-bit. Additionally ensure you have the path segment
+   ending with ``\Scripts``, i.e.,
+   ``C:\Users\<username>\AppData\Local\Programs\Python3x-32\Scripts``, and for
+   user-installed Python programs, ``%APPDATA%\Python\Python3x\Scripts``.
+
+   You may need to restart your command prompt session to load the environment
+   variables.
 
    .. seealso:: See `Configuring Python (on Windows)
       <https://docs.python.org/3/using/windows.html#configuring-python>`_ for
@@ -230,7 +235,7 @@ After installing Python as described previously in
 
    .. code-block:: doscon
 
-      c:\> cd \dir
+      c:\> cd \
       c:\> set VENV=c:\env
       c:\> python -m venv %VENV%
       c:\> cd %VENV%
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 17005f15c..3d17a4191 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -75,27 +75,17 @@ In :ref:`installing_chapter`, you created a virtual Python environment via the
 ``venv`` command. We called the virtual environment directory
 ``env`` and set an environment variable ``VENV`` to its path.
 
-We assume that you previously installed cookiecutter using the following command:
-
-.. code-block:: bash
-
-    $ $VENV/bin/pip install cookiecutter
+We assume that you :ref:`previously installed cookiecutter <cookiecutters>`, following its installation instructions.
 
 We'll choose ``pyramid-cookiecutter-starter`` to start the project.  When we invoke ``cookiecutter``, it will create a directory that represents our project.
 
-The following commands assume that our current working directory is the value of ``$VENV``.
+We assume our current working directory is the value of ``VENV``.
 
-On UNIX:
+On all platforms, generate a project using cookiecutter.
 
 .. code-block:: bash
 
-   $ $VENV/bin/cookiecutter https://github.com/Pylons/pyramid-cookiecutter-starter
-
-Or on Windows:
-
-.. code-block:: doscon
-
-   c:\> %VENV%\Scripts\cookiecutter https://github.com/Pylons/pyramid-cookiecutter-starter
+   $ cookiecutter https://github.com/Pylons/pyramid-cookiecutter-starter
 
 If prompted for the first item, accept the default ``yes`` by hitting return.
 
@@ -128,9 +118,9 @@ Or on Windows:
     # Change directory into your newly created project.
     c:\> cd myproject
     # Create a new virtual environment...
-    c:\myproject\> c:\Python3x\python -m venv %VENV%
+    c:\myproject> python -m venv %VENV%
     # ...where we upgrade packaging tools.
-    c:\myproject\> %VENV%\Scripts\pip install --upgrade pip setuptools
+    c:\myproject> %VENV%\Scripts\pip install --upgrade pip setuptools
 
 As a result of invoking the ``cookiecutter`` command, a directory named
 ``myproject`` is created.  That directory is a :term:`project` directory. The
@@ -201,7 +191,7 @@ Or on Windows:
 
 .. code-block:: doscon
 
-    c:\env\myproject\> %VENV%\Scripts\pip install -e .
+    c:\env\myproject> %VENV%\Scripts\pip install -e .
 
 Elided output from a run of this command on UNIX is shown below:
 
@@ -239,7 +229,7 @@ On Windows:
 
 .. code-block:: doscon
 
-   c:\env\myproject\> %VENV%\Scripts\pip install -e ".[testing]"
+   c:\env\myproject> %VENV%\Scripts\pip install -e ".[testing]"
 
 Once the testing requirements are installed, then you can run the tests using
 the ``py.test`` command that was just installed in the ``bin`` directory of
@@ -255,7 +245,7 @@ On Windows:
 
 .. code-block:: doscon
 
-   c:\env\myproject\> %VENV%\Scripts\py.test -q
+   c:\env\myproject> %VENV%\Scripts\py.test -q
 
 Here's sample output from a test run on UNIX:
 
@@ -320,7 +310,7 @@ On Windows:
 
 .. code-block:: doscon
 
-   c:\env\myproject\> %VENV%\Scripts\pserve development.ini
+   c:\env\myproject> %VENV%\Scripts\pserve development.ini
 
 Here's sample output from a run of ``pserve`` on UNIX:
 
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index 4e434c3c6..e0482d5a2 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -208,7 +208,7 @@ On Windows, you need to issue two commands:
 .. code-block:: doscon
 
    c:\> set PYTHONWARNINGS=default
-   c:\> Scripts/pserve.exe development.ini
+   c:\> Scripts\pserve development.ini
 
 At this point, it's ensured that deprecation warnings will be printed to the
 console whenever a codepath is hit that generates one.  You can then click
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index f95dac488..70e68514b 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -156,7 +156,7 @@ environment variable.
 .. code-block:: doscon
 
     # Windows
-    c:\> c:\Python35\python -m venv %VENV%
+    c:\> python -m venv %VENV%
 
 .. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python
    2's `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ package.
@@ -214,4 +214,4 @@ tutorial.
 .. code-block:: doscon
 
     # Windows
-    c:\> %VENV%\Scripts\pip install webtest deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar pyramid_jinja2 waitress pyramid_tm zope.sqlalchemy
+    c:\> %VENV%\Scripts\pip install webtest pytest pytest-cov deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar pyramid_jinja2 waitress pyramid_tm zope.sqlalchemy
diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index 6cd7fbbc2..c735bdf9d 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -102,7 +102,7 @@ On UNIX
 On Windows
 ^^^^^^^^^^
 
-Each version of Python uses different paths, so you will need to adjust the path to the command for your Python version.
+Each version of Python uses different paths, so you might need to adjust the path to the command for your Python version. Recent versions of the Python 3 installer for Windows now install a Python launcher.
 
 Python 2.7:
 
@@ -114,7 +114,7 @@ Python 3.6:
 
 .. code-block:: doscon
 
-    c:\tutorial> c:\Python36\Scripts\python -m venv %VENV%
+    c:\tutorial> python -m venv %VENV%
 
 
 Upgrade packaging tools in the virtual environment
@@ -242,8 +242,7 @@ On Windows
 
 .. code-block:: doscon
 
-   c:\tutorial> %VENV%\Scripts\py.test --cov \
-       --cov-report=term-missing
+   c:\tutorial> %VENV%\Scripts\py.test --cov --cov-report=term-missing
 
 If successful, you will see output something like this:
 
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index 794566985..fd323fcfc 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -114,7 +114,7 @@ On UNIX
 On Windows
 ^^^^^^^^^^
 
-Each version of Python uses different paths, so you will need to adjust the path to the command for your Python version.
+Each version of Python uses different paths, so you will need to adjust the path to the command for your Python version. Recent versions of the Python 3 installer for Windows now install a Python launcher.
 
 Python 2.7:
 
@@ -126,7 +126,7 @@ Python 3.6:
 
 .. code-block:: doscon
 
-    c:\tutorial> c:\Python36\Scripts\python -m venv %VENV%
+    c:\tutorial> python -m venv %VENV%
 
 
 Upgrade packaging tools in the virtual environment