Merge doc changes from 3.2 (#8617, #10745).

In the install and library docs, I changed the text to refer to
packaging instead of distutils.  I also checked that the documented
paths correctly reflect what’s really defined in sysconfig; the main
difference with paths defined in distutils.install is that include
directories don’t end with the distribution name anymore (i.e. distutils
uses include/python3.3/spam, sysconfig include/python3.3), I have no
idea why.

Doc/library/site.rst

@@ -2,22 +2,24 @@
 ================================================
 
 .. module:: site
-   :synopsis: A standard way to reference site-specific modules.
+   :synopsis: Module responsible for site-specific configuration.
 
 **Source code:** :source:`Lib/site.py`
 
 --------------
 
+.. highlightlang:: none
+
 **This module is automatically imported during initialization.** The automatic
 import can be suppressed using the interpreter's :option:`-S` option.
 
 .. index:: triple: module; search; path
 
-Importing this module will append site-specific paths to the module search
-path, unless :option:`-S` was used.  In that case, this module can be safely
-imported with no automatic modifications to the module search path.  To
-explicitly trigger the usual site-specific additions, call the
-:func:`site.main` function.
+Importing this module will append site-specific paths to the module search path
+and add a few builtins, unless :option:`-S` was used.  In that case, this module
+can be safely imported with no automatic modifications to the module search path
+or additions to the builtins.  To explicitly trigger the usual site-specific
+additions, call the :func:`site.main` function.
 
 .. versionchanged:: 3.3
    Importing the module used to trigger paths manipulation even when using
@@ -36,11 +38,11 @@ Unix and Macintosh).  For each of the distinct head-tail combinations, it sees
 if it refers to an existing directory, and if so, adds it to ``sys.path`` and
 also inspects the newly added path for configuration files.
 
-A path configuration file is a file whose name has the form :file:`package.pth`
+A path configuration file is a file whose name has the form :file:`{name}.pth`
 and exists in one of the four directories mentioned above; its contents are
 additional items (one per line) to be added to ``sys.path``.  Non-existing items
-are never added to ``sys.path``, but no check is made that the item refers to a
-directory (rather than a file).  No item is added to ``sys.path`` more than
+are never added to ``sys.path``, and no check is made that the item refers to a
+directory rather than a file.  No item is added to ``sys.path`` more than
 once.  Blank lines and lines beginning with ``#`` are skipped.  Lines starting
 with ``import`` (followed by space or tab) are executed.
 
@@ -50,8 +52,7 @@ with ``import`` (followed by space or tab) are executed.
 
 For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to
 :file:`/usr/local`.  The Python X.Y library is then installed in
-:file:`/usr/local/lib/python{X.Y}` (where only the first three characters of
-``sys.version`` are used to form the installation path name).  Suppose this has
+:file:`/usr/local/lib/python{X.Y}`.  Suppose this has
 a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three
 subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path
 configuration files, :file:`foo.pth` and :file:`bar.pth`.  Assume
@@ -84,42 +85,59 @@ not mentioned in either path configuration file.
 
 After these path manipulations, an attempt is made to import a module named
 :mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
-If this import fails with an :exc:`ImportError` exception, it is silently
-ignored.
+It is typically created by a system administrator in the site-packages
+directory.  If this import fails with an :exc:`ImportError` exception, it is
+silently ignored.
 
-.. index:: module: sitecustomize
+.. index:: module: usercustomize
+
+After this, an attempt is made to import a module named :mod:`usercustomize`,
+which can perform arbitrary user-specific customizations, if
+:data:`ENABLE_USER_SITE` is true.  This file is intended to be created in the
+user site-packages directory (see below), which is part of ``sys.path`` unless
+disabled by :option:`-s`.  An :exc:`ImportError` will be silently ignored.
 
 Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
 empty, and the path manipulations are skipped; however the import of
-:mod:`sitecustomize` is still attempted.
+:mod:`sitecustomize` and :mod:`usercustomize` is still attempted.
 
 
 .. data:: PREFIXES
 
-   A list of prefixes for site package directories
+   A list of prefixes for site-packages directories.
 
 
 .. data:: ENABLE_USER_SITE
 
