Reformat and restructure lookup API documentation

[jorgecarleitao]

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

[Daniele Procida]

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.

[jorgecarleitao]

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.

[Tim Graham]

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

[Tim Graham <timograham@…>]

In 8780849da06f866720284d2c61d0aae5890e92ae:

Fixed #22812 -- Refactored lookup API documentation.

Thanks Anssi and Tim for reviews.

[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