URL namespacing documentation should be clearer

[Daniele Procida]

There are a couple of places in the documentation that refer to "application instances":

<​https://docs.djangoproject.com/en/dev/topics/http/urls/#introduction>
<​https://docs.djangoproject.com/en/dev/ref/contrib/admin/#multiple-admin-sites-in-the-same-urlconf>

However, it's not really clear what an application instance is or why I might need to deploy multiple instances of one.

I think that's worth explaining in the documentation, especially since I have found a number of questions and discussions on the subject elsewhere.

I'd suggest that the explanation be incorporated in the URLs documentation.

[Daniele Procida]

Also:

• <​https://docs.djangoproject.com/en/dev/topics/http/urls/#url-namespaces only gives multiple application instances as a case for namespacing; <https://docs.djangoproject.com/en/dev/intro/tutorial03/#namespacing-url-names> cites the case of re-usable applications
• perhaps documentation should more strongly advise creating URL pattern names that are unlikely to be used in other applications, to avoid the need for namespacing

[Daniele Procida]

And in ​https://docs.djangoproject.com/en/dev/intro/tutorial03/#namespacing-url-names, instead of namespace="polls", should we not be advising to use app_name="polls"?

[Tim Graham]

Duplicate/related #17707?

[Daniele Procida]

Yes, there's some overlap. However, this one's a bit more specific, and also I once I start to get the answers clear in my head I will do some work on a patch to see if I can improve the documentation. How about a link from that one to this one?

[Aymeric Augustin]

I have a file with notes from a discussion I had with Malcolm at DjangoCon US last year. I plan (at some point) to clarify the use case of url namespaces, and maybe to relax some constraints on their use. I want to do it because it's part of Malcolm's legacy but it hasn't reached the top of my TODO list for Django yet.

[Aymeric Augustin]

Mailing-list discussion: ​https://groups.google.com/forum/#!topic/django-developers/SwzaJMXHGOE

I copied my notes in #21927.

[Tim Graham]

​PR

[Tim Graham <timograham@…>]

In a2bcec34918ba38a22b46aa5b24317c90fecf0b0:

Fixed #17707, #20734 -- Added examples to URL namespacing docs.

Thanks Daniele Procida for review.

[Tim Graham <timograham@…>]

In 588afbb2be6cf03afde8e1b17980bea09f54ba9a:

[1.7.x] Fixed #17707, #20734 -- Added examples to URL namespacing docs.

Thanks Daniele Procida for review.

Backport of a2bcec3491 from master