It is not documented how to work with ManyToMany relations

[Mikhail Korobov]

The docs for ManyToMany relations used to rely on doctests ("See the Many-to-many relationship model example for a full example.")
​https://docs.djangoproject.com/en/dev/topics/db/models/#many-to-many-relationships

But since https://code.djangoproject.com/changeset/14285/ these doctests were removed. So ManyToMany relations are now almost undocumented (both in dev version of docs and in all old versions of docs).

Because this is a regression from Django 1.3 I've marked it as a release blocker.

[Claude Paroz]

Adding ManyToManyField examples

[Claude Paroz]

I added some code examples in the docs. Don't know if it is enough to cover most usages, but it's a start at least. Double-check my English, as usual.

[Ramiro Morales]

Alternative patch adding a topics/db/examples/ hierarchy

[Ramiro Morales]

In the '-2' patch I simply converted to ReST syntax the models.py files of the modeltests for m2m, FK and one2one relationships freezing them with the state they were in when their respective doctests were removed.

Also, removed all references to tests/modeltests/* from topics/db/models.txt.

[Zbigniew Siciarz]

The second patch is a good starting point. However, in my opinion the examples should be simplified. There's too much tests for various field lookups which are already documented elsewhere. If these are meant to be examples, they must be short, simple and useful. Also a few more lines of text would be welcome.

[Zbigniew Siciarz]

Trying to simplify the examples, probably needs some more tweaking.

[Ramiro Morales]

zsiciarz's patch plus some ReST/Sphinx tweaks

[Aymeric Augustin]

The style shows that these documents used to be doctests, but it's a good basis IMO.

topics/db/models.txt

• This page still refers to the "Many-to-one relationship model tests", but that link is pointing to a regular documentation page. Use the same wording as the other "See also" blocks?

topics/db/examples/many_to_one.txt

• a = Article(id=None, ...: this isn't idiomatic; I'd skip the id kwarg entirely.
• "Article objects have access to their related Reporter objects:": this was demonstrated just above, I'd reorganize this part a bit
• >>> Article.objects.filter(reporter=1): I didn't know this was supported, and it feels unclean. Plus, there are two ways to do the same thing. Do we really want to document this possibility?
• >>> Reporter.objects.filter(article=1): same comment

topics/db/examples/many_to_many.txt

• "Add a Publication directly via publications.add...": shouldn't that be "publications.create"?
• >>> Article.objects.filter(publications=1): same comment again
• publications__in=[1,2]: missing space after the comma
• publications__in=[p1,p2]: missing space after the comma
• >>> Publication.objects.filter(article=1): same comment again
• article__in=[1,2]: missing space after the comma
• article__in=[a1,a2]: missing space after the comma
• "After the delete, the QuerySet cache needs to be cleared, and the referenced objects should be gone": this sounds like an internal implementation detail, not something a developer using Django should worry about

topics/db/examples/one_to_one.txt

• "Restaurant.objects.all()" should be in fixed width font.

I hope this helps!

[James Bennett]

In [17737]:

Fixed #17605: Restored deleted query documentation that used to live in doctests. Thanks zsiciarz for work on the patch.

[Claude Paroz]

In [17832]:

Fixed #17999 -- Restored the links to examples from models documentation. Refs #17605.

[Claude Paroz]

In [17833]:

[1.4.X] Fixed #17999 -- Restored the links to examples from models documentation. Refs #17605.

Backport of r17832 from trunk.