Create a reference of public Manager methods

[Ramiro Morales]

In the "Natural keys" documentation, an example of a custom manager's get_by_natural_key() method calls self.get() (​https://docs.djangoproject.com/en/dev/topics/serialization/#deserialization-of-natural-keys) but we don't document which the available methods are.

We should expand the reference-type documentation of manager, even if only to note some of them simply proxy to the respective QuerySet methods:

​https://github.com/django/django/blob/master/django/db/models/manager.py#L111

[Ramiro Morales]

In master there are news in this front #20625 and [31fadc120213284da76801cc7bc56e9f32d7281b]

[loic84]

IMO ref/models/managers.txt should take over a fair chunk from the topic guide topics/db/managers.txt.

The reference would include the stock Manager methods and attributes and everything one needs to know about using managers (either the stock Manager or subclasses like CurrentSiteManager). I suggest the following:

• A section about QuerySet methods. I'm not sure if we should list them all or just mention that all QuerySet public methods but delete() are available from Manager.
• Reference the from_queryset(), get_queryset(), raw() methods and the model, db, use_for_related_fields attributes.
• Get "Manager names" from the topic guide.
• Split "Modifying initial Manager QuerySets" from the topic guide into two parts, one that goes within the get_queryset() definition and the other one into a new section "Using multiple managers on the same model".
• Get "Custom managers and model inheritance" from the topic guide.

The topic guide would then stick to the ins and outs of creating a custom Manager:

• "Calling custom QuerySet methods from the Manager"
• "Creating Manager with QuerySet methods" (linked from Manager.from_queryset and QuerySet.as_manager)
• A new section about creating a Manager by compositing QuerySets like the example in ​https://github.com/django/django/pull/1328#issuecomment-21439470
• "Implementation concerns"
• "Controlling automatic Manager types" (Linked from Manager.use_for_related_fields)
• "Writing correct Managers for use in automatic Manager instances" (Linked from Manager.use_for_related_fields)

While we are at it, we should remove the Male/Female distinction from the examples.

Feedback welcome.

[loic84]

While addressing this, we should account for @ramiro's ​on the PR. Probably by removing the custom __init__ altogether.