More URL mapping documentation fixes.

docs/ref/urls.txt

@@ -80,15 +80,32 @@ The ``prefix`` parameter has the same meaning as the first argument to
 include()
 ---------
 
-.. function:: include(<module or pattern_list>)
+.. function:: include(module[, namespace=None, app_name=None])
+              include(pattern_list)
+              include((pattern_list, app_namespace, instance_namespace))
 
-A function that takes a full Python import path to another URLconf module that
+    A function that takes a full Python import path to another URLconf module
-should be "included" in this place.
+    that should be "included" in this place. Optionally, the :term:`application
+    namespace` and :term:`instance namespace` where the entries will be included
+    into can also be specified.
 
-:func:`include` also accepts as an argument an iterable that returns URL
+    ``include()`` also accepts as an argument either an iterable that returns
-patterns.
+    URL patterns or a 3-tuple containing such iterable plus the names of the
+    application and instance namespaces.
 
-See :ref:`Including other URLconfs <including-other-urlconfs>`.
+    :arg module: URLconf module (or module name)
+    :type module: Module or string
+    :arg namespace: Instance namespace for the URL entries being included
+    :type namespace: string
+    :arg app_name: Application namespace for the URL entries being included
+    :type app_name: string
+    :arg pattern_list: Iterable of URL entries as returned by :func:`patterns`
+    :arg app_namespace: Application namespace for the URL entries being included
+    :type app_namespace: string
+    :arg instance_namespace: Instance namespace for the URL entries being included
+    :type instance_namespace: string
+
+See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`.
 
 handler403
 ----------

docs/topics/http/urls.txt

@@ -327,7 +327,7 @@ essentially "roots" a set of URLs below other ones.
 For example, here's an excerpt of the URLconf for the `Django Web site`_
 itself. It includes a number of other URLconfs::
 
-    from django.conf.urls import patterns, url, include
+    from django.conf.urls import patterns, include
 
     urlpatterns = patterns('',
         # ... snip ...
@@ -347,28 +347,23 @@ string to the included URLconf for further processing.
 Another possibility is to include additional URL patterns not by specifying the
 URLconf Python module defining them as the ``include()`` argument but by using
 directly the pattern list as returned by :func:`~django.conf.urls.patterns`
-instead. For example::
+instead. For example, consider this URLconf::
 
     from django.conf.urls import patterns, url, include
 
     extra_patterns = patterns('',
-        url(r'^reports/(?P<id>\d+)/$', 'credit.views.report', name='credit-reports'),
+        url(r'^reports/(?P<id>\d+)/$', 'credit.views.report'),
-        url(r'^charge/$', 'credit.views.charge', name='credit-charge'),
+        url(r'^charge/$', 'credit.views.charge'),
     )
 
     urlpatterns = patterns('',
-        url(r'^$', 'apps.main.views.homepage', name='site-homepage'),
+        url(r'^$', 'apps.main.views.homepage'),
         (r'^help/', include('apps.help.urls')),
         (r'^credit/', include(extra_patterns)),
     )
 
-This approach can be seen in use when you deploy an instance of the Django
+In this example, the ``/credit/reports/`` URL will be handled by the
-Admin application. The Django Admin is deployed as instances of a
+``credit.views.report()`` Django view.
-:class:`~django.contrib.admin.AdminSite`; each
-:class:`~django.contrib.admin.AdminSite` instance has an attribute ``urls``
-that returns the url patterns available to that instance. It is this attribute
-that you ``include()`` into your projects ``urlpatterns`` when you deploy the
-admin instance.
 
 .. _`Django Web site`: https://www.djangoproject.com/
 
@@ -595,33 +590,33 @@ A URL namespace comes in two parts, both of which are strings:
     This describes the name of the application that is being deployed. Every
     instance of a single application will have the same application namespace.
     For example, Django's admin application has the somewhat predictable
-    application namespace of ``admin``.
+    application namespace of ``'admin'``.
 
   instance namespace
     This identifies a specific instance of an application. Instance namespaces
     should be unique across your entire project. However, an instance namespace
     can be the same as the application namespace. This is used to specify a
     default instance of an application. For example, the default Django Admin
-    instance has an instance namespace of ``admin``.
+    instance has an instance namespace of ``'admin'``.
 
-Namespaced URLs are specified using the ``:`` operator. For example, the main
+Namespaced URLs are specified using the ``':'`` operator. For example, the main
-index page of the admin application is referenced using ``admin:index``. This
+index page of the admin application is referenced using ``'admin:index'``. This
-indicates a namespace of ``admin``, and a named URL of ``index``.
+indicates a namespace of ``'admin'``, and a named URL of ``'index'``.
 
-Namespaces can also be nested. The named URL ``foo:bar:whiz`` would look for
+Namespaces can also be nested. The named URL ``'foo:bar:whiz'`` would look for
-a pattern named ``whiz`` in the namespace ``bar`` that is itself defined within
+a pattern named ``'whiz'`` in the namespace ``'bar'`` that is itself defined
-the top-level namespace ``foo``.
+within the top-level namespace ``'foo'``.
 
 .. _topics-http-reversing-url-namespaces:
 
 Reversing namespaced URLs
 -------------------------
 
-When given a namespaced URL (e.g. ``myapp:index``) to resolve, Django splits
+When given a namespaced URL (e.g. ``'myapp:index'``) to resolve, Django splits
 the fully qualified name into parts, and then tries the following lookup:
 
-1. First, Django looks for a matching application namespace (in this
+1. First, Django looks for a matching :term:`application namespace` (in this
-   example, ``myapp``). This will yield a list of instances of that
+   example, ``'myapp'``). This will yield a list of instances of that
    application.
 
 2. If there is a *current* application defined, Django finds and returns
@@ -632,19 +627,20 @@ the fully qualified name into parts, and then tries the following lookup:
    render a template.
 
    The current application can also be specified manually as an argument
-   to the :func:`reverse()` function.
+   to the :func:`django.core.urlresolvers.reverse()` function.
 
 3. If there is no current application. Django looks for a default
    application instance. The default application instance is the instance
-   that has an instance namespace matching the application namespace (in
+   that has an :term:`instance namespace` matching the :term:`application
-   this example, an instance of the ``myapp`` called ``myapp``).
+   namespace` (in this example, an instance of the ``myapp`` called
+   ``'myapp'``).
 
 4. If there is no default application instance, Django will pick the last
    deployed instance of the application, whatever its instance name may be.
 
-5. If the provided namespace doesn't match an application namespace in
+5. If the provided namespace doesn't match an :term:`application namespace` in
    step 1, Django will attempt a direct lookup of the namespace as an
-   instance namespace.
+   :term:`instance namespace`.
 
 If there are nested namespaces, these steps are repeated for each part of the
 namespace until only the view name is unresolved. The view name will then be
@@ -654,58 +650,68 @@ Example
 ~~~~~~~
 
 To show this resolution strategy in action, consider an example of two instances
-of ``myapp``: one called ``foo``, and one called ``bar``. ``myapp`` has a main
+of ``myapp``: one called ``'foo'``, and one called ``'bar'``. ``myapp`` has a
-index page with a URL named `index`. Using this setup, the following lookups are
+main index page with a URL named ``'index'``. Using this setup, the following
-possible:
+lookups are possible:
 
 * If one of the instances is current - say, if we were rendering a utility page
-  in the instance ``bar`` - ``myapp:index`` will resolve to the index page of
+  in the instance ``'bar'`` - ``'myapp:index'`` will resolve to the index page
-  the instance ``bar``.
+  of the instance ``'bar'``.
 
 * If there is no current instance - say, if we were rendering a page
-  somewhere else on the site - ``myapp:index`` will resolve to the last
+  somewhere else on the site - ``'myapp:index'`` will resolve to the last
   registered instance of ``myapp``. Since there is no default instance,
   the last instance of ``myapp`` that is registered will be used. This could
-  be ``foo`` or ``bar``, depending on the order they are introduced into the
+  be ``'foo'`` or ``'bar'``, depending on the order they are introduced into the
   urlpatterns of the project.
 
-* ``foo:index`` will always resolve to the index page of the instance ``foo``.
+* ``'foo:index'`` will always resolve to the index page of the instance
+  ``'foo'``.
 
-If there was also a default instance - i.e., an instance named `myapp` - the
+If there was also a default instance - i.e., an instance named ``'myapp'`` - the
 following would happen:
 
 * If one of the instances is current - say, if we were rendering a utility page
-  in the instance ``bar`` - ``myapp:index`` will resolve to the index page of
+  in the instance ``'bar'`` - ``'myapp:index'`` will resolve to the index page
-  the instance ``bar``.
+  of the instance ``'bar'``.
 
 * If there is no current instance - say, if we were rendering a page somewhere
-  else on the site - ``myapp:index`` will resolve to the index page of the
+  else on the site - ``'myapp:index'`` will resolve to the index page of the
   default instance.
 
-* ``foo:index`` will again resolve to the index page of the instance ``foo``.
+* ``'foo:index'`` will again resolve to the index page of the instance
+  ``'foo'``.
+
+.. _namespaces-and-include:
 
 URL namespaces and included URLconfs
 ------------------------------------
 
 URL namespaces of included URLconfs can be specified in two ways.
 
-Firstly, you can provide the application and instance namespace as arguments
+Firstly, you can provide the application and :term:`instance namespace` as
-to ``include()`` when you construct your URL patterns. For example,::
+arguments to :func:`django.conf.urls.include()` when you construct your URL
+patterns. For example,::
 
     (r'^help/', include('apps.help.urls', namespace='foo', app_name='bar')),
 
-This will include the URLs defined in ``apps.help.urls`` into the application
+This will include the URLs defined in ``apps.help.urls`` into the
-namespace ``bar``, with the instance namespace ``foo``.
+:term:`application namespace` ``'bar'``, with the :term:`instance namespace`
+``'foo'``.
 
 Secondly, you can include an object that contains embedded namespace data. If
-you ``include()`` a ``patterns`` object, that object will be added to the
+you ``include()`` an object as returned by :func:`~django.conf.urls.patterns`,
-global namespace. However, you can also ``include()`` an object that contains
+the URLs contained in that object will be added to the global namespace.
-a 3-tuple containing::
+However, you can also ``include()`` a 3-tuple containing::
 
     (<patterns object>, <application namespace>, <instance namespace>)
 
 This will include the nominated URL patterns into the given application and
-instance namespace. For example, the ``urls`` attribute of Django's
+instance namespace.
-:class:`~django.contrib.admin.AdminSite` object returns a 3-tuple that contains
+
-all the patterns in an admin site, plus the name of the admin instance, and the
+For example, the Django Admin is deployed as instances of
-application namespace ``admin``.
+:class:`~django.contrib.admin.AdminSite`.  ``AdminSite`` objects have a ``urls``
+attribute: A 3-tuple that contains all the patterns in the corresponding admin
+site, plus the application namespace ``'admin'``, and the name of the admin
+instance. It is this ``urls`` attribute that you ``include()`` into your
+projects ``urlpatterns`` when you deploy an Admin instance.