Context Navigation

← Previous Ticket
Next Ticket →

#32372 closed Cleanup/optimization (fixed)

Improve consistency in "Related objects reference" docs.

Reported by:	Jack Aitken	Owned by:	Jack Aitken
Component:	Documentation	Version:	3.1
Severity:	Normal	Keywords:
Cc:		Triage Stage:	Accepted
Has patch:	yes	Needs documentation:	no
Needs tests:	no	Patch needs improvement:	no
Easy pickings:	yes	UI/UX:	no

Description

I have a suggested clarification in the docs, under the "Related objects reference" section: https://docs.djangoproject.com/en/3.1/ref/models/relations/.

One of the first examples of a ManyToMany field relationship begins with an example of a Pizza model and a Toppings model, but in the shell example below it demonstrates this relationship with two different models: a Blog model and an Entry model.

I've read through this section a few times so I apologize in advance if I'm incorrect in my understanding, but in my opinion it would be clearer to stick with one set of classes for both the examples. If choosing to continue with the Pizza and Toppings example, I would suggest changing the example shown in the shell as follows:

>>> t = Topping.objects.get(id=1)
>>> p = Pizza.objects.get(id=5)
>>> t.pizza_set.add(p) # Associates Topping t with Pizza p.

If this is agreeable, I would love to make this change.

Change History (11)

comment:1 by Jack Aitken, 4 years ago

Type:	Uncategorized → Cleanup/optimization

follow-up: 3 comment:2 by Mariusz Felisiak, 4 years ago

Easy pickings:	set
Owner:	changed from nobody to Jack Aitken
Status:	new → assigned
Summary:	Clarification of "RelatedManager" class example → Improve consistency in "Related objects reference" docs.
Triage Stage:	Unreviewed → Accepted

Examples in this page use reverse relation for a ForeignKey not a ManyToManyField, so the be more consistent we could change change the Reporter - Article example to Blog - Entry, e.g.:

class Blog(models.Model):
    # ...
    pass

class Entry(models.Model):
    blog = models.ForeignKey(Entry, on_delete=models.CASCADE)

in reply to: 2 comment:3 by Jack Aitken, 4 years ago

Replying to Mariusz Felisiak:

Apologies, this is my first contribution so I'm still learning a lot. I've followed the Advice for new contributors as well as Writing documentation. I've now built the html files using Sphinx but when I try to git add relations.html from /docs/_build/html/ref/models I get an error:

The following paths are ignored by one of your .gitignore files:
docs/_build/html/ref/models/relations.html

Sorry! Any help you can give would be really appreciated.

comment:4 by Tim Graham, 4 years ago

Only the source files for the docs are stored in version control. You can build the docs locally for testing, but you shouldn't put anything from docs/_build in your commit.