From ebce1b9a2b588b95e56a3719b3ac71a82834965a Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Sat, 11 Jul 2009 15:38:47 +0000
Subject: [PATCH] Fixed #11439 -- Added docs on including URL patterns as an
 iterable. Thanks to Ramiro Morales for the draft text.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@11221 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/topics/http/urls.txt | 36 +++++++++++++++++++++++++++++++-----
 1 file changed, 31 insertions(+), 5 deletions(-)

diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt
index 4248d4f02e..17978d4328 100644
--- a/docs/topics/http/urls.txt
+++ b/docs/topics/http/urls.txt
@@ -40,14 +40,14 @@ algorithm the system follows to determine which Python code to execute:
        this is the value of the ``ROOT_URLCONF`` setting, but if the incoming
        ``HttpRequest`` object has an attribute called ``urlconf``, its value
        will be used in place of the ``ROOT_URLCONF`` setting.
-    
+
     2. Django loads that Python module and looks for the variable
        ``urlpatterns``. This should be a Python list, in the format returned by
        the function ``django.conf.urls.defaults.patterns()``.
-    
+
     3. Django runs through each URL pattern, in order, and stops at the first
        one that matches the requested URL.
-    
+
     4. Once one of the regexes matches, Django imports and calls the given
        view, which is a simple Python function. The view gets passed an
        :class:`~django.http.HttpRequest` as its first argument and any values
@@ -263,8 +263,15 @@ value should suffice.
 include
 -------
 
-A function that takes a full Python import path to another URLconf that should
-be "included" in this place. See `Including other URLconfs`_ below.
+A function that takes a full Python import path to another URLconf module that
+should be "included" in this place.
+
+.. versionadded:: 1.1
+
+:meth:``include`` also accepts as an argument an iterable that returns URL
+patterns.
+
+See `Including other URLconfs`_ below.
 
 Notes on capturing text in URLs
 ===============================
@@ -391,6 +398,25 @@ Django encounters ``include()``, it chops off whatever part of the URL matched
 up to that point and sends the remaining string to the included URLconf for
 further processing.
 
+.. versionadded:: 1.1
+
+Another posibility 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 `patterns`_ instead. For example::
+
+    from django.conf.urls.defaults import *
+
+    extra_patterns = patterns('',
+        url(r'reports/(?P<id>\d+)/$', 'credit.views.report', name='credit-reports'),
+        url(r'charge/$', 'credit.views.charge', name='credit-charge'),
+    )
+
+    urlpatterns = patterns('',
+        url(r'^$',    'apps.main.views.homepage', name='site-homepage'),
+        (r'^help/',   include('apps.help.urls')),
+        (r'^credit/', include(extra_patterns)),
+    )
+
 .. _`Django Web site`: http://www.djangoproject.com/
 
 Captured parameters