Why is the Python documentation terrible in this respect? Python comes with a language reference[1], that has most of the components you ask for (one of the components is in a document that's called something other than the language reference, but that's because it's the stdlib, not the language itself... it's certainly the same style of document, not a tutorial!):
1. Syntax (sections 5, 6, 7 and I guess also 9 if you want the full grammar)
2. Whitespace (section 2.1)
3. Operation priority (section 5.15 has it explicitly, the rest of the sections also clarify)
5. All parameters? Documentation should already have these.
6. Callback parameters: I can't think of any callbacks in the stdlib offhand, but the ones that do exist are methods you implement, and all the ones I can think of are documented
7. Default values and their meanings are pretty much always documented
8. I don't know what flag values are, but if they're just parameters they fall under (5)
9. Return values and exceptions should always be documented
10. There are plenty of cases where some input parameters causing undefined behavior is documented; some maybe not (for example I don't think urlparse.urlsplit documents what happens when you give it a scheme it doesn't know about), but MOSTLY it's documented.
A while back I was trying to figure out something in Python. Python isn't hard, and I can read it (since its practically like reading Ruby) and get by writing it here and there when needed.
So... I'm trying to use some Python library (whatever your equivalent of a Gem is). I spent a few hours ripping out my hair trying to find good documentation for how to install and manage Python libraries. There didn't appear to be the equivalent of RubyGems or Bundler. There did seem to be 2-3 different ways of managing them (eggs?), but just getting those programs working on my local system wasn't liking me either. Googling for "Using Python libraries" didn't return much useful- nor did "Installing Python Libraries".
I'm still unclear what the standard method for managing these is. When I checkout a Ruby thing, I just type 'bundle install' and all is fine then.
Yes, the technical docs were fine- but the baseline "how do I get this damn stuff, working!?!?!" wasn't.
There are various methods for installing 3rd party python libraries from PyPI [1], including easy_install, pip, or just extracting the tarball from PyPI and running `python setup install`.
Edit: There's also the official documentation page called "Installing Python Modules" which covers the last of those three methods: http://docs.python.org/install/index.html
I think this might be an issue with what you're used to. We have things like rvm, gems and bundler: look at virtualenv, distutils/setuptools... The equivalent of a Gemfile is a requirements file, pip knows how to install these (pip install -r FILE).
If you ask me to do the same in Ruby, I'd probably be lost too.
1. Syntax (sections 5, 6, 7 and I guess also 9 if you want the full grammar)
2. Whitespace (section 2.1)
3. Operation priority (section 5.15 has it explicitly, the rest of the sections also clarify)
4. All functions, types, classes... both globals and stdlib modules are documented in http://docs.python.org/library/index.html#library-index
5. All parameters? Documentation should already have these.
6. Callback parameters: I can't think of any callbacks in the stdlib offhand, but the ones that do exist are methods you implement, and all the ones I can think of are documented
7. Default values and their meanings are pretty much always documented
8. I don't know what flag values are, but if they're just parameters they fall under (5)
9. Return values and exceptions should always be documented
10. There are plenty of cases where some input parameters causing undefined behavior is documented; some maybe not (for example I don't think urlparse.urlsplit documents what happens when you give it a scheme it doesn't know about), but MOSTLY it's documented.
[1] http://docs.python.org/reference/