Merge pull request #2664 from stevepiercy/master

Update Windows installation instructions and related bits.

CHANGES.txt

@@ -25,3 +25,5 @@ Deprecations
 
 Documentation Changes
 ---------------------
+- Updated Windows installation instructions and related bits.
+  See: https://github.com/Pylons/pyramid/issues/2661

docs/conventions.rst

@@ -57,23 +57,16 @@ character, e.g.:
 
      $ $VENV/bin/py.test -q
 
-(See :term:`venv` for the meaning of ``$VENV``)
+See :term:`venv` for the meaning of ``$VENV``.
 
-Example blocks representing Windows ``cmd.exe`` commands are prefixed with a
-drive letter and/or a directory name, e.g.:
+Example blocks representing Windows commands are prefixed with a drive letter
+with an optional directory name, e.g.:
 
   .. code-block:: doscon
 
      c:\examples> %VENV%\Scripts\py.test -q
 
-(See :term:`venv` for the meaning of ``%VENV%``)
-
-Sometimes, when it's unknown which directory is current, Windows ``cmd.exe``
-example block commands are prefixed only with a ``>`` character, e.g.:
-
-  .. code-block:: doscon
-
-     > %VENV%\Scripts\py.test -q
+See :term:`venv` for the meaning of ``%VENV%``.
 
 When a command that should be typed on one line is too long to fit on a page,
 the backslash ``\`` is used to indicate that the following printed line should

docs/narr/firstapp.rst

@@ -27,15 +27,15 @@ installed, an HTTP server is started on TCP port 8080.
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/python helloworld.py
 
 On Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   C:\> %VENV%\Scripts\python.exe helloworld.py
+   c:\> %VENV%\Scripts\python helloworld.py
 
 This command will not return and nothing will be printed to the console. When
 port 8080 is visited by a browser on the URL ``/hello/world``, the server will

docs/narr/i18n.rst

@@ -294,7 +294,7 @@ Lingua like so:
 
 .. code-block:: doscon
 
-   C> %VENV%\Scripts\pip install lingua
+   c:\> %VENV%\Scripts\pip install lingua
 
 
 .. index::

docs/narr/install.rst

@@ -92,8 +92,24 @@ 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 accept the defaults during the installation process. You may
-also need to download and install the Python for Windows extensions.
+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.
 
 .. seealso:: See the official Python documentation :ref:`Using Python on
    Windows <python:using-on-windows>` for full details.
@@ -104,14 +120,19 @@ also need to download and install the Python for Windows extensions.
    directions. Make sure you get the proper 32- or 64-bit build and Python
    version.
 
+.. seealso:: `Python launcher for Windows
+   <https://docs.python.org/3/using/windows.html#launcher>`_ provides a command
+   ``py`` that allows users to run any installed version of Python.
+
 .. warning::
 
-   After you install Python on Windows, you may 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.
+   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.
 
    .. seealso:: See `Configuring Python (on Windows)
       <https://docs.python.org/3/using/windows.html#configuring-python>`_ for
@@ -190,7 +211,8 @@ After installing Python as described previously in
 
       c:\> set VENV=c:\env
       # replace "x" with your minor version of Python 3
-      c:\> c:\Python3x\Scripts\python3 -m venv %VENV%
+      c:\> c:\Python3x\python -m venv %VENV%
+      c:\> cd %VENV%
 
    You can either follow the use of the environment variable ``%VENV%``, or
    replace it with the root directory of the virtual environment. If you choose
@@ -204,7 +226,7 @@ After installing Python as described previously in
 
    .. parsed-literal::
 
-      c:\\env> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
+      c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
 
 
 What Gets Installed

docs/narr/project.rst

@@ -87,9 +87,9 @@ On UNIX:
 
 Or on Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   > %VENV%\Scripts\pcreate -s starter MyProject
+   c:\> %VENV%\Scripts\pcreate -s starter MyProject
 
 As a result of invoking the ``pcreate`` command, a directory named
 ``MyProject`` is created.  That directory is a :term:`project` directory. The
@@ -161,8 +161,8 @@ Or on Windows:
 
 .. code-block:: doscon
 
-   > cd MyProject
-   > %VENV%\Scripts\pip install -e .
+   c:\> cd MyProject
+   c:\> %VENV%\Scripts\pip install -e .
 
 Elided output from a run of this command on UNIX is shown below:
 
@@ -199,7 +199,7 @@ On Windows:
 
 .. code-block:: doscon
 
-   > %VENV%\Scripts\pip install -e ".[testing]"
+   c:\> %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
@@ -215,7 +215,7 @@ On Windows:
 
 .. code-block:: doscon
 
-   > %VENV%\Scripts\py.test -q
+   c:\> %VENV%\Scripts\py.test -q
 
 Here's sample output from a test run on UNIX:
 
@@ -282,7 +282,7 @@ On Windows:
 
 .. code-block:: text
 
-   > %VENV%\Scripts\pserve development.ini
+   c:\> %VENV%\Scripts\pserve development.ini
 
 Here's sample output from a run of ``pserve`` on UNIX:
 

docs/narr/upgrading.rst

@@ -205,10 +205,10 @@ On UNIX, you can do that via:
 
 On Windows, you need to issue two commands:
 
-.. code-block:: bash
+.. code-block:: doscon
 
-   C:\> set PYTHONWARNINGS=default
-   C:\> Scripts/pserve.exe development.ini
+   c:\> set PYTHONWARNINGS=default
+   c:\> Scripts/pserve.exe 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

docs/quick_tour.rst

@@ -44,9 +44,9 @@ For Windows:
 .. parsed-literal::
 
     # set an environment variable to where you want your virtual environment
-    c:\> set VENV=c:\env
+    c:\\> set VENV=c:\\env
     # create the virtual environment
-    c:\\> c:\\Python35\\python3 -m venv %VENV%
+    c:\\> %VENV%\\Scripts\\python -m venv %VENV%
     # install pyramid
     c:\\> %VENV%\\Scripts\\pip install pyramid
     # or for a specific released version

docs/quick_tutorial/requirements.rst

@@ -156,7 +156,7 @@ environment variable.
 .. code-block:: doscon
 
     # Windows
-    c:\> c:\Python35\python3 -m venv %VENV%
+    c:\> c:\Python35\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.