Add PostgreSQL Extension operation example to reference page

[Maxime Lorant]

TrigramExtension and UnaccentExtension have been introduced in django.contrib.postgres in Django 1.10 to help developpers to activate the pg_trim and unaccent extension of postgres when they are using the corresponding ORM lookup.

Even though I feel pretty comfortable with the Django doc usually, this time, I did not find UnaccentExtension in few minutes. In local, I did the extension activation by myself (since I did not read the relevant part of the doc) but get stuck when trying to execute my unit tests. I think these migration operations are not stressed enough in the doc. I believe it is [referenced only here](​https://docs.djangoproject.com/en/1.10/ref/contrib/postgres/lookups/), each time in a sentence which barely says when to use it.

I think there should be an introduction at the top of the page linked above saying something like: "The lookups above need the activation of extensions in Postgres. To enable them, you are advised to create a Django migration which will apply the relevant operation", where the "relevant operation" is referring to either TrigramExtension or UnaccentExtension, but I don't know how to transcribe it :/

[Tim Graham]

It's not entirely clear to me why you want the instructions repeated twice, once at the top of the page and once within the docs for each extension -- or did I misunderstand the suggestion? Another consideration is that future lookups might not require activation of an extension.

[Maxime Lorant]

Replying to Tim Graham:

It's not entirely clear to me why you want the instructions repeated twice, once at the top of the page and once within the docs for each extension -- or did I misunderstand the suggestion? Another consideration is that future lookups might not require activation of an extension.

I don't think it should be write twice, but I guess it would not hurt if the usefulness of these two classes was more explicit so it can be easier to find it.

(It is marked as cleanup, we can live with the current wording, but I think it could be better :) )

[Tim Graham]

Maybe moving the HStoreExtension example from ​https://docs.djangoproject.com/en/dev/ref/contrib/postgres/fields/#django.contrib.postgres.fields.HStoreField to ​https://docs.djangoproject.com/en/dev/ref/contrib/postgres/operations/ and explaining that the same usage principles apply for all extensions would be help?

[Maxime Lorant]

That would be great, yes, and it does involve a lot of changes.

[Levi Velázquez]

What Maxime suggested sounds good, I think we can add an section on ​https://docs.djangoproject.com/en/dev/ref/contrib/postgres/operations/ named "Create extension using migrations" and add the example from ​​https://docs.djangoproject.com/en/dev/ref/contrib/postgres/fields/#django.contrib.postgres.fields.HStoreField.

About Tom reply, why it does involve a lot of changes ?

I'm interesting to take this cleanup, It would be my first contribution to Django.

[Maxime Lorant]

Replying to Levi Velázquez:

About Tom reply, why it does involve a lot of changes ?

I'm interesting to take this cleanup, It would be my first contribution to Django.

I forgot a "not", you should read: "it does NOT involve [...] " :-) It's merely copy-pasting in another page with some adjustments.

[ntuckovic]

​PR

[Reinout van Rees]

Looks fine, apart from some spelling/formatting corrections. These have been noted as comments on the PR.

For clarity, I've set the "patch needs improvement" checkbox as there are two sets of suggested fixes on the PR.

[Tim Graham <timograham@…>]

In 4de8aaf:

Fixed #27355 -- Added “Creating extension using migrations” docs.

[Tim Graham <timograham@…>]

In 1b6649c6:

[1.10.x] Fixed #27355 -- Added “Creating extension using migrations” docs.

Backport of 4de8aaf7ffc91b91cbb70e9db406abe9b160575a from master