From 108121ee8a08837c39379cdd0e2e9c2b5b3712e8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Jul 2016 01:34:25 -0700 Subject: [PATCH 1/3] Update Windows installation instructions and related bits. - Use proper Windows commands, drives, and paths - Use doscon for Windows console lexer --- docs/conventions.rst | 15 +++------- docs/narr/firstapp.rst | 6 ++-- docs/narr/i18n.rst | 2 +- docs/narr/install.rst | 42 +++++++++++++++++++++------- docs/narr/project.rst | 16 +++++------ docs/narr/upgrading.rst | 6 ++-- docs/quick_tour.rst | 4 +-- docs/quick_tutorial/requirements.rst | 2 +- 8 files changed, 54 insertions(+), 39 deletions(-) diff --git a/docs/conventions.rst b/docs/conventions.rst index 43853882c6..de041da047 100644 --- a/docs/conventions.rst +++ b/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 diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index a8491eabdf..ad05976c06 100644 --- a/docs/narr/firstapp.rst +++ b/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 diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 131832aaea..3549b53a56 100644 --- a/docs/narr/i18n.rst +++ b/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:: diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 7d96f4074a..c59ced2a5e 100644 --- a/docs/narr/install.rst +++ b/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 `_ (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 ` 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 + `_ 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) `_ 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 diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 1ce12a9384..812404b76c 100644 --- a/docs/narr/project.rst +++ b/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: @@ -266,7 +266,7 @@ path to the module on which we want to run tests and coverage. Running the Project Application ------------------------------- -.. seealso:: See also the output of :ref:`pserve --help `. +.. seealso:: See also the output of :ref:`pserve --help `. Once a project is installed for development, you can run the application it represents using the ``pserve`` command against the generated configuration @@ -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: diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst index 21b696775a..4e434c3c68 100644 --- a/docs/narr/upgrading.rst +++ b/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 diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index dde91b495e..fb957be1ce 100644 --- a/docs/quick_tour.rst +++ b/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 diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index 62dd570fc3..958347a90a 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\python3 -m venv %VENV% + c:\> c:\Python35\python -m venv %VENV% .. seealso:: See also Python 3's :mod:`venv module ` and Python 2's `virtualenv `_ package. From 446065219c5e43a8116f5b06142de0c75c779618 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Jul 2016 01:39:02 -0700 Subject: [PATCH 2/3] Update Windows installation instructions and related bits. - Use proper Windows commands and paths - Use doscon for Windows console lexer --- CHANGES.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES.txt b/CHANGES.txt index 4fdd7bf2f7..36a8d17ac2 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -25,3 +25,5 @@ Deprecations Documentation Changes --------------------- +- Updated Windows installation instructions and related bits. + See: https://github.com/Pylons/pyramid/issues/2661 \ No newline at end of file From fa257dd74588c9cc80cc3a6b4158ff2c627eacd5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Jul 2016 01:55:29 -0700 Subject: [PATCH 3/3] fix overly aggressive refactor --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 812404b76c..71bd176f6a 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -266,7 +266,7 @@ path to the module on which we want to run tests and coverage. Running the Project Application ------------------------------- -.. seealso:: See also the output of :ref:`pserve --help `. +.. seealso:: See also the output of :ref:`pserve --help `. Once a project is installed for development, you can run the application it represents using the ``pserve`` command against the generated configuration