DOC: clarify and expand documentation about PYTHONUSERBASE and PYTHONNOUSERSITE (#144637)

Author: tacaswell

Doc/library/site.rst

@@ -64,7 +64,8 @@ When running under a :ref:`virtual environment <sys-path-init-virtual-environmen
 the ``pyvenv.cfg`` file in :data:`sys.prefix` is checked for site-specific
 configurations. If the ``include-system-site-packages`` key exists and is set to
 ``true`` (case-insensitive), the system-level prefixes will be searched for
-site-packages, otherwise they won't.
+site-packages, otherwise they won't.  If the system-level prefixes are not searched then
+the user site prefixes are also implicitly not searched for site-packages.
 
 .. index::
    single: # (hash); comment

Doc/library/sys_path_init.rst

@@ -57,15 +57,19 @@ otherwise they are set to the same value as :data:`sys.base_prefix` and
 :data:`sys.base_exec_prefix`, respectively.
 This is used by :ref:`sys-path-init-virtual-environments`.
 
-Finally, the :mod:`site` module is processed and :file:`site-packages` directories
-are added to the module search path. A common way to customize the search path is
-to create :mod:`sitecustomize` or :mod:`usercustomize` modules as described in
-the :mod:`site` module documentation.
+Finally, the :mod:`site` module is processed and :file:`site-packages`
+directories are added to the module search path.  The :envvar:`PYTHONUSERBASE`
+environment variable controls where is searched for user site-packages and the
+:envvar:`PYTHONNOUSERSITE` environment variable prevents searching for user
+site-packages all together.  A common way to customize the search path is to
+create :mod:`sitecustomize` or :mod:`usercustomize` modules as described in the
+:mod:`site` module documentation.
 
 .. note::
 
-   Certain command line options may further affect path calculations.
-   See :option:`-E`, :option:`-I`, :option:`-s` and :option:`-S` for further details.
+   The command line options :option:`-E`, :option:`-P`, :option:`-I`,
+   :option:`-S` and :option:`-s` further affect path calculations, see their
+   documentation for details.
 
 .. versionchanged:: 3.14
 
@@ -96,11 +100,10 @@ Please refer to :mod:`site`'s
 
 .. note::
 
-   There are other ways how "virtual environments" could be implemented, this
-   documentation refers implementations based on the ``pyvenv.cfg`` mechanism,
-   such as :mod:`venv`. Most virtual environment implementations follow the
-   model set by :mod:`venv`, but there may be exotic implementations that
-   diverge from it.
+   There are other ways "virtual environments" could be implemented.
+   This documentation refers to implementations based on the ``pyvenv.cfg``
+   mechanism, such as :mod:`venv`, that many virtual environment implementations
+   follow.
 
 _pth files
 ----------

Doc/using/cmdline.rst

@@ -949,8 +949,9 @@ conflict.
 
 .. envvar:: PYTHONNOUSERSITE
 
-   If this is set, Python won't add the :data:`user site-packages directory
-   <site.USER_SITE>` to :data:`sys.path`.
+   This is equivalent to the :option:`-s` option.  If this is set, Python won't
+   add the :data:`user site-packages directory <site.USER_SITE>` to
+   :data:`sys.path`.
 
    .. seealso::
 
@@ -964,6 +965,9 @@ conflict.
    and :ref:`installation paths <sysconfig-user-scheme>` for
    ``python -m pip install --user``.
 
+   To disable the user site-packages, see :envvar:`PYTHONNOUSERSITE` or the :option:`-s`
+   option.
+
    .. seealso::
 
       :pep:`370` -- Per user site-packages directory

Lib/site.py

@@ -18,9 +18,11 @@
 it is also checked for site-packages (sys.base_prefix and
 sys.base_exec_prefix will always be the "real" prefixes of the Python
 installation). If "pyvenv.cfg" (a bootstrap configuration file) contains
-the key "include-system-site-packages" set to anything other than "false"
+the key "include-system-site-packages" is set to  "true"
 (case-insensitive), the system-level prefixes will still also be
-searched for site-packages; otherwise they won't.
+searched for site-packages; otherwise they won't.  If the system-level
+prefixes are not included then the user site prefixes are also implicitly
+not searched for site-packages.
 
 All of the resulting site-specific directories, if they exist, are
 appended to sys.path, and also inspected for path configuration