Improve documentation for PEP 370 support in site module (#8617).

site.USER_BASE and site.USER_SITE are now fully documented.  PEP 370 is
outdated with respects to the Mac framework situation, but the code in
sysconfig and the example in the 3.2 What’s New document helped me find
the right values to document for Mac OS X.

The command-line interface of the site module, partly documented in the
3.2 What’s New, is fully described in the module docs.

The purpose of the usercustomize module is explained in the site docs,
with a gentle introduction in the tutorial (right after the section that
talks about PYTHONSTARTUP; a comment mentions it should be moved from
the tutorial to another file, but that will be another bug).

Various markup and wording improvements were made along the way in the
site module docs.  Duplicate and incomplete declarations of environment
variables have also been removed (the original bug report was actually
about these entries :).  The site module docs are still a bit messy;
I’ll see about improving them for #11553.

All these sections are copiously interlinked and findable from the doc
indexes.

2 files changed, 27 insertions, 4 deletions

diff --git a/Doc/tutorial/interactive.rst b/Doc/tutorial/interactive.rst
index 5faaf96..36acb06 100644
--- a/Doc/tutorial/interactive.rst
+++ b/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
diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst
index 29afc50..417eeee 100644
--- a/Doc/tutorial/interpreter.rst
+++ b/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.
-