[Django] #36095: Explicitly introduce lazy references in early sections of the docs before they are used.

[Django]

#36095: Explicitly introduce lazy references in early sections of the docs before
they are used.
-------------------------------------+-------------------------------------
Reporter: Clifford | Owner: Clifford Gama
Gama |
Type: | Status: assigned
Cleanup/optimization |
Component: | Version: 5.1
Documentation |
Severity: Normal | Keywords:
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
While reading https://docs.djangoproject.com/en/dev/topics/db/models/, I
noticed two issues:
1. Lazy relationships are used in the documentation before they are
explicitly introduced
https://docs.djangoproject.com/en/dev/topics/db/models/#extra-fields-on-
many-to-many-relationships
2. The `ManyToManyField.through` option does not document that it supports
lazy references.

To address these:

For the first issue, I propose explicitly introducing lazy references in
the introductory [https://docs.djangoproject.com/en/dev/topics/db/models
/#models-across-files Models across files] section.
For the second issue, I propose adding a note to the
`ManyToManyField.through` section, clarifying that it supports both lazy
references and direct model classes.
--
Ticket URL: <https://code.djangoproject.com/ticket/36095>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36095: Explicitly introduce lazy references in early sections of the docs before
they are used.
-------------------------------------+-------------------------------------

Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Clifford Gama):

* has_patch: 0 => 1

Comment:

[https://github.com/django/django/pull/19041 PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/36095#comment:1>

[Django]

#36095: Explicitly introduce lazy references in early sections of the docs before
they are used.
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* stage: Unreviewed => Accepted

--
Ticket URL: <https://code.djangoproject.com/ticket/36095#comment:2>

[Django]

#36095: Explicitly introduce lazy references in early sections of the docs before
they are used.
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:

Keywords: | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Sarah Boyce):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/36095#comment:3>

[Django]

#36095: Explicitly introduce lazy references in early sections of the docs before
they are used.
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Sarah Boyce <42296566+sarahboyce@…>):

In [changeset:"eb4ea9c3efca479b169bed88a5521c4cf47ed2a2" eb4ea9c]:
{{{#!CommitTicketReference repository=""
revision="eb4ea9c3efca479b169bed88a5521c4cf47ed2a2"
Refs #36095 -- Doc'd that ManyToManyField.through supports lazy
relationships.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36095#comment:4>

[Django]

#36095: Explicitly introduce lazy references in early sections of the docs before
they are used.
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama

Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce <42296566+sarahboyce@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"6a2c296e706a0b8f9f9b89e66b37001ce2a03ea7" 6a2c296]:
{{{#!CommitTicketReference repository=""
revision="6a2c296e706a0b8f9f9b89e66b37001ce2a03ea7"
Fixed #36095 -- Introduced lazy references in "Models across files"
section.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36095#comment:5>

[Django]

#36095: Explicitly introduce lazy references in early sections of the docs before
they are used.
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Sarah Boyce <42296566+sarahboyce@…>):

In [changeset:"37b8a45f5a7260ecaec851c9f359240a7d15afbb" 37b8a45]:
{{{#!CommitTicketReference repository=""
revision="37b8a45f5a7260ecaec851c9f359240a7d15afbb"
[5.2.x] Fixed #36095 -- Introduced lazy references in "Models across
files" section.

Backport of 6a2c296e706a0b8f9f9b89e66b37001ce2a03ea7 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36095#comment:7>

[Django]

#36095: Explicitly introduce lazy references in early sections of the docs before
they are used.
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Sarah Boyce <42296566+sarahboyce@…>):

In [changeset:"61535d2228bc1dec5d843793f1c1cfe27a784acc" 61535d2]:
{{{#!CommitTicketReference repository=""
revision="61535d2228bc1dec5d843793f1c1cfe27a784acc"
[5.2.x] Refs #36095 -- Doc'd that ManyToManyField.through supports lazy
relationships.

Backport of eb4ea9c3efca479b169bed88a5521c4cf47ed2a2 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36095#comment:6>

[Django]

#36095: Explicitly introduce lazy references in early sections of the docs before
they are used.
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Sarah Boyce <42296566+sarahboyce@…>):

In [changeset:"f927c9f2aac2d41ddbb7454da6470a9e93b26c38" f927c9f]:
{{{#!CommitTicketReference repository=""
revision="f927c9f2aac2d41ddbb7454da6470a9e93b26c38"
[5.1.x] Fixed #36095 -- Introduced lazy references in "Models across
files" section.

Backport of 6a2c296e706a0b8f9f9b89e66b37001ce2a03ea7 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36095#comment:9>

[Django]

#36095: Explicitly introduce lazy references in early sections of the docs before
they are used.
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Sarah Boyce <42296566+sarahboyce@…>):

In [changeset:"bd8bbc8c1a5971ce9cea325357234b119b91802a" bd8bbc8]:
{{{#!CommitTicketReference repository=""
revision="bd8bbc8c1a5971ce9cea325357234b119b91802a"
[5.1.x] Refs #36095 -- Doc'd that ManyToManyField.through supports lazy
relationships.

Backport of eb4ea9c3efca479b169bed88a5521c4cf47ed2a2 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36095#comment:8>