classification
Title: Better document user site-packages in site module doc
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: christian.heimes, dabrahams, docs@python, eric.araujo, maximd, python-dev, r.david.murray, tarek
Priority: normal Keywords: needs review, patch

Created on 2010-05-04 23:51 by dabrahams, last changed 2012-05-09 15:45 by maximd. This issue is now closed.

Files
File name Uploaded Description Edit
pep370-doc.diff eric.araujo, 2011-06-27 15:44
Messages (11)
msg104985 - (view) Author: Dave Abrahams (dabrahams) Date: 2010-05-04 23:51
http://docs.python.org/library/site.html#module-site mentions two variables that don't appear in my Python 2.6.5 installation's site module:

PYTHONNOUSERSITE
New in version 2.6.

PYTHONUSERBASE
New in version 2.6.
msg104995 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-05-05 01:40
These are references to environment variables.  The markup marks them as such, but this does not translate into HTML in a visible way.  Without a text description it is also left to guesswork as to how they function. The 2.7 docs are even more confusing, adding 'getuserbase'.  Adding Tarek as nosy since he has been updating this doc most recently.
msg105004 - (view) Author: Tarek Ziadé (tarek) * (Python committer) Date: 2010-05-05 08:20
site definitely needs more documentation about the per-user site-packages. 

We need to add a section about that. I am adding Christian to the nosy list, since he added those feature. I can work on a section sometimes next week and propose a patch here btw.
msg132154 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-25 21:07
Tarek, if you don’t have time for a patch, I am interested in making one.
msg137989 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-09 15:29
I have started to work on this; I’ll have one or two patches ready in a few weeks.
msg141831 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-08-09 16:11
New changeset 74179a79d673 by Éric Araujo in branch '3.2':
Improve documentation for PEP 370 support in site module (#8617).
http://hg.python.org/cpython/rev/74179a79d673

New changeset d354802a637d by Éric Araujo in branch 'default':
Merge doc changes from 3.2 (#8617, #10745).
http://hg.python.org/cpython/rev/d354802a637d
msg142432 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-08-19 12:28
New changeset b3f72b6450f1 by Éric Araujo in branch '2.7':
Improve documentation for PEP 370 support in site module (#8617).
http://hg.python.org/cpython/rev/b3f72b6450f1
msg160299 - (view) Author: Maxim Doucet (maximd) Date: 2012-05-09 15:38
Shouldn't there be an update of the 2.6 documentation too?

After your patch, the 2.7 reflects the existence of the "--user" option (see http://docs.python.org/release/2.7.3/install/index.html#alternate-installation-the-user-scheme) but not the 2.6 documentation (http://docs.python.org/release/2.6.8/install/index.html#alternate-installation).

In my personal experience, I used the "--home" option with python 2.6 to mimic what "--user" does and it took me 2 weeks to, by chance, stumble upon http://www.python.org/dev/peps/pep-0370/ which informed me that the "--user" option was originally available for python 2.6. If it had been on the 2.6 documentation, it would have been easier and more coherent IMHO.
msg160300 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-05-09 15:40
2.6 only gets security fixes now.
msg160302 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-05-09 15:44
BTW it appears that many people use the most recent 2.7 documentation even if they are using 2.6, because the doc is better and there are notes which tell you if something was changed or added in 2.7.  For PEP 370 there are notes in the doc of the site module and the environment variables but I forgot to add one to the distutils doc; I will do that.
msg160303 - (view) Author: Maxim Doucet (maximd) Date: 2012-05-09 15:45
Fair enough, thank you for the information. As a side note, my original question was in fact more suited for issue10745
History
Date User Action Args
2012-05-09 15:45:50maximdsetmessages: + msg160303
2012-05-09 15:44:05eric.araujosetmessages: + msg160302
2012-05-09 15:40:17eric.araujosetmessages: + msg160300
2012-05-09 15:38:47maximdsetnosy: + maximd
messages: + msg160299
2011-08-19 12:35:36eric.araujosetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2011-08-19 12:28:06python-devsetmessages: + msg142432
2011-08-09 16:11:14python-devsetnosy: + python-dev
messages: + msg141831
2011-06-27 15:45:08eric.araujosetkeywords: + needs review
stage: needs patch -> patch review
2011-06-27 15:44:30eric.araujosetfiles: + pep370-doc.diff
keywords: + patch
2011-06-10 17:46:18eric.araujolinkissue11553 dependencies
2011-06-09 15:29:54eric.araujosetassignee: docs@python -> eric.araujo
messages: + msg137989
versions: - Python 3.1
2011-03-25 21:07:52eric.araujosetnosy: + eric.araujo
title: Non-existent variables documented -> Better document user site-packages in site module doc
messages: + msg132154

versions: + Python 3.3, - Python 2.6
2010-05-05 08:20:01tareksetnosy: + christian.heimes
messages: + msg105004
2010-05-05 01:40:27r.david.murraysetversions: + Python 3.1, Python 2.7, Python 3.2
nosy: + tarek, r.david.murray

messages: + msg104995

type: behavior
stage: needs patch
2010-05-04 23:51:19dabrahamscreate