add section for definitive Model.objects documentation

[Chris Jerdonek]

I can't seem to find the model class attribute objects documented in any of the ​models reference sections. In addition, there doesn't seem to be an obvious central place where objects is documented (and in particular, a clear place where the word "objects" can internally link to). I think this place should be somewhere in the reference/API section.

Currently, the most detailed documentation of objects seems to be ​here, in the "Retrieving objects" subsection of the "Making queries" section of the introductory "Models and databases" topic section. However, objects is referred to much earlier than that, for example several times in the ​previous "Models" section.

My recommendations would be:

• add to the Models reference a definitive section about the objects class attribute, and include there a hyperlink to the introductory section about objects that I mentioned above,
• hyperlink the first mentions of objects in the models introductory sections to the definitive section, and
• in particular, hyperlink the introductory section about objects to the definitive section.

[Marc Tamlyn]

There is no need for extensive documentation of objects - it's a Manager instance so the managers doc is the reference: ​https://docs.djangoproject.com/en/dev/topics/db/managers/

Making these links more explicit might be useful though.

[Chris Jerdonek]

It doesn't need to be extensive. It might only be a few sentences, say like the ​Model.save docs, which primarily points the reader to other places.

The point is just to have Model.objects appear some place in the API docs. It can simply be a hub that links people elsewhere (e.g. the "Retrieving objects" section I mentioned above as well as the managers section you mentioned).

[nheyning]

I've been discussing this issue with Daniele Procida at the 2014 Amsterdam Django sprint.

My plan is to add a section to Model Topics page called Model attributes. The manager is the first attribute that will discussed here, with objects as its default name

[nheyning]

Reference documentation is actually missing a section about managers. To fill the gab I added some explanation to the model topic.

Because I focussed more on Model attributes in general, it didn't seem logical any more to make objects in other documentation link to this section.

[nheyning]

Pullrequest: ​https://github.com/django/django/pull/2363

[Sasha Romijn]

Patch looks fine to me :)

[Daniele Procida <daniele@…>]

In 4f7b7ef6837ee8e385785b164534fd5bc6c38e9f:

Merge pull request #2363 from nheyning/22019_add_objects_doc

Fixed #22019 -- added documentation on Model attributes

[Chris Jerdonek]

My suggestion was to add objects to the reference API. It's not intuitive if only the introductory section covers this but not the more detailed reference section. I also suggested hyperlinking some mentions of objects for this issue, for example ​here.

[Daniele Procida]

It's somewhat hard to see where in the ref/models documentations this might go.

I don't see that it warrants a section of its own, and yet there's no adequate place for it in the existing sections.

I agree that the concerns raised in the ticket are valid, and also not fully addressed, but I don't think that a very satisfactory answer will be found within given the current structure of the documentation.

Feel free to re-open the ticket though.

[Chris Jerdonek]

Reopening to address the two points in my previous comment (hyperlinking and adding to the reference section).

Yes, I agree that with the current section organization of the model reference section, it's not clear where an objects class attribute should go (all of the sections are titled somewhat specifically).

Looking at the sections more carefully, I think the most natural location is probably the ​Model instance reference section, even though strictly speaking that section is about instance attributes and methods rather than class attributes. But the introductory sentence does read, "This document describes the details of the Model API." Also, early on in the "Creating objects" subsection, the page does discuss adding a custom objects manager.

If we want to be more correct with the title, we could even consider changing the title to the more general "Model class reference."

[gtvblame]

Take this ticket to work on during DjangoCon Europe 2014 sprint.

[Tim Graham <timograham@…>]

In 5b185ecc68c04c0ee63cf44de43d831623daa263:

Fixed #22019 -- Added Model.objects reference documentation.