Code

Opened 5 years ago

Closed 3 years ago

Last modified 3 years ago

#11864 closed (fixed)

Relationship backreference documentation is hard to find

Reported by: anonymous Owned by: dwillis
Component: Documentation Version: 1.1
Severity: Keywords: relationships foreigkey
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

I would expect that documentation on backreferences in relationships would be documented under Model API documentation, but it takes a few clicks from there to see how it works.

http://docs.djangoproject.com/en/dev/topics/db/models/#relationships

will, if the seeker of wisdom is pretty sharp or diligent, lead to one link labeled "the model field reference", which if followed, takes one to

http://docs.djangoproject.com/en/dev/ref/models/fields/#foreign-key-arguments

From there, one follows a link labeled "related objects documentation" that points at

http://docs.djangoproject.com/en/dev/topics/db/queries/#backwards-related-objects

which is where the fact that if I have a one-many relationship between Foo and Bar, where the Bar model class has a ForeignKey reference to Foo, then instances of the Foo
class will have an attribute named "bar_set" whose value is a relationship manager (and that fact's documented on a page about queries).

All this means that the highly useful and important fact about how Django manages the relationship from Foos to Bars is two clicks and quite a bit of reading away from the starting point from learning about
relationships. It might be useful for newcomers to have a quicker path (perhaps including a sentence example of the form "if a Car model has a ForeignKey reference to the Manufacturer model, then Manufacturer instances will have an attribute "car_set" that provides access to the related Car instances") -- a natural place for this example might be under the docs for ForeignKey.related_name (http://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.ForeignKey.related_name), but as it's such a useful an interesting feature, if there's an even more prominent place to put it, so much the better.

thanks!

Attachments (2)

11864.diff (1.7 KB) - added by dwillis 4 years ago.
11864-revised.diff (1.7 KB) - added by dwillis 3 years ago.

Download all attachments as: .zip

Change History (15)

comment:1 Changed 5 years ago by anonymous

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

comment:2 Changed 4 years ago by russellm

  • milestone set to 1.2
  • Triage Stage changed from Unreviewed to Accepted

comment:3 Changed 4 years ago by ubernostrum

  • milestone 1.2 deleted

This isn't critical to 1.2; we can always go back and improve documentation as needed, but attention right now should focus on actual bugs.

comment:4 Changed 4 years ago by dwillis

  • Owner changed from nobody to dwillis
  • Status changed from new to assigned

Changed 4 years ago by dwillis

comment:5 Changed 4 years ago by dwillis

  • Has patch set

comment:6 Changed 4 years ago by dwillis

Added a patch with an example of the backwards relationship in topics/db/models, with a link to the fuller example.

comment:7 Changed 4 years ago by danielr

  • Patch needs improvement set

I don't think that belongs there at all. It goes straight from providing the syntax for ForeignKey to talking about following backwards relationships - it hasn't even shown how to follow forwards ones yet. I think this would be better off with a simple link from there to the Related objects documentation (topics/db/queries/#related-objects), perhaps replacing the existing See Also box which unhelpfully goes to the FK doctests.

comment:8 Changed 4 years ago by poswald

  • milestone set to 1.3

comment:9 Changed 3 years ago by gabrielhurley

The solution here is fairly simple, in line with danielr's suggestion.

The whole ending of the Many-to-One Relationships section should be cleaned up as follows:

  1. The "see also" section should become the last item in that section.
  2. The text under the "see also" about the model field reference is also a "see also" and should be in the "see also" box.
  3. The new information (the subject of this ticket) is *yet another* "see also" and should be in that box as well.

There should be no problem presenting the three distinctly within that callout.

We don't need to provide separate information about backwards relationships in this document, only make it easier to arrive at the existing information.

Changed 3 years ago by dwillis

comment:10 Changed 3 years ago by dwillis

  • Patch needs improvement unset

Added revised patch using gabrielhurley's recommendations.

comment:11 Changed 3 years ago by gabrielhurley

  • Resolution set to fixed
  • Status changed from assigned to closed

In [15758]:

(The changeset message doesn't reference this ticket)

comment:12 Changed 3 years ago by gabrielhurley

In [15759]:

[1.2.X] Fixed #11864 -- Improved the "see also" section of the many-to-one model topic guide to more clearly connect people to the backwards-related objects docs and to the correct point in the model tests for sample code (since the doctests went away). Thanks to dwillis for the work on the patch.

Backport of [15758] from trunk.

comment:13 Changed 3 years ago by jacob

  • milestone 1.3 deleted

Milestone 1.3 deleted

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.