Opened 9 years ago
Closed 3 years ago
#25444 closed Cleanup/optimization (invalid)
Restructure expressions documentation to better highlight ORM support
Reported by: | Josh Smeaton | Owned by: | nobody |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | |
Cc: | Triage Stage: | Unreviewed | |
Has patch: | no | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
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
Change History (2)
comment:1 by , 9 years ago
Component: | Uncategorized → Documentation |
---|---|
Needs documentation: | unset |
Triage Stage: | Unreviewed → Accepted |
Type: | Uncategorized → Cleanup/optimization |
comment:2 by , 3 years ago
Resolution: | → invalid |
---|---|
Status: | new → closed |
Triage Stage: | Accepted → Unreviewed |
The current version of expressions reference contains reference material for many expressions and it seems to follow the principles outlined in the Diátaxis framework. Closing as "invalid".
Other improvements related with expressions docs are tracked in #25703.