Opened 10 months ago

Closed 9 months ago

Last modified 9 months 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 10 months ago by EvilDMP

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

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 10 months ago by EvilDMP

  • Easy pickings set

comment:3 Changed 10 months 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 10 months ago by timo

  • 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 9 months ago by jorgecarleitao

  • Patch needs improvement unset

comment:6 Changed 9 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from new to closed

In 8780849da06f866720284d2c61d0aae5890e92ae:

Fixed #22812 -- Refactored lookup API documentation.

Thanks Anssi and Tim for reviews.

comment:7 Changed 9 months 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