[doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (GH-98350)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

2 files changed, 84 insertions, 95 deletions

diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index 40eccde..adc6cd3 100644
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -15,14 +15,22 @@
 
 --------------
 
-The :mod:`venv` module provides support for creating lightweight "virtual
-environments" with their own site directories, optionally isolated from system
-site directories.  Each virtual environment has its own Python binary (which
-matches the version of the binary that was used to create this environment) and
-can have its own independent set of installed Python packages in its site
-directories.
+.. _venv-def:
+.. _venv-intro:
+
+The :mod:`!venv` module supports creating lightweight "virtual environments",
+each with their own independent set of Python packages installed in
+their :mod:`site` directories.
+A virtual environment is created on top of an existing
+Python installation, known as the virtual environment's "base" Python, and may
+optionally be isolated from the packages in the base environment,
+so only those explicitly installed in the virtual environment are available.
 
-See :pep:`405` for more information about Python virtual environments.
+When used from within a virtual environment, common installation tools such as
+`pip`_ will install Python packages into a virtual environment
+without needing to be told to do so explicitly.
+
+See :pep:`405` for more background on Python virtual environments.
 
 .. seealso::
 
@@ -36,54 +44,72 @@ Creating virtual environments
 
 .. include:: /using/venv-create.inc
 
+.. _venv-explanation:
 
-.. _venv-def:
+How venvs work
+--------------
 
-.. note:: A virtual environment is a Python environment such that the Python
-   interpreter, libraries and scripts installed into it are isolated from those
-   installed in other virtual environments, and (by default) any libraries
-   installed in a "system" Python, i.e., one which is installed as part of your
-   operating system.
-
-   A virtual environment is a directory tree which contains Python executable
-   files and other files which indicate that it is a virtual environment.
-
-   Common installation tools such as setuptools_ and pip_ work as
-   expected with virtual environments. In other words, when a virtual
-   environment is active, they install Python packages into the virtual
-   environment without needing to be told to do so explicitly.
-
-   When a virtual environment is active (i.e., the virtual environment's Python
-   interpreter is running), the attributes :attr:`sys.prefix` and
-   :attr:`sys.exec_prefix` point to the base directory of the virtual
-   environment, whereas :attr:`sys.base_prefix` and
-   :attr:`sys.base_exec_prefix` point to the non-virtual environment Python
-   installation which was used to create the virtual environment. If a virtual
-   environment is not active, then :attr:`sys.prefix` is the same as
-   :attr:`sys.base_prefix` and :attr:`sys.exec_prefix` is the same as
-   :attr:`sys.base_exec_prefix` (they all point to a non-virtual environment
-   Python installation).
-
-   When a virtual environment is active, any options that change the
-   installation path will be ignored from all ``setuptools`` configuration
-   files to prevent projects being inadvertently installed outside of the
-   virtual environment.
-
-   When working in a command shell, users can make a virtual environment active
-   by running an ``activate`` script in the virtual environment's executables
-   directory (the precise filename and command to use the file is
-   shell-dependent), which prepends the virtual environment's directory for
-   executables to the ``PATH`` environment variable for the running shell. There
-   should be no need in other circumstances to activate a virtual
-   environment; scripts installed into virtual environments have a "shebang"
-   line which points to the virtual environment's Python interpreter. This means
-   that the script will run with that interpreter regardless of the value of
-   ``PATH``. On Windows, "shebang" line processing is supported if you have the
-   Python Launcher for Windows installed (this was added to Python in 3.3 - see
-   :pep:`397` for more details). Thus, double-clicking an installed script in a
-   Windows Explorer window should run the script with the correct interpreter
-   without there needing to be any reference to its virtual environment in
-   ``PATH``.
+When a Python interpreter is running from a virtual environment,
+:data:`sys.prefix` and :data:`sys.exec_prefix`
+point to the directories of the virtual environment,
+whereas :data:`sys.base_prefix` and :data:`sys.base_exec_prefix`
+point to those of the base Python used to create the environment.
+It is sufficient to check
+``sys.prefix == sys.base_prefix`` to determine if the current interpreter is
+running from a virtual environment.
+
+A virtual environment may be "activated" using a script in its binary directory
+(``bin`` on POSIX; ``Scripts`` on Windows).
+This will prepend that directory to your :envvar:`!PATH`, so that running
+:program:`!python` will invoke the environment's Python interpreter
+and you can run installed scripts without having to use their full path.
+The invocation of the activation script is platform-specific
+(:samp:`{<venv>}` must be replaced by the path to the directory
+containing the virtual environment):
+
++-------------+------------+--------------------------------------------------+
+| Platform    | Shell      | Command to activate virtual environment          |
++=============+============+==================================================+
+| POSIX       | bash/zsh   | :samp:`$ source {<venv>}/bin/activate`           |
+|             +------------+--------------------------------------------------+
+|             | fish       | :samp:`$ source {<venv>}/bin/activate.fish`      |
+|             +------------+--------------------------------------------------+
+|             | csh/tcsh   | :samp:`$ source {<venv>}/bin/activate.csh`       |
+|             +------------+--------------------------------------------------+
+|             | PowerShell | :samp:`$ {<venv>}/bin/Activate.ps1`              |
++-------------+------------+--------------------------------------------------+
+| Windows     | cmd.exe    | :samp:`C:\\> {<venv>}\\Scripts\\activate.bat`    |
+|             +------------+--------------------------------------------------+
+|             | PowerShell | :samp:`PS C:\\> {<venv>}\\Scripts\\Activate.ps1` |
++-------------+------------+--------------------------------------------------+
+
+.. versionadded:: 3.4
+   :program:`!fish` and :program:`!csh` activation scripts.
+
+.. versionadded:: 3.8
+   PowerShell activation scripts installed under POSIX for PowerShell Core
+   support.
+
+You don't specifically *need* to activate a virtual environment,
+as you can just specify the full path to that environment's
+Python interpreter when invoking Python.
+Furthermore, all scripts installed in the environment
+should be runnable without activating it.
+
+In order to achieve this, scripts installed into virtual environments have
+a "shebang" line which points to the environment's Python interpreter,
+i.e. :samp:`#!/{<path-to-venv>}/bin/python`.
+This means that the script will run with that interpreter regardless of the
+value of :envvar:`!PATH`. On Windows, "shebang" line processing is supported if
+you have the :ref:`launcher` installed. Thus, double-clicking an installed
+script in a Windows Explorer window should run it with the correct interpreter
+without the environment needing to be activated or on the :envvar:`!PATH`.
+
+When a virtual environment has been activated, the :envvar:`!VIRTUAL_ENV`
+environment variable is set to the path of the environment.
+Since explicitly activating a virtual environment is not required to use it,
+:envvar:`!VIRTUAL_ENV` cannot be relied upon to determine
+whether a virtual environment is being used.
 
 .. warning:: Because scripts installed in environments should not expect the
    environment to be activated, their shebang lines contain the absolute paths
@@ -99,6 +125,11 @@ Creating virtual environments
    environment in its new location. Otherwise, software installed into the
    environment may not work as expected.
 
+You can deactivate a virtual environment by typing ``deactivate`` in your shell.
+The exact mechanism is platform-specific and is an internal implementation
+detail (typically, a script or shell function will be used).
+
+
 .. _venv-api:
 
 API
diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc
index c2a9f52..fd8cc01 100644
--- a/Doc/using/venv-create.inc
+++ b/Doc/using/venv-create.inc
@@ -105,45 +105,3 @@ Multiple paths can be given to ``venv``, in which case an identical virtual
 environment will be created, according to the given options, at each provided
 path.
 
-Once a virtual environment has been created, it can be "activated" using a
-script in the virtual environment's binary directory. The invocation of the
-script is platform-specific (`<venv>` must be replaced by the path of the
-directory containing the virtual environment):
-
-+-------------+-----------------+-----------------------------------------+
-| Platform    | Shell           | Command to activate virtual environment |
-+=============+=================+=========================================+
-| POSIX       | bash/zsh        | $ source <venv>/bin/activate            |
-+-------------+-----------------+-----------------------------------------+
-|             | fish            | $ source <venv>/bin/activate.fish       |
-+-------------+-----------------+-----------------------------------------+
-|             | csh/tcsh        | $ source <venv>/bin/activate.csh        |
-+-------------+-----------------+-----------------------------------------+
-|             | PowerShell Core | $ <venv>/bin/Activate.ps1               |
-+-------------+-----------------+-----------------------------------------+
-| Windows     | cmd.exe         | C:\\> <venv>\\Scripts\\activate.bat     |
-+-------------+-----------------+-----------------------------------------+
-|             | PowerShell      | PS C:\\> <venv>\\Scripts\\Activate.ps1  |
-+-------------+-----------------+-----------------------------------------+
-
-When a virtual environment is active, the :envvar:`VIRTUAL_ENV` environment
-variable is set to the path of the virtual environment. This can be used to
-check if one is running inside a virtual environment.
-
-You don't specifically *need* to activate an environment; activation just
-prepends the virtual environment's binary directory to your path, so that
-"python" invokes the virtual environment's Python interpreter and you can run
-installed scripts without having to use their full path. However, all scripts
-installed in a virtual environment should be runnable without activating it,
-and run with the virtual environment's Python automatically.
-
-You can deactivate a virtual environment by typing "deactivate" in your shell.
-The exact mechanism is platform-specific and is an internal implementation
-detail (typically a script or shell function will be used).
-
-.. versionadded:: 3.4
-   ``fish`` and ``csh`` activation scripts.
-
-.. versionadded:: 3.8
-   PowerShell activation scripts installed under POSIX for PowerShell Core
-   support.