[Django] #22019: add section for definitive Models.objects documentation
Django
--------------------------------------+----------------------------
Reporter: cjerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Severity: Normal | Keywords: models,objects
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+----------------------------
I can't seem to find the model class attribute `objects` documented in any
of the [https://docs.djangoproject.com/en/dev/ref/models/ 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
[https://docs.djangoproject.com/en/dev/topics/db/queries/#retrieving-
objects 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
[https://docs.djangoproject.com/en/dev/topics/db/models/ 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/22019>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Reporter: cjerdonek | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution:
Severity: Normal | Triage Stage:
Keywords: models,objects | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by cjerdonek):
* cc: chris.jerdonek@… (added)
* needs_docs: => 0
* needs_better_patch: => 0
* needs_tests: => 0
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:1>
Django
-------------------------------------+-------------------------------------
Reporter: cjerdonek | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution:
Severity: Normal | Triage Stage:
Keywords: models,objects | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by mjtamlyn):
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:2>
Django
-------------------------------------+-------------------------------------
Reporter: cjerdonek | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution:
Severity: Normal | Triage Stage:
Keywords: models,objects | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by cjerdonek):
It doesn't need to be extensive. It might only be a few sentences, say
like the
[https://docs.djangoproject.com/en/dev/ref/models/instances/#django.db.models.Model.save
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).
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:3>
Django
--------------------------------------+------------------------------------
Reporter: cjerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Keywords: models,objects | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Changes (by timo):
* easy: 0 => 1
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:4>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.6
Severity: Normal | Resolution:
Keywords: models,objects | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* owner: nobody => nheyning
* status: new => assigned
Comment:
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
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:5>
Django
--------------------------------------+------------------------------------
Reporter: cjerdonek | Owner: nheyning
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: models,objects | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:6>
Django
--------------------------------------+------------------------------------
Reporter: cjerdonek | Owner: nheyning
Component: Documentation | Version: 1.6
Severity: Normal | Resolution: fixed
Keywords: models,objects | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
Pullrequest: https://github.com/django/django/pull/2363
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:7>
Django
-------------------------------------+-------------------------------------
Reporter: cjerdonek | Owner: nheyning
Type: | Status: new
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution:
Keywords: models nlsprint14 | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by erikr):
* status: closed => new
* cc: eromijn@… (added)
* keywords: models,objects => models nlsprint14
* has_patch: 0 => 1
* resolution: fixed =>
* stage: Accepted => Ready for checkin
Comment:
Patch looks fine to me :)
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: cjerdonek | Owner: nheyning
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Ready for
Keywords: models nlsprint14 | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: new => closed
* resolution: => fixed
Comment:
In [changeset:"4f7b7ef6837ee8e385785b164534fd5bc6c38e9f"]:
{{{
#!CommitTicketReference repository=""
revision="4f7b7ef6837ee8e385785b164534fd5bc6c38e9f"
Merge pull request #2363 from nheyning/22019_add_objects_doc
Fixed #22019 -- added documentation on Model attributes
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:9>
Django
-------------------------------------+-------------------------------------
Reporter: cjerdonek | Owner: nheyning
Type: | Status: closed
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Ready for
Keywords: models nlsprint14 | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by cjerdonek):
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
[https://docs.djangoproject.com/en/dev/topics/db/queries/#retrieving-
objects here].
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:10>
Django
-------------------------------------+-------------------------------------
Reporter: cjerdonek | Owner: nheyning
Type: | Status: closed
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Ready for
Keywords: models nlsprint14 | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by EvilDMP):
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:11>
Django
-------------------------------------+-------------------------------------
Reporter: cjerdonek | Owner: nheyning
Type: | Status: closed
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Ready for
Keywords: models nlsprint14 | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by cjerdonek):
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
[https://docs.djangoproject.com/en/dev/ref/models/instances/ 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."
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:12>
Django
--------------------------------------+------------------------------------
Reporter: cjerdonek | Owner: nheyning
Component: Documentation | Version: 1.6
Keywords: models nlsprint14 | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by cjerdonek):
* status: closed => new
* resolution: fixed =>
* stage: Ready for checkin => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:13>
Django
--------------------------------------+------------------------------------
Reporter: cjerdonek | Owner: nheyning
Component: Documentation | Version: 1.6
Keywords: models nlsprint14 | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* has_patch: 1 => 0
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:14>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution:
Keywords: models nlsprint14 | Needs documentation: 0
Has patch: 0 | Patch needs improvement: 0
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Changes (by gtvblame):
* owner: nheyning => anonymous
* status: new => assigned
Comment:
Take this ticket to work on during DjangoCon Europe 2014 sprint.
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:15>
Django
-------------------------------------+-------------------------------------
Reporter: cjerdonek | Owner: anonymous
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Accepted
Keywords: models nlsprint14 | Needs documentation: 0
Has patch: 0 | Patch needs improvement: 0
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"5b185ecc68c04c0ee63cf44de43d831623daa263"]:
{{{
#!CommitTicketReference repository=""
revision="5b185ecc68c04c0ee63cf44de43d831623daa263"
Fixed #22019 -- Added Model.objects reference documentation.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/22019#comment:16>