Opened 2 years ago

Closed 2 years ago

Last modified 2 years ago

#22812 closed Cleanup/optimization (fixed)

Reformat and restructure lookup API documentation

Reported by: jorgecarleitao Owned by: jorgecarleitao
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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.
  1. 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?)

Change History (7)

comment:1 Changed 2 years ago by Daniele Procida

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Triage Stage: UnreviewedAccepted

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.

comment:2 Changed 2 years ago by Daniele Procida

Easy pickings: set

comment:3 Changed 2 years ago by jorgecarleitao

Has patch: set

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.

comment:4 Changed 2 years ago by Tim Graham

Patch needs improvement: set

I think it would be better not to move the built-in lookups for the reason you mentioned.

comment:5 Changed 2 years ago by jorgecarleitao

Patch needs improvement: unset

comment:6 Changed 2 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: newclosed

In 8780849da06f866720284d2c61d0aae5890e92ae:

Fixed #22812 -- Refactored lookup API documentation.

Thanks Anssi and Tim for reviews.

comment:7 Changed 2 years ago by Tim Graham <timograham@…>

In e548328851ee1e0d030ad3625c5e8a5315a12ed4:

[1.7.x] Fixed #22812 -- Refactored lookup API documentation.

Thanks Anssi and Tim for reviews.

Backport of 8780849da0 from master

Note: See TracTickets for help on using tickets.
Back to Top