Fixed #12323 and #11582 -- Extended the ability to handle static files. Thanks to all for helping with the original app, the patch, documentation and general support.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14293 bcc190cf-cafb-0310-a4f2-bffc1f526a37

4 files changed, 293 insertions, 2 deletions

diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt
index 90edf72c94..5e308dc469 100644
--- a/docs/ref/contrib/index.txt
+++ b/docs/ref/contrib/index.txt
@@ -38,6 +38,7 @@ those packages have.
    redirects
    sitemaps
    sites
+   staticfiles
    syndication
    webdesign
 
diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
new file mode 100644
index 0000000000..0a330a0fce
--- /dev/null
+++ b/docs/ref/contrib/staticfiles.txt
@@ -0,0 +1,283 @@
+===================
+The staticfiles app
+===================
+
+.. module:: django.contrib.staticfiles
+   :synopsis: An app for handling static files.
+
+.. versionadded:: 1.3
+
+``django.contrib.staticfiles`` collects media from each of your applications
+(and any other places you specify) into a single location that can easily be
+served in production.
+
+.. seealso::
+
+    For an introduction to the static files app and some usage examples, see
+    :doc:`/howto/static-files`.
+
+.. _staticfiles-settings:
+
+Settings
+========
+
+.. highlight:: python
+
+The following settings control the behavior of the static files app. Only
+:setting:`STATICFILES_ROOT` is required, but you'll probably also need to
+configure :setting:`STATICFILES_URL` as well.
+
+.. setting:: STATICFILES_ROOT
+
+STATICFILES_ROOT
+----------------
+
+Default: ``''`` (Empty string)
+
+The absolute path to the directory that holds static files::
+
+   STATICFILES_ROOT = "/home/example.com/static/"
+
+This is a **required setting** unless you've overridden
+:setting:`STATICFILES_STORAGE` and are using a custom storage backend.
+
+.. setting:: STATICFILES_URL
+
+STATICFILES_URL
+---------------
+
+Default: ``'/static/'``
+
+The URL that handles the files served from :setting:`STATICFILES_ROOT`, e.g.::
+
+    STATICFILES_URL = '/site_media/static/'
+   
+... or perhaps::
+
+    STATICFILES_URL = 'http://media.exmaple.com/'
+
+This should **always** have a trailing slash.
+
+.. setting:: STATICFILES_DIRS
+
+STATICFILES_DIRS
+----------------
+
+Default: ``[]``
+
+This setting defines the additional locations the staticfiles app will traverse
+if the :class:`FileSystemFinder` finder is enabled, e.g. if you use the
+:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
+static file serving view.
+
+It should be defined as a sequence of ``(prefix, path)`` tuples, e.g.::
+
+   STATICFILES_DIRS = (
+       ('', '/home/special.polls.com/polls/media'),
+       ('', '/home/polls.com/polls/media'),
+       ('common', '/opt/webfiles/common'),
+   )
+
+.. setting:: STATICFILES_STORAGE
+
+STATICFILES_STORAGE
+-------------------
+
+Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'``
+
+The file storage engine to use when collecting static files with the
+:djadmin:`collectstatic` management command.
+
+For an example, see :ref:`staticfiles-from-cdn`.
+
+.. setting:: STATICFILES_FINDERS
+
+STATICFILES_FINDERS
+-------------------
+
+Default::
+
+    ("django.contrib.staticfiles.finders.FileSystemFinder",
+     "django.contrib.staticfiles.finders.AppDirectoriesFinder")
+
+The list of finder backends that know how to find static files in
+various locations.
+
+The default will find files stored in the :setting:`STATICFILES_DIRS` setting
+(using :class:`django.contrib.staticfiles.finders.FileSystemFinder`) and in a
+``static`` subdirectory of each app (using
+:class:`django.contrib.staticfiles.finders.AppDirectoriesFinder`)
+
+One finder is disabled by default:
+:class:`django.contrib.staticfiles.finders.DefaultStorageFinder`. If added to
+your :setting:`STATICFILES_FINDERS` setting, it will look for static files in
+the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE`
+setting.
+
+.. note:: 
+
+    When using the :class:AppDirectoriesFinder` finder, make sure your apps can
+    be found by Django's app loading mechanism. Simply include a ``models``
+    module (an empty ``models.py`` file suffices) and add the app to the
+    :setting:`INSTALLED_APPS` setting of your site.
+
+Static file finders are currently considered a private interface, and this
+interface is thus undocumented.
+
+Management Commands
+===================
+
+.. highlight:: console
+
+``django.contrib.staticfiles`` exposes two management commands.
+
+collectstatic
+-------------
+
+.. django-admin:: collectstatic
+
+Collects the static files into :setting:`STATICFILES_ROOT`.
+
+Duplicate file names are resolved in a similar way to how template resolution
+works: files from apps later in :setting:`INSTALLED_APPS` overwrite those from
+earlier apps, and files from storage directories later in
+:setting:`STATICFILES_DIRS` overwrite those from earlier. If you're confused,
+the :djadmin:`findstatic` command can help show you where 
+
+Files are searched by using the :ref:`enabled finders
+<staticfiles-finders>`. The default is to look in all locations defined in
+:ref:`staticfiles-dirs` and in the ``media`` directory of apps specified by the
+:setting:`INSTALLED_APPS` setting.
+
+Some commonly used options are:
+
+``--noinput``
+    Do NOT prompt the user for input of any kind.
+
+``-i PATTERN`` or ``--ignore=PATTERN``
+    Ignore files or directories matching this glob-style pattern. Use multiple
+    times to ignore more.
+
+``-n`` or ``--dry-run``
+    Do everything except modify the filesystem.
+
+``-l`` or ``--link``
+    Create a symbolic link to each file instead of copying.
+
+``--no-default-ignore``
+    Don't ignore the common private glob-style patterns ``'CVS'``, ``'.*'``
+    and ``'*~'``.
+
+For a full list of options, refer to the commands own help by running::
+
+   $ python manage.py collectstatic --help
+
+findstatic
+----------
+
+.. django-admin:: findstatic
+
+Searches for one or more relative paths with the enabled finders.
+
+For example::
+
+   $ python manage.py findstatic css/base.css admin/js/core.js
+   /home/special.polls.com/core/media/css/base.css
+   /home/polls.com/core/media/css/base.css
+   /home/polls.com/src/django/contrib/admin/media/js/core.js
+
+By default, all matching locations are found. To only return the first match
+for each relative path, use the ``--first`` option::
+
+   $ python manage.py findstatic css/base.css --first
+   /home/special.polls.com/core/media/css/base.css
+   
+This is a debugging aid; it'll show you exactly which static file will be
+collected for a given path.
+
+Other Helpers
+=============
+
+The ``media`` context processor
+-------------------------------
+
+.. function:: django.contrib.staticfiles.context_processors.staticfiles
+
+This context processor adds the :setting:`STATICFILES_URL` into each template
+context as the variable ``{{ STATICFILES_URL }}``. To use it, make sure that
+``'django.contrib.staticfiles.context_processors.staticfiles'`` appears
+somewhere in your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
+
+Remember, only templates rendered with :class:`~django.template.RequestContext`
+will have acces to the data provided by this (and any) context processor.
+
+.. templatetag:: get_staticfiles_prefix
+
+The ``get_staticfiles_prefix`` templatetag
+==========================================
+
+.. highlight:: html+django
+
+If you're not using :class:`~django.template.RequestContext`, or if you need
+more control over exactly where and how :setting:`STATICFILES_URL` is injected
+into the template, you can use the :ttag:`get_staticfiles_prefix` template tag
+instead::
+
+    {% load staticfiles %}
+    <img src="{% get_staticfiles_prefix %}images/hi.jpg" />
+
+There's also a second form you can use to avoid extra processing if you need the
+value multiple times::
+
+    {% load staticfiles %}
+    {% get_staticfiles_prefix as STATIC_PREFIX %}
+
+    <img src="{{ STATIC_PREFIX }}images/hi.jpg" />
+    <img src="{{ STATIC_PREFIX }}images/hi2.jpg" />
+
+.. _staticfiles-development-view:
+
+Static file development view
+----------------------------
+
+.. highlight:: python
+
+.. function:: django.contrib.staticfiles.views.serve(request, path)
+
+This view function serves static media in in development.
+
+.. warning::
+
+    This view will only work if :setting:`DEBUG` is ``True``.
+
+    That's because this view is **grossly inefficient** and probably
+    **insecure**. This is only intended for local development, and should
+    **never be used in production**.
+
+To use the view, add the following snippet to the end of your primary URL
+configuration::
+
+   from django.conf import settings
+   
+   if settings.DEBUG:
+       urlpatterns = patterns('django.contrib.staticfiles.views',
+           url(r'^static/(?P<path>.*)$', 'serve'),
+       )
+
+Note, the begin of the pattern (``r'^static/'``) should be your
+:setting:`STATICFILES_URL` setting.
+
+Since this is a bit finicky, there's also a helper function that'll do this for you:
+
+.. function:: django.contrib.staticfiles.urls.staticfiles_urlpatterns()
+
+This will return the proper URL pattern for serving static files to your
+already defined pattern list. Use it like this::
+
+   from django.contrib.staticfiles.urls import staticfiles_urlpatterns
+   
+   # ... the rest of your URLconf here ...
+   
+   urlpatterns += staticfiles_urlpatterns()
+
+
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 6ad5af9301..f0b4c562da 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1482,7 +1482,7 @@ Default::
     ("django.contrib.auth.context_processors.auth",
     "django.core.context_processors.debug",
     "django.core.context_processors.i18n",
-    "django.core.context_processors.media",
+    "django.contrib.staticfiles.context_processors.staticfiles",
     "django.contrib.messages.context_processors.messages")
 
 A tuple of callables that are used to populate the context in ``RequestContext``.
diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index 2ac4e653c4..4589084ac2 100644
--- a/docs/ref/templates/api.txt
+++ b/docs/ref/templates/api.txt
@@ -289,6 +289,8 @@ you'll see below.
 Subclassing Context: RequestContext
 -----------------------------------
 
+.. class:: django.template.RequestContext
+
 Django comes with a special ``Context`` class,
 ``django.template.RequestContext``, that acts slightly differently than the
 normal ``django.template.Context``. The first difference is that it takes an
@@ -309,7 +311,7 @@ and return a dictionary of items to be merged into the context. By default,
     ("django.contrib.auth.context_processors.auth",
     "django.core.context_processors.debug",
     "django.core.context_processors.i18n",
-    "django.core.context_processors.media",
+    "django.contrib.staticfiles.context_processors.staticfiles",
     "django.contrib.messages.context_processors.messages")
 
 .. versionadded:: 1.2
@@ -432,6 +434,11 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
 ``RequestContext`` will contain a variable ``MEDIA_URL``, providing the
 value of the :setting:`MEDIA_URL` setting.
 
+.. versionchanged:: 1.3
+    This context processor has been moved to the new :ref:`staticfiles` app.
+    Please use the new ``django.contrib.staticfiles.context_processors.staticfiles``
+    context processor.
+
 django.core.context_processors.csrf
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~