diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 10173aec87..2a25ad84de 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 `_ (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 ` 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 `_. 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. `_ 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\\AppData\Local\Programs\Python3x-32``, where you have + your username instead of ````, 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\\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) `_ 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 17005f15c4..3d17a41910 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 `, 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 4e434c3c68..e0482d5a24 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 f95dac488c..70e68514bc 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 ` and Python 2's `virtualenv `_ 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 6cd7fbbc26..c735bdf9d5 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 7945669851..fd323fcfc1 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