homepage

I can't find documentation for extra_path anywhere.. but this is the 
documentation I found by searching google ( http://
mail.python.org/pipermail/distutils-sig/2000-March/000803.html ), 
from an old USAGE.txt that sits in the CVS attic now:
extra_path:
 information about extra intervening directories to put between
 'install_lib' and 'install_sitelib', along with a .pth file to
 ensure that those directories wind up in sys.path. Can be a 1- 
or
 2-tuple, or a comma-delimited string with 1 or 2 parts. The
 1-element case is simpler: the .pth file and directory have the 
same
 name (except for ".pth"). Eg. if extra_path is "foo" or ("foo",),
 then Distutils sets 'install_site_lib' to 'install_lib' +
 "site-packages/foo", and puts foo.path in the "site-packages"
 directory; it contains just "foo". The 2-element case allows the
 .pth file and intervening directories to be named differently; 
eg.
 if 'extra_path' is ("foo","foo/bar/baz") (or "foo,foo/bar/baz"),
 then Distutils will set 'install_site_lib' to 'install_lib' +
 "site-packages/foo/bar/baz", and put "foo.pth" containing
 "foo/bar/baz" in the "site-packages" directory.

Logged In: YES 
user_id=580910
extra_path also doesn't have a command-line equivalent.

Unassign, I won't work on this.

I've attached a documentation patch for this (for py3k)

The patch has some words missing ("to put between"), but I can add them. I’m also going to include the example that was in Bob’s message, since the bit of doc in the table alone is not enough to understand clearly what this does IMO.
I’m reassigning this to distutils2. distutils only gets bug fixes, and its doc is changed only when it says something that doesn’t work. This lets us put energy on distutils2.
I’ll get to it this week-end or later.

I don't understand why distutils won't even get documentation updates.
Bob's report is about undocumented functionality that is used in real life and was the best way to install python distributions in a self-contained way before setuptools was invented.
AFAIK The "options" argument to setup is also not documented an that one is also used (both py2exe and py2app mention this feature in their documentation).

This strict freeze policy has been decided by Tarek. The less work there is on distutils’ side, the less synchronization we’ll have to do in distutils2. We do fix doc bugs, we can also fix markup or add links, but that’s it. Improving docs is for distutils2.
Note that at first I wanted to improve distutils docs even though the code was frozen, but I now agree with Tarek that it would take up a lot of time that is better spent in distutils2. (Regarding the options parameter, a Montreal-Python contributor added a test for it and a TODO note about lack of documentation. See, things get better one step at a time :)
I hope this answers your question without sounding too dictatorial. I understand your viewpoint but ultimately agree with the freeze.

I've applied the patch on distutils2. This can now be closed.

You shouldn’t have :) apiref.rst is very outdated in d2, because the setup function does not exist. The docs could be adjusted to document Distribution instead of setup, but we’re not even sure Distribution will stay.
I think I will make a compromise here and apply the patch to distutils1 doc, so that the information is found on the official docs.

Still, the extra_path argument exists and can be used, it's worth to
have it documented somewhere, especially if someone have done it.
That's also true that apiref.rst is outdated in d2, and will need a
complete reshape :)

I added the missing words and reworded a few lines in the attached patch.
That said, I find that the new doc is barely helpful; it describes what the code does, but does not explain why one would want to use it. Comments in the source suggest it’s a hack to support some corner case. This is still obscure to me after reading about it and looking at the code :(

Given the progression in issue27919, I suggest this documentation effort can be dropped, but feel free to revive the conversation if you disagree.