QuerySet reference enhancement + reST cleanup

[Gabriel Hurley]

The reST issues aren't really the subject of this ticket (normally I'd just commit those).

However, also in this patch is a chunk that fleshes out the QuerySet class definition. In particular it adds:

1. The query and using kwargs to the signature.
2. The ordered and db properties (which are marked as "public" in the source, and are mentioned in the docs elsewhere).

While using should certainly be documented as a kwarg, sql.Query isn't a public API so I'm not sure if documenting query is appropriate.

However, the docs say "here's the formal declaration of a QuerySet" so I'm inclined to say that the declaration should be complete.

I just wanted to get a quick nod from someone else on this one.

[Russell Keith-Magee]

sql.Query isn't public API, but the existence of the argument isn't a secret. I'm happy for it to be documented with a Jedi-mind trick: "This argument exists so that specialist query subclasses (such as GeoDjango) can reconstruct internal query state. The value itself is an opaque representation of query state. If you need to ask, you don't need to use it".

Otherwise, I'm happy with the patch as provided.

[Gabriel Hurley]

In [15776]:

Fixed #15558 -- Improved QuerySet reference docs and cleaned up numerous reST/sphinx problems.