Thanks for the detailed review.  I’d like to work on a number of them.  I think I’ll open focused bug reports and make this one depend on them; this will let interested people see the new bugs and possibly give feedback.

> The Language Reference is way too complicated for the mainstream case.
Well, it is not a user guide, but a language reference.  Its scope is different from the library reference.

> Exactly what variants of arguments are possible, and what are their effects?
Does http://docs.python.org/dev/library/functions#__import__ help? Does http://docs.python.org/dev/library/importlib ?

> What are the interactions with package features, such as whether or not
> modules have been explicitly imported into package __init_.py?
Ah, that’s a common issue.  I’ll look into the turorial and docs for import and make a patch.

> Details of package structure have evidently changed over Python versions.
I don’t think so.

> Current docs are unclear on points such as:
> -- is __init__.py needed on subpackage directories?
Yes, it always has.  I think there was some discussion about removing them in py3k, but this was rejected.

> -- the __all__ variable: Does it act generally to limit visibility of a
> module or package's attributes, or does pertain only to the
> 'from...import *' statement?
Both.  http://docs.python.org/dev/genindex-_ leads me to http://docs.python.org/dev/reference/simple_stmts#index-44 and http://docs.python.org/dev/c-api/import#index-0  The doc is there; I however agree that the tutorial or libref could have the same info.

> Language Reference
> Grammar issue: the grammar shown for the import statement shows: [snip]
I have no inkling on that one; I’ll create another bug and ask the import experts.

> Really 'module' is not quite right here either since it's used to mean module-or-package.
A package is a type of module.
                                                                                                
> site.py:
I think I’ll focus first on my work about improving the site.rst documentation, then open another bug to synchronize the docstrings.

> Seriously misleading discussion of .pth files.  [snip]
Agreed.  I believe this section dates back to the pre-package days, where projects like PIL had a module, a .pth file and a directory with modules on sys.path.

> The docstring (or other docs) should make clear that .pth files
> are ONLY processed within site-package directories (ie: only by site.py)
I’ll add a section about the “site directories” in the docs.  They’re defined in site.py or by users calling site.addsitedir.

> In addsitepackages(), the library directory for Windows (the else clause)
> is shown as lower-case 'lib' instead of 'Lib'.
I don’t see any else clause in the 2.7 or 3.3 code.  Otherwise you’re right.


> Tutorial [snip]
All valid points.


> Standard Library Reference
> site
> This page may simply be importing the docstring from site.py?
> In any case it repeats the ommissions and errors noted above for site.py.
We don’t use docstring extraction in CPython.  Code and docs are updated alongside, or like here, get oudated in parallel.

> sys
> Could helpfully point to a discussion of the typical items to
> be found in sys.path under normal circumstances
Hm, this would be very platform-specific.  What use cases would that help?

> pkgutil
I’ll have to read again the code and PEPs to comment on that one.

> 'Installing Python Modules' document
> "Windows has no concept of a user’s home directory, " and so on.
The author probably meant that there was no $HOME environment variable, ~ shortcut and all that.  Even though Windows assigns a directory for each user, it’s not quite a home dir, but the parent of a settings dir, a documents dir, etc.  (Just like on Mac OS X, there is a UNIX-style home dir, but the tools present another directory for users’ documents, IIRC.)

> For Windows suggests 'prefix' (default: C:\Python) as an installation directory.
> This is indeed one of the possible 'site-package' directories, but surely it is
> deprecated in favor of C:\Python\Lib\site-packages, which this section does not mention.
Don’t confuse the prefix and the install dir.  The directory for Python modules is computed as prefix + Lib/site-packages.

> Does not mention user-specific site-package directories.
That’s #10745.  I documented it in http://docs.python.org/dev/packaging/commandref#install-dist but it’s not done for distutils docs yet.

> 'Modifying Python's Search Path' [snip]
> (a) .pth files are only processed in site-package directories.
Yes.  I’ll probably link to the site docs after we write out a clean section on .pth files.  There are other parts of the distutils docs that duplicate information found in docs.python.org/dev/using, for example; I’ll remove them from the packaging (distutils2) docs.

> (b) Clarifying an additional point of confusion [...]
We don’t over-explain every implication in the docs; see http://docs.python.org/dev/documenting/style.html#affirmative-tone

> PEP 302 New Import Hooks
This would be a valid point to raise on python-dev.

That was my initial feeback; I think I’ve covered all of your points.  Some time next week I’ll open the focused bugs and start on patches.