[Django] #25444: Restructure expressions documentation to better highlight ORM support
Django
-----------------------------------------+------------------------
Reporter: jarshwah | Owner: nobody
Type: Uncategorized | Status: new
Component: Uncategorized | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 1 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-----------------------------------------+------------------------
The docs in docs/ref/models/expressions.txt could probably do with an
overhaul. The original document was very specific about highlighting the
use-cases of F expressions in terms of filter and update.
I think the docs should be structured in terms of which queryset methods
support expressions. We can then leave the specific expression reference
below.
Some of the F() examples can be pulled out into the queryset method
sections, but the F() section can still highlight the things it is
particularly good at -- like avoiding race conditions.
The docs would be structured like:
{{{
=================
Query Expressions
=================
Intro..
Supported QuerySet Operations
=========================
Not every :doc:`QuerySet </ref/models/queryset>` method has full support
for
Query Expressions, but the support is growing with each release. Below is
a
quick overview showing which methods do have support.
create() and update()
----------------------------------
Intro
Examples
filter() and exclude()
--------------------------------
Intro
Examples
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25444>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: jarshwah | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timgraham):
* component: Uncategorized => Documentation
* needs_docs: 1 => 0
* type: Uncategorized => Cleanup/optimization
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/25444#comment:1>
Django
Reporter: Josh Smeaton | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak):
* status: new => closed
* resolution: => invalid
* stage: Accepted => Unreviewed
Comment:
The current version of
[https://docs.djangoproject.com/en/4.0/ref/models/expressions/ expressions
reference] contains reference material for many expressions and it seems
to follow the principles outlined in the [https://diataxis.fr/ Diátaxis
framework]. Closing as "invalid".
Other improvements related with expressions docs are tracked in #25703.
--
Ticket URL: <https://code.djangoproject.com/ticket/25444#comment:2>