[Django] #22812: Reformat and restructure lookup API documentation
Django
--------------------------------------+----------------------------
Reporter: jorgecarleitao | Owner: jorgecarleitao
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+----------------------------
Currently the API documentation docs/ref/models/custom-lookups.txt has
some formatting issues, and mixes the howto with the API references, see
https://docs.djangoproject.com/en/dev/ref/models/custom-lookups/
Here I'm proposing to separate these two concepts:
1. Adding a new howto - docs/howto/custom-lookups.txt - for custom
lookups, which includes section
https://docs.djangoproject.com/en/dev/ref/models/custom-lookups/#a-simple-
lookup-example to section https://docs.djangoproject.com/en/dev/ref/models
/custom-lookups/#how-django-determines-the-lookups-and-transforms-which-
are-used with potential improvements.
2. Renaming "custom-lookups.txt" to "lookups.txt" in ref/models to be the
documentation of lookups API, with references for the public interfaces of
`RegisterLookupMixin`, `Lookup`, `Transform`.
Optionally, because the BuiltIn lookups are part of this new API, they
could be documented in 2., but this may not be possible due to backward
compatibility of documentation urls (devs?)
--
Ticket URL: <https://code.djangoproject.com/ticket/22812>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: jorgecarleitao | Owner:
Type: | jorgecarleitao
Cleanup/optimization | Status: new
Component: Documentation | Version: master
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 EvilDMP):
* needs_better_patch: => 0
* stage: Unreviewed => Accepted
* needs_tests: => 0
* needs_docs: => 0
Comment:
If the structure of the documentation needs to change then it needs to
change - we don't need to worry too much about URLs in such a case.
--
Ticket URL: <https://code.djangoproject.com/ticket/22812#comment:1>
Django
Reporter: jorgecarleitao | Owner:
Type: | jorgecarleitao
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Changes (by EvilDMP):
* easy: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/22812#comment:2>
Django
Reporter: jorgecarleitao | Owner:
Type: | jorgecarleitao
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* has_patch: 0 => 1
Comment:
Pull request here: https://github.com/django/django/pull/2807
At some point we need to discuss what more can be merged on
ref/models/lookups. E.g. could make sense to add the builtin lookups
there.
--
Ticket URL: <https://code.djangoproject.com/ticket/22812#comment:3>
Django
Reporter: jorgecarleitao | Owner:
Type: | jorgecarleitao
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* needs_better_patch: 0 => 1
Comment:
I think it would be better not to move the built-in lookups for the reason
you mentioned.
--
Ticket URL: <https://code.djangoproject.com/ticket/22812#comment:4>
Django
Reporter: jorgecarleitao | Owner:
Type: | jorgecarleitao
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* needs_better_patch: 1 => 0
--
Ticket URL: <https://code.djangoproject.com/ticket/22812#comment:5>
Django
Reporter: jorgecarleitao | Owner:
Type: | jorgecarleitao
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: new => closed
* resolution: => fixed
Comment:
In [changeset:"8780849da06f866720284d2c61d0aae5890e92ae"]:
{{{
#!CommitTicketReference repository=""
revision="8780849da06f866720284d2c61d0aae5890e92ae"
Fixed #22812 -- Refactored lookup API documentation.
Thanks Anssi and Tim for reviews.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/22812#comment:6>
Django
Reporter: jorgecarleitao | Owner:
Type: | jorgecarleitao
Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"e548328851ee1e0d030ad3625c5e8a5315a12ed4"]:
{{{
#!CommitTicketReference repository=""
revision="e548328851ee1e0d030ad3625c5e8a5315a12ed4"
[1.7.x] Fixed #22812 -- Refactored lookup API documentation.
Thanks Anssi and Tim for reviews.
Backport of 8780849da0 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/22812#comment:7>