Merge pull request #2900 from stevepiercy/windows-install

Windows documentation updates

6 files changed, 47 insertions, 54 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 10173aec8..2a25ad84d 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -91,29 +91,22 @@ If your Windows system doesn't have a Python interpreter, you'll need to
 install it by downloading a Python 3.x-series interpreter executable from
 `python.org's download section <https://www.python.org/downloads/>`_ (the files
 labeled "Windows Installer").  Once you've downloaded it, double click on the
-executable, and select appropriate options during the installation process. To
+executable and select appropriate options during the installation process. To
 standardize this documentation, we used the GUI installer and selected the
 following options:
 
 - Screen 1: Install Python 3.x.x (32- or 64-bit)
-    - Check "Install launcher for all users (recommended)"
-    - Check "Add Python 3.x to PATH"
-    - Click "Customize installation"
-- Screen 2: Optional Features
-    - Check all options
-    - Click "Next"
-- Screen 3: Advanced Options
-    - Check all options
-    - Customize install location: "C:\\Python3x", where "x" is the minor
-      version of Python
-    - Click "Next"
-
-You might also need to download and install the Python for Windows extensions.
+    - Check "Install launcher for all users (recommended)".
+    - Check "Add Python 3.x to PATH".
+    - Click "Install Now".
+- Screen 2: User Account Control
+    - Click "Yes".
 
 .. seealso:: See the official Python documentation :ref:`Using Python on
    Windows <python:using-on-windows>` for full details.
 
-.. seealso:: Download and install the `Python for Windows extensions
+.. seealso:: You might also need to download and install the `Python for
+   Windows extensions
    <https://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read
    the README.txt file at the end of the list of builds, and follow its
    directions. Make sure you get the proper 32- or 64-bit build and Python
@@ -123,15 +116,26 @@ You might also need to download and install the Python for Windows extensions.
    <https://docs.python.org/3/using/windows.html#launcher>`_ provides a command
    ``py`` that allows users to run any installed version of Python.
 
-.. warning::
+.. warning:: After you install Python on Windows, you might need to add the
+   directory where Python and other programs—such as pip, setuptools, and
+   cookiecutter—are installed to your environment's ``Path``. This will make it
+   possible to invoke them from a command prompt.
 
-   After you install Python on Windows, you might need to add the
-   ``c:\Python3x`` directory to your environment's ``Path``, where ``x`` is the
-   minor version of installed Python, in order to make it possible to invoke
-   Python from a command prompt by typing ``python``. To do so, right click
-   ``My Computer``, select ``Properties`` --> ``Advanced Tab`` -->
-   ``Environment Variables``, and add that directory to the end of the ``Path``
-   environment variable.
+   To do so, search for "Environment Variables" on your computer (on Windows
+   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 ``<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
@@ -231,9 +235,9 @@ After installing Python as described previously in
 
    .. code-block:: doscon
 
+      c:\> cd \
       c:\> set VENV=c:\env
-      # replace "x" with your minor version of Python 3
-      c:\> c:\Python3x\python -m venv %VENV%
+      c:\> python -m venv %VENV%
       c:\> cd %VENV%
 
    You can either follow the use of the environment variable ``%VENV%``, or
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