Merge pull request #2665 from stevepiercy/1.7-branch

Steve Piercy

2016-07-02 1ab3a7f949a9c876f1fcfcb0a6f4290182f369f4

Merge pull request #2665 from stevepiercy/1.7-branch

Update Windows installation instructions and related bits

 CHANGES.txt

@@ -16,6 +16,9 @@
  ``pyramid.config.Configurator.set_request_property`` instead of
  ``pyramid.config.Configurator.add_request_method``.

- Updated Windows installation instructions and related bits.
  See: https://github.com/Pylons/pyramid/issues/2661

1.7 (2016-05-19)
================


 docs/conventions.rst

@@ -57,23 +57,16 @@

     $ $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 @@

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 @@

.. code-block:: doscon

   C> %VENV%\Scripts\pip install lingua
   c:\> %VENV%\Scripts\pip install lingua


.. index::

 docs/narr/install.rst

@@ -92,8 +92,24 @@
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 @@
   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 @@

      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 @@

   .. 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 @@

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 @@

.. 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 @@

.. 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 @@

.. 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 @@

.. 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 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 @@
.. 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 @@
.. 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.