Merge pull request #2484 from stevepiercy/docs/easy-install-to-pip.2104

one does not simply "create a virtualenv". one should "create a virtu…

12 files changed, 87 insertions, 85 deletions

diff --git a/docs/conventions.rst b/docs/conventions.rst
index a9d2550bf..0346f1107 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -57,7 +57,7 @@ character, e.g.:
 
      $ $VENV/bin/nosetests
 
-(See :term:`virtualenv` 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.:
@@ -66,7 +66,7 @@ drive letter and/or a directory name, e.g.:
 
      c:\examples> %VENV%\Scripts\nosetests
 
-(See :term:`virtualenv` for the meaning of ``%VENV%``)
+(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.:
diff --git a/docs/glossary.rst b/docs/glossary.rst
index fd32ed796..4c17c0f0b 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -155,9 +155,9 @@ Glossary
      request before it returns a :term:`context` resource.
 
    virtualenv
-     A term referring both to an isolated Python environment,
-     or `the leading tool <http://www.virtualenv.org>`_ that allows one to
-     create such environments.
+     The `virtualenv tool <https://virtualenv.pypa.io/en/latest/>`_ that allows
+     one to create virtual environments. In Python 3.3 and greater,
+     :term:`venv` is the preferred tool.
 
      Note: whenever you encounter commands prefixed with ``$VENV`` (Unix)
      or ``%VENV`` (Windows), know that that is the environment variable whose
@@ -1012,8 +1012,8 @@ Glossary
 
    console script
      A script written to the ``bin`` (on UNIX, or ``Scripts`` on Windows)
-     directory of a Python installation or :term:`virtualenv` as the result of
-     running ``setup.py install`` or ``setup.py develop``.
+     directory of a Python installation or :term:`virtual environment` as the
+     result of running ``pip install`` or ``pip install -e .``.
 
    introspector
      An object with the methods described by
@@ -1110,6 +1110,14 @@ Glossary
       but it is deprecated in 3.6 in favor of ``python3 -m venv`` which is
       backward compatible.
 
+   virtual environment
+      An isolated Python environment that allows packages to be installed for
+      use by a particular application, rather than being installed system wide.
+
    venv
       The `Python Packaging Authority's <https://www.pypa.io/>`_ recommended
       tool for creating virtual environments.
+
+      Note: whenever you encounter commands prefixed with ``$VENV`` (Unix)
+      or ``%VENV`` (Windows), know that that is the environment variable whose
+      value is the root of the virtual environment in question.
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 7f112550f..6cd90d42f 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -815,17 +815,17 @@ Making Your Script into a Console Script
 ----------------------------------------
 
 A "console script" is :term:`setuptools` terminology for a script that gets
-installed into the ``bin`` directory of a Python :term:`virtualenv` (or "base"
-Python environment) when a :term:`distribution` which houses that script is
-installed.  Because it's installed into the ``bin`` directory of a virtualenv
-when the distribution is installed, it's a convenient way to package and
-distribute functionality that you can call from the command-line. It's often
-more convenient to create a console script than it is to create a ``.py``
-script and instruct people to call it with the "right" Python interpreter.  A
-console script generates a file that lives in ``bin``, and when it's invoked it
-will always use the "right" Python environment, which means it will always be
-invoked in an environment where all the libraries it needs (such as Pyramid)
-are available.
+installed into the ``bin`` directory of a Python :term:`virtual environment`
+(or "base" Python environment) when a :term:`distribution` which houses that
+script is installed. Because it's installed into the ``bin`` directory of a
+virtual environment when the distribution is installed, it's a convenient way
+to package and distribute functionality that you can call from the
+command-line. It's often more convenient to create a console script than it is
+to create a ``.py`` script and instruct people to call it with the "right"
+Python interpreter. A console script generates a file that lives in ``bin``,
+and when it's invoked it will always use the "right" Python environment, which
+means it will always be invoked in an environment where all the libraries it
+needs (such as Pyramid) are available.
 
 In general, you can make your script into a console script by doing the
 following:
@@ -843,7 +843,7 @@ following:
 - Run ``pip install -e .`` or ``pip install .`` to get your distribution
   reinstalled. When you reinstall your distribution, a file representing the
   script that you named in the last step will be in the ``bin`` directory of
-  the virtualenv in which you installed the distribution. It will be
+  the virtual environment in which you installed the distribution. It will be
   executable. Invoking it from a terminal will execute your callable.
 
 As an example, let's create some code that can be invoked by a console script
@@ -1029,7 +1029,7 @@ The result will be something like:
          )
 
 Once you've done this, invoking ``$VENV/bin/pip install -e .`` will install a
-file named ``show_settings`` into the ``$somevirtualenv/bin`` directory with a
+file named ``show_settings`` into the ``$somevenv/bin`` directory with a
 small bit of Python code that points to your entry point. It will be
 executable. Running it without any arguments will print an error and exit.
 Running it with a single argument that is the path of a config file will print
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index b385eaf96..93e355ffe 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -270,12 +270,12 @@ system run this command:
    $ sudo apt-get install gettext
 
 Installing Lingua is done with the Python packaging tools. If the
-:term:`virtualenv` into which you've installed your :app:`Pyramid` application
-lives in ``/my/virtualenv``, you can install Lingua like so:
+:term:`virtual environment` into which you've installed your :app:`Pyramid`
+application lives in ``/my/venv``, you can install Lingua like so:
 
 .. code-block:: text
 
-   $ cd /my/virtualenv
+   $ cd /my/venv
    $ $VENV/bin/easy_install lingua
 
 Installation on Windows
@@ -288,8 +288,8 @@ compile it yourself. Make sure the installation path is added to your
 ``$PATH``.
 
 Installing Lingua is done with the Python packaging tools. If the
-:term:`virtualenv` into which you've installed your :app:`Pyramid` application
-lives in ``C:\my\virtualenv``, you can install Lingua like so:
+:term:`virtual environment` into which you've installed your :app:`Pyramid`
+application lives in ``C:\my\venv``, you can install Lingua like so:
 
 .. code-block:: text
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 548d040f1..7cd47d681 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -150,7 +150,7 @@ After installing Python as described previously in :ref:`for-mac-os-x-users` or
 :ref:`if-you-don-t-yet-have-a-python-interpreter-unix`, and satisfying the
 :ref:`requirements-for-installing-packages`, you can now install Pyramid.
 
-#. Make a :term:`virtualenv` workspace:
+#. Make a :term:`virtual environment` workspace:
 
    .. code-block:: bash
 
@@ -184,7 +184,7 @@ After installing Python as described previously in
 :ref:`if-you-don-t-yet-have-a-python-interpreter-windows`, and satisfying the
 :ref:`requirements-for-installing-packages`, you can now install Pyramid.
 
-#. Make a :term:`virtualenv` workspace:
+#. Make a :term:`virtual environment` workspace:
 
    .. code-block:: ps1con
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 355a42d8a..24e484c11 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -67,14 +67,14 @@ Creating the Project
 .. seealso:: See also the output of :ref:`pcreate --help <pcreate_script>`.
 
 In :ref:`installing_chapter`, you created a virtual Python environment via the
-``virtualenv`` command.  To start a :app:`Pyramid` :term:`project`, use the
-``pcreate`` command installed within the virtualenv.  We'll choose the
+``venv`` command.  To start a :app:`Pyramid` :term:`project`, use the
+``pcreate`` command installed within the virtual environment.  We'll choose the
 ``starter`` scaffold for this purpose.  When we invoke ``pcreate``, it will
 create a directory that represents our project.
 
-In :ref:`installing_chapter` we called the virtualenv directory ``env``. The
-following commands assume that our current working directory is the ``env``
-directory.
+In :ref:`installing_chapter` we called the virtual environment directory
+``env``. The following commands assume that our current working directory is
+the ``env`` directory.
 
 The below example uses the ``pcreate`` command to create a project with the
 ``starter`` scaffold.
@@ -112,16 +112,16 @@ The ``MyProject`` project directory contains an additional subdirectory named
 which holds very simple :app:`Pyramid` sample code.  This is where you'll edit
 your application's Python code and templates.
 
-We created this project within an ``env`` virtualenv directory.  However, note
-that this is not mandatory.  The project directory can go more or less anywhere
-on your filesystem.  You don't need to put it in a special "web server"
-directory, and you don't need to put it within a virtualenv directory.  The
-author uses Linux mainly, and tends to put project directories which he creates
-within his ``~/projects`` directory.  On Windows, it's a good idea to put
-project directories within a directory that contains no space characters, so
-it's wise to *avoid* a path that contains, i.e., ``My Documents``.  As a
-result, the author, when he uses Windows, just puts his projects in
-``C:\projects``.
+We created this project within an ``env`` virtual environment directory.
+However, note that this is not mandatory. The project directory can go more or
+less anywhere on your filesystem. You don't need to put it in a special "web
+server" directory, and you don't need to put it within a virtual environment
+directory. The author uses Linux mainly, and tends to put project directories
+which he creates within his ``~/projects`` directory. On Windows, it's a good
+idea to put project directories within a directory that contains no space
+characters, so it's wise to *avoid* a path that contains, i.e., ``My
+Documents``. As a result, the author, when he uses Windows, just puts his
+projects in ``C:\projects``.
 
 .. warning::
 
@@ -140,9 +140,9 @@ Installing your Newly Created Project for Development
 
 To install a newly created project for development, you should ``cd`` to the
 newly created project directory and use the Python interpreter from the
-:term:`virtualenv` you created during :ref:`installing_chapter` to invoke the
-command ``pip install -e .``, which installs the project in development mode
-(``-e`` is for "editable") into the current directory (``.``).
+:term:`virtual environment` you created during :ref:`installing_chapter` to
+invoke the command ``pip install -e .``, which installs the project in
+development mode (``-e`` is for "editable") into the current directory (``.``).
 
 The file named ``setup.py`` will be in the root of the pcreate-generated
 project directory.  The ``python`` you're invoking should be the one that lives
diff --git a/docs/quick_tutorial/databases.rst b/docs/quick_tutorial/databases.rst
index 311ff6ec5..f9f548585 100644
--- a/docs/quick_tutorial/databases.rst
+++ b/docs/quick_tutorial/databases.rst
@@ -176,7 +176,7 @@ module.
 
 The ``initialize_tutorial_db`` is a nice example of framework support.
 You point your setup at the location of some ``[console_scripts]`` and
-these get generated into your virtualenv's ``bin`` directory. Our
+these get generated into your virtual environment's ``bin`` directory. Our
 console script follows the pattern of being fed a configuration file
 with all the bootstrapping. It then opens SQLAlchemy and creates the
 root of the wiki, which also makes the SQLite file. Note the
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index 17ce845e2..9e10e3ebe 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -129,7 +129,7 @@ order to avoid spaces in any of the path names.
 Next within ``projects`` is your workspace directory, here named
 ``quick_tutorial``. A workspace is a common term used by integrated
 development environments (IDE) like PyCharm and PyDev that stores
-isolated Python environments (virtualenvs) and specific project files
+isolated Python environments (virtual environments) and specific project files
 and repositories.
 
 
@@ -174,7 +174,7 @@ environment variable.
     c:\> c:\Python35\python3 -m venv %VENV%
 
 .. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python
-   2's `virtualenv <http://www.virtualenv.org/en/latest/>`_ package.
+   2's `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ package.
 
 
 .. _install-pyramid:
diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst
index 1a149b44a..0885a42ab 100644
--- a/docs/tutorials/modwsgi/index.rst
+++ b/docs/tutorials/modwsgi/index.rst
@@ -24,21 +24,15 @@ specific path information for commands and files.
     system.  If you do not, install Apache 2.X for your platform in
     whatever manner makes sense.
 
+#.  It is also assumed that you have satisfied the
+    :ref:`requirements-for-installing-packages`.
+
 #.  Once you have Apache installed, install ``mod_wsgi``.  Use the
     (excellent) `installation instructions
     <http://code.google.com/p/modwsgi/wiki/InstallationInstructions>`_
     for your platform into your system's Apache installation.
 
-#.  Install :term:`virtualenv` into the Python which mod_wsgi will
-    run using pip.
-
-    .. code-block:: text
-
-       $ sudo /usr/bin/pip install virtualenv
-
-    This command may need to be performed as the root user.
-
-#.  Create a :term:`virtualenv` which we'll use to install our
+#.  Create a :term:`virtual environment` which we'll use to install our
     application.
 
     .. code-block:: text
@@ -46,9 +40,9 @@ specific path information for commands and files.
        $ cd ~
        $ mkdir modwsgi
        $ cd modwsgi
-       $ /usr/local/bin/virtualenv env
+       $ python3 -m venv env
 
-#.  Install :app:`Pyramid` into the newly created virtualenv:
+#.  Install :app:`Pyramid` into the newly created virtual environment:
 
     .. code-block:: text
 
@@ -67,7 +61,7 @@ specific path information for commands and files.
        $ cd myapp
        $ $VENV/bin/pip install -e .
 
-#.  Within the virtualenv directory (``~/modwsgi/env``), create a
+#.  Within the virtual environment directory (``~/modwsgi/env``), create a
     script named ``pyramid.wsgi``.  Give it these contents:
 
     .. code-block:: python
diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst
index a7ea601ee..8bdf51021 100644
--- a/docs/tutorials/wiki/distributing.rst
+++ b/docs/tutorials/wiki/distributing.rst
@@ -7,8 +7,8 @@ Distributing Your Application
 Once your application works properly, you can create a "tarball" from it by
 using the ``setup.py sdist`` command.  The following commands assume your
 current working directory is the ``tutorial`` package we've created and that
-the parent directory of the ``tutorial`` package is a virtualenv representing
-a :app:`Pyramid` environment.
+the parent directory of the ``tutorial`` package is a virtual environment
+representing a :app:`Pyramid` environment.
 
 On UNIX:
 
diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index c50faa2e3..b1b89d117 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -12,8 +12,7 @@ This tutorial assumes that you have already followed the steps in
 install Pyramid**.  Thereby you will satisfy the following requirements.
 
 * A Python interpreter is installed on your operating system.
-* :term:`virtualenv` is installed.
-* :term:`pip` will be installed when we create a virtual environment.
+* You've satisfied the :ref:`requirements-for-installing-packages`.
 
 
 Create directory to contain the project
@@ -39,8 +38,8 @@ On Windows
 Create and use a virtual Python environment
 -------------------------------------------
 
-Next let's create a ``virtualenv`` workspace for our project.  We will use the
-``VENV`` environment variable instead of the absolute path of the virtual
+Next let's create a virtual environment workspace for our project.  We will use
+the ``VENV`` environment variable instead of the absolute path of the virtual
 environment.
 
 On UNIX
@@ -49,7 +48,7 @@ On UNIX
 .. code-block:: bash
 
    $ export VENV=~/pyramidtut
-   $ virtualenv $VENV
+   $ python3 -m venv $VENV
 
 On Windows
 ^^^^^^^^^^
@@ -71,7 +70,7 @@ Python 3.5:
 
 .. code-block:: ps1con
 
-   c:\> c:\Python35\Scripts\virtualenv %VENV%
+   c:\> c:\Python35\Scripts\python -m venv %VENV%
 
 
 Upgrade ``pip`` and ``setuptools`` in the virtual environment
@@ -164,8 +163,9 @@ On Windows
 
 .. note:: If you are using Windows, the ``zodb`` scaffold may not deal
    gracefully with installation into a location that contains spaces in the
-   path. If you experience startup problems, try putting both the virtualenv
-   and the project into directories that do not contain spaces in their paths.
+   path. If you experience startup problems, try putting both the virtual
+   environment and the project into directories that do not contain spaces in
+   their paths.
 
 
 .. _installing_project_in_dev_mode_zodb:
@@ -177,7 +177,7 @@ In order to do development on the project easily, you must "register" the
 project as a development egg in your workspace using the ``pip install -e .``
 command. In order to do so, change directory to the ``tutorial`` directory that
 you created in :ref:`making_a_project`, and run the ``pip install -e .``
-command using the virtualenv Python interpreter.
+command using the virtual environment Python interpreter.
 
 On UNIX
 ^^^^^^^
@@ -283,8 +283,8 @@ runs the tests in the same way that ``py.test`` does, but provides additional
 "coverage" information, exposing which lines of your project are covered by the
 tests.
 
-We've already installed the ``pytest-cov`` package into our ``virtualenv``, so
-we can run the tests with coverage.
+We've already installed the ``pytest-cov`` package into our virtual
+environment, so we can run the tests with coverage.
 
 On UNIX
 ^^^^^^^
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index b44a96325..c3350c792 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -12,8 +12,7 @@ This tutorial assumes that you have already followed the steps in
 install Pyramid**.  Thereby you will satisfy the following requirements.
 
 * A Python interpreter is installed on your operating system.
-* :term:`virtualenv` is installed.
-* :term:`pip` will be installed when we create a virtual environment.
+* You've satisfied the :ref:`requirements-for-installing-packages`.
 
 
 Create directory to contain the project
@@ -39,8 +38,8 @@ On Windows
 Create and use a virtual Python environment
 -------------------------------------------
 
-Next let's create a ``virtualenv`` workspace for our project.  We will use the
-``VENV`` environment variable instead of the absolute path of the virtual
+Next let's create a virtual environment workspace for our project.  We will use
+the ``VENV`` environment variable instead of the absolute path of the virtual
 environment.
 
 On UNIX
@@ -49,7 +48,7 @@ On UNIX
 .. code-block:: bash
 
    $ export VENV=~/pyramidtut
-   $ virtualenv $VENV
+   $ python3 -m venv $VENV
 
 On Windows
 ^^^^^^^^^^
@@ -71,7 +70,7 @@ Python 3.5:
 
 .. code-block:: ps1con
 
-   c:\> c:\Python35\Scripts\virtualenv %VENV%
+   c:\> c:\Python35\Scripts\python -m venv %VENV%
 
 
 Upgrade ``pip`` and ``setuptools`` in the virtual environment
@@ -185,8 +184,9 @@ On Windows
 
 .. note:: If you are using Windows, the ``alchemy`` scaffold may not deal
    gracefully with installation into a location that contains spaces in the
-   path. If you experience startup problems, try putting both the virtualenv
-   and the project into directories that do not contain spaces in their paths.
+   path. If you experience startup problems, try putting both the virtual
+   environment and the project into directories that do not contain spaces in
+   their paths.
 
 
 .. _installing_project_in_dev_mode:
@@ -198,7 +198,7 @@ In order to do development on the project easily, you must "register" the
 project as a development egg in your workspace using the ``pip install -e .``
 command. In order to do so, change directory to the ``tutorial`` directory that
 you created in :ref:`sql_making_a_project`, and run the ``pip install -e .``
-command using the virtualenv Python interpreter.
+command using the virtual environment Python interpreter.
 
 On UNIX
 ^^^^^^^
@@ -302,8 +302,8 @@ runs the tests in the same way that ``py.test`` does, but provides additional
 "coverage" information, exposing which lines of your project are covered by the
 tests.
 
-We've already installed the ``pytest-cov`` package into our ``virtualenv``, so
-we can run the tests with coverage.
+We've already installed the ``pytest-cov`` package into our virtual
+environment, so we can run the tests with coverage.
 
 On UNIX
 ^^^^^^^