[Django] #32957: Make documentation of Model.save() arguments easier to find and get to
Django
------------------------------------------------+------------------------
Reporter: Chris Jerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
------------------------------------------------+------------------------
Currently, in the documentation of
[https://docs.djangoproject.com/en/3.2/ref/models/instances/#saving-
objects Model.save()], one needs to scroll far down to find documentation
of the keyword arguments. For example, for the `update_fields` argument,
one has to scroll down to a section called
[https://docs.djangoproject.com/en/3.2/ref/models/instances/#specifying-
which-fields-to-save "Specifying which fields to save"].
I think it would be helpful if, right after `Model.save()`'s function
signature in the docs, there was a sentence or two containing a link to
the right section, for each keyword argument argument appearing in the
signature. I'm thinking of sentences like, "For documentation of the
`force_insert` and `force_update` arguments, see the "Forcing an INSERT or
UPDATE" section. ..." This will make it clearer where the documentation of
the argument can be found.
--
Ticket URL: <https://code.djangoproject.com/ticket/32957>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: Chris Jerdonek | Owner: nobody
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Description changed by Chris Jerdonek:
Old description:
> Currently, in the documentation of
> [https://docs.djangoproject.com/en/3.2/ref/models/instances/#saving-
> objects Model.save()], one needs to scroll far down to find documentation
> of the keyword arguments. For example, for the `update_fields` argument,
> one has to scroll down to a section called
> [https://docs.djangoproject.com/en/3.2/ref/models/instances/#specifying-
> which-fields-to-save "Specifying which fields to save"].
>
> I think it would be helpful if, right after `Model.save()`'s function
> signature in the docs, there was a sentence or two containing a link to
> the right section, for each keyword argument argument appearing in the
> signature. I'm thinking of sentences like, "For documentation of the
> `force_insert` and `force_update` arguments, see the "Forcing an INSERT
> or UPDATE" section. ..." This will make it clearer where the
> documentation of the argument can be found.
New description:
Currently, in the documentation of
[https://docs.djangoproject.com/en/3.2/ref/models/instances/#saving-
objects Model.save()], one needs to scroll far down to find documentation
of the keyword arguments. For example, for the `update_fields` argument,
one has to scroll down to a section called
[https://docs.djangoproject.com/en/3.2/ref/models/instances/#specifying-
which-fields-to-save "Specifying which fields to save"].
I think it would be helpful if, right after `Model.save()`'s function
signature in the docs, there was a sentence or two containing a link to
the right section, for each keyword argument argument appearing in the
signature. I'm thinking of sentences like, "For documentation of the
`force_insert` and `force_update` arguments, see the "Forcing an INSERT or
UPDATE" section. ..." This will make it clearer where the documentation
for the arguments can be found.
--
--
Ticket URL: <https://code.djangoproject.com/ticket/32957#comment:1>
Django
Reporter: Chris Jerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Mariusz Felisiak):
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/32957#comment:2>
Django
Reporter: Chris Jerdonek | Owner: Abhyudai
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Abhyudai):
* owner: nobody => Abhyudai
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/32957#comment:3>
Django
Reporter: Chris Jerdonek | Owner: Abhyudai
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Abhyudai):
* has_patch: 0 => 1
Comment:
[https://github.com/django/django/pull/14684 pull-request]
--
Ticket URL: <https://code.djangoproject.com/ticket/32957#comment:4>
Django
Reporter: Chris Jerdonek | Owner: Abhyudai
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Mariusz Felisiak):
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/32957#comment:5>
Django
Reporter: Chris Jerdonek | Owner: Abhyudai
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Mariusz Felisiak <felisiak.mariusz@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"f876c7d08e75d719df5cd34b97cac63fdaae3fcc" f876c7d0]:
{{{
#!CommitTicketReference repository=""
revision="f876c7d08e75d719df5cd34b97cac63fdaae3fcc"
Fixed #32957 -- Improved visibility of arguments sections in Model.save()
docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32957#comment:6>
Django
Reporter: Chris Jerdonek | Owner: Abhyudai
Type: | Status: closed
Cleanup/optimization |
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"bdd4cbe84a4f89b114e614042a9e7f280c0ced63" bdd4cbe8]:
{{{
#!CommitTicketReference repository=""
revision="bdd4cbe84a4f89b114e614042a9e7f280c0ced63"
[3.2.x] Fixed #32957 -- Improved visibility of arguments sections in
Model.save() docs.
Backport of f876c7d08e75d719df5cd34b97cac63fdaae3fcc from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32957#comment:7>