-   Flag showing the status of the user site directory. True means the
-   user site directory is enabled and added to sys.path. When the flag
-   is None the user site directory is disabled for security reasons.
+   Flag showing the status of the user site-packages directory.  ``True`` means
+   that it is enabled and was added to ``sys.path``.  ``False`` means that it
+   was disabled by user request (with :option:`-s` or
+   :envvar:`PYTHONNOUSERSITE`).  ``None`` means it was disabled for security
+   reasons (mismatch between user or group id and effective id) or by an
+   administrator.
 
 
 .. data:: USER_SITE
 
-   Path to the user site directory for the current Python version or None
+   Path to the user site-packages for the running Python.  Can be ``None`` if
+   :func:`getusersitepackages` hasn't been called yet.  Default value is
+   :file:`~/.local/lib/python{X.Y}/site-packages` for UNIX and non-framework Mac
+   OS X builds, :file:`~/Library/Python/{X.Y}/lib/python/site-packages` for Mac
+   framework builds, and :file:`{%APPDATA%}\\Python\\Python{XY}\\site-packages`
+   on Windows.  This directory is a site directory, which means that
+   :file:`.pth` files in it will be processed.
 
 
 .. data:: USER_BASE
 
-   Path to the base directory for user site directories
-
-
-.. envvar:: PYTHONNOUSERSITE
-
-
-.. envvar:: PYTHONUSERBASE
+   Path to the base directory for the user site-packages.  Can be ``None`` if
+   :func:`getuserbase` hasn't been called yet.  Default value is
+   :file:`~/.local` for UNIX and Mac OS X non-framework builds,
+   :file:`~/Library/Python/{X.Y}` for Mac framework builds, and
+   :file:`{%APPDATA%}\\Python` for Windows.  This value is used by Packaging to
+   compute the installation directories for scripts, data files, Python modules,
+   etc. for the :ref:`user installation scheme <packaging-alt-install-user>`.
+   See also :envvar:`PYTHONUSERBASE`.
 
 
 .. function:: main()
@@ -135,34 +153,67 @@ empty, and the path manipulations are skipped; however the import of
 
 .. function:: addsitedir(sitedir, known_paths=None)
 
-   Adds a directory to sys.path and processes its pth files.
+   Add a directory to sys.path and process its :file:`.pth` files.  Typically
+   used in :mod:`sitecustomize` or :mod:`usercustomize` (see above).
+
 
 .. function:: getsitepackages()
 
-   Returns a list containing all global site-packages directories
-   (and possibly site-python).
+   Return a list containing all global site-packages directories (and possibly
+   site-python).
 
    .. versionadded:: 3.2
 
-.. function:: getuserbase()
 
-   Returns the "user base" directory path.
+.. function:: getuserbase()
 
-   The "user base" directory can be used to store data. If the global
-   variable ``USER_BASE`` is not initialized yet, this function will also set
-   it.
+   Return the path of the user base directory, :data:`USER_BASE`.  If it is not
+   initialized yet, this function will also set it, respecting
+   :envvar:`PYTHONUSERBASE`.
 
    .. versionadded:: 3.2
 
-.. function:: getusersitepackages()
 
-   Returns the user-specific site-packages directory path.
+.. function:: getusersitepackages()
 
-   If the global variable ``USER_SITE`` is not initialized yet, this
-   function will also set it.
+   Return the path of the user-specific site-packages directory,
+   :data:`USER_SITE`.  If it is not initialized yet, this function will also set
+   it, respecting :envvar:`PYTHONNOUSERSITE` and :data:`USER_BASE`.
 
    .. versionadded:: 3.2
 
-.. XXX Update documentation
-.. XXX document python -m site --user-base --user-site
 
+The :mod:`site` module also provides a way to get the user directories from the
+command line:
+
+.. code-block:: sh
+
+   $ python3 -m site --user-site
+   /home/user/.local/lib/python3.3/site-packages
+
+.. program:: site
+
+If it is called without arguments, it will print the contents of
+:data:`sys.path` on the standard output, followed by the value of
+:data:`USER_BASE` and whether the directory exists, then the same thing for
+:data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`.
+
+.. cmdoption:: --user-base
+
+   Print the path to the user base directory.
+
+.. cmdoption:: --user-site
+
+   Print the path to the user site-packages directory.
+
+If both options are given, user base and user site will be printed (always in
+this order), separated by :data:`os.pathsep`.
+
+If any option is given, the script will exit with one of these values: ``O`` if
+the user site-packages directory is enabled, ``1`` if it was disabled by the
+user, ``2`` if it is disabled for security reasons or by an administrator, and a
+value greater than 2 if there is an error.
+
+.. seealso::
+
+   :pep:`370` -- Per user site-packages directory

Doc/packaging/commandref.rst

@@ -12,6 +12,12 @@ their options.
    description.  Use pysetup run <command> --help to get help about the options
    of one command.
 
+.. XXX sections from this document should be merged with other docs (e.g. check
+   and upload with uploading.rst, install_* with install/install.rst, etc.);
+   there is no value in partially duplicating information.  this file could
+   however serve as an index, i.e. just a list of all commands with links to
+   every section that describes options or usage
+
 
 Preparing distributions
 =======================
@@ -310,13 +316,8 @@ the target system.
 -----------------------
 
 Install a distribution, delegating to the other :command:`install_*` commands to
-do the work.
-
-.. program:: packaging install_dist
-
-.. cmdoption:: --user
-
-   Install in user site-packages directory (see :PEP:`370`).
+do the work.  See :ref:`packaging-how-install-works` for complete usage
+instructions.
 
 
 :command:`install_data`

Doc/tutorial/interactive.rst

@@ -156,17 +156,18 @@ symbol table.  A command to check (or even suggest) matching parentheses,
 quotes, etc., would also be useful.
 
 One alternative enhanced interactive interpreter that has been around for quite
-some time is `IPython`_, which features tab completion, object exploration and
+some time is IPython_, which features tab completion, object exploration and
 advanced history management.  It can also be thoroughly customized and embedded
 into other applications.  Another similar enhanced interactive environment is
-`bpython`_.
+bpython_.
 
 
 .. rubric:: Footnotes
 
 .. [#] Python will execute the contents of a file identified by the
    :envvar:`PYTHONSTARTUP` environment variable when you start an interactive
-   interpreter.
+   interpreter.  To customize Python even for non-interactive mode, see
+   :ref:`tut-customize`.
 
 
 .. _GNU Readline: http://tiswww.case.edu/php/chet/readline/rltop.html

Doc/tutorial/interpreter.rst

@@ -236,6 +236,29 @@ in the script::
        exec(open(filename).read())
 
 
+.. _tut-customize:
+
+The Customization Modules
+-------------------------
+
+Python provides two hooks to let you customize it: :mod:`sitecustomize` and
+:mod:`usercustomize`.  To see how it works, you need first to find the location
+of your user site-packages directory.  Start Python and run this code:
+
+   >>> import site
+   >>> site.getusersitepackages()
+   '/home/user/.local/lib/python3.2/site-packages'
+
+Now you can create a file named :file:`usercustomize.py` in that directory and
+put anything you want in it.  It will affect every invocation of Python, unless
+it is started with the :option:`-s` option to disable the automatic import.
+
+:mod:`sitecustomize` works in the same way, but is typically created by an
+administrator of the computer in the global site-packages directory, and is
+imported before :mod:`usercustomize`.  See the documentation of the :mod:`site`
+module for more details.
+
+
 .. rubric:: Footnotes
 
 .. [#] On Unix, the Python 3.x interpreter is by default not installed with the
@@ -243,4 +266,3 @@ in the script::
    simultaneously installed Python 2.x executable.
 
 .. [#] A problem with the GNU Readline package may prevent this.
-

Doc/using/cmdline.rst

@@ -229,7 +229,8 @@ Miscellaneous options
 
 .. cmdoption:: -s
 
-   Don't add user site directory to sys.path
+   Don't add the :data:`user site-packages directory <site.USER_SITE>` to
+   :data:`sys.path`.
 
    .. seealso::
 
@@ -470,7 +471,8 @@ These environment variables influence Python's behavior.
 
 .. envvar:: PYTHONNOUSERSITE
 
-   If this is set, Python won't add the user site directory to sys.path
+   If this is set, Python won't add the :data:`user site-packages directory
+   <site.USER_SITE>` to :data:`sys.path`.
 
    .. seealso::
 
@@ -479,7 +481,10 @@ These environment variables influence Python's behavior.
 
 .. envvar:: PYTHONUSERBASE
 
-   Sets the base directory for the user site directory
+   Defines the :data:`user base directory <site.USER_BASE>`, which is used to
+   compute the path of the :data:`user site-packages directory <site.USER_SITE>`
+   and :ref:`Packaging installation paths <packaging-alt-install-user>` for
+   ``pysetup run install_dist --user``.
 
    .. seealso::