Add examples with nested arrays/objects to JSONField docs for __contains and __contained_by

[Jacob Walls]

With data in a JSON field like:

{"key": [1, 2]}

I was initially surprised to find that this returns a match, since I assumed the values would be compared by equality when determining whether the top-level contains:

.filter(field__contains={"key": [1]})  # the additional value in the array doesn't matter

---

The ​docs say:

The returned objects are those where the given dict of key-value pairs are all contained in the top-level of the field.

From this sentence I assumed values were checked by equality, not containment all the way down. Apparently this is how it is supposed to work, see #31836. Of course strings don't behave this way, {"key": "value"} does not contain {"key": "val"}.

This seems tricky enough to warrant a little example?

[Sarah Boyce]

I agree adding an example would be nice, thank you for the ticket Jacob

[Clifford Gama]

​https://github.com/django/django/pull/19226

[GitHub <noreply@…>]

In 304e9f3d:

Fixed #36202 -- Added examples of JSONField contains and contained_by lookups with nested arrays to docs.

[Mariusz Felisiak <felisiak.mariusz@…>]

In bcb6ada2:

[5.2.x] Fixed #36202 -- Added examples of JSONField contains and contained_by lookups with nested arrays to docs.

Backport of 304e9f3d6ae8387bbfc261d68b51247a1f5230bb from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In e9acb05b:

[5.1.x] Fixed #36202 -- Added examples of JSONField contains and contained_by lookups with nested arrays to docs.

Backport of 304e9f3d6ae8387bbfc261d68b51247a1f5230bb from main