Clarify the docs about what INTERNAL_IPS does

[Marten Kenbeek]

The ​current documentation says:

A tuple of IP addresses, as strings, that:

• See debug comments, when DEBUG is True
• Receive X headers in admindocs if the XViewMiddleware is installed (see The Django admin documentation generator)

The documentation of DEBUG doesn't mention INTERNAL_IPS at all, and the documentation of the admindocs only briefly mentions it in the last line.

[Tim Graham]

There's also a usage in AdminEmailHandler that could be mentioned.

[Alex Morozov]

Guys, could you please elaborate on what specifically must be documented?

INTERNAL_IPS is now used at three places (except tests):

1. django.template.context_processors.debug to add SQL queries to context. Its docs mention the setting. Is it enough?
2. django.contrib.admindocs.middleware.XViewMiddleware to add an X-View header. Docs mention the setting. Should we refactor documentation? I hardly can imagine what to add about the middleware itself.
3. django.utils.log.AdminEmailHandler to prefix an email subject with an 'internal'/'EXTERNAL' marks. Should we mention the setting ​here?

As for the DEBUG documentation, it seems pretty complete to me, since this setting has no direct relation to the INTERNAL_IPS. Am I wrong?

[Tim Graham]

Linking from the ​INTERNAL_IPS setting to where each of those features are discussed in more detail would be helpful.

[Alex Morozov]

@timgraham, thank you. Do I understand correctly that the existing phrase "See debug comments, when DEBUG is True" is about the debug context processor?

[Tim Graham]

Yes, I think so.

[Alex Morozov]

Someone, please review my ​russian English.

[Tim Graham <timograham@…>]

In 5abed86:

Fixed #25710 -- Clarified the docs about what INTERNAL_IPS does.

[Tim Graham <timograham@…>]

In 361038ee:

[1.9.x] Fixed #25710 -- Clarified the docs about what INTERNAL_IPS does.

Backport of 5abed864ee1cd31a0b920768b4abe85b26b43a4d from master

[Tim Graham <timograham@…>]

In b4aa38d:

[1.8.x] Fixed #25710 -- Clarified the docs about what INTERNAL_IPS does.

Backport of 5abed864ee1cd31a0b920768b4abe85b26b43a4d from master