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.
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 16a753c..bbc654e 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -229,7 +229,8 @@
.. 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::
@@ -468,7 +469,8 @@
.. 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::
@@ -477,7 +479,9 @@
.. 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 Distutils installation paths for ``python setup.py install --user``.
.. seealso::