Fixed #14693, #14709 -- Backwards incompatible change to rectify the confusion around the STATICFILES_URL and STATICFILES_ROOT settings.

  * Two new global settings that will be used by -- **but are not limited to** -- the staticfiles app: STATIC_ROOT and STATIC_URL.

  * Moving the 'django.contrib.staticfiles.templatetags.staticfiles' template tag to the core ('django.templatetags.static') and renaming it to 'get_static_prefix'.

  * Moving the context processor 'django.contrib.staticfiles.context_processors.staticfiles' to the core ('django.core.context_processors.static') and renaming it to 'static'.

  * Paths in media definitions will use STATIC_URL as the prefix if the value is not None, and falls back to the previously used MEDIA_URL.

Thanks again to the community for constructive criticism and Carl and Russ for sanity-inducing discussions on IRC.

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

4 files changed, 126 insertions, 98 deletions

diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
index f82fd79024..2cd2282f4e 100644
--- a/docs/ref/contrib/staticfiles.txt
+++ b/docs/ref/contrib/staticfiles.txt
@@ -23,48 +23,11 @@ Settings
 
 .. highlight:: python
 
-The following settings control the behavior of the staticfiles 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 the :djadmin:`collectstatic` management
-command will collect static files into, for serving from
-:setting:`STATICFILES_URL`::
-
-   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.
-
-This is not a place to store your static files permanently under version
-control; you should do that in directories that will be found by your
-:setting:`STATICFILES_FINDERS` (by default, per-app ``static/`` subdirectories,
-and any directories you include in :setting:`STATICFILES_DIRS`). Files from
-those locations will be collected into :setting:`STATICFILES_ROOT`.
-
-.. 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://static.example.com/'
+.. note::
 
-This should **always** have a trailing slash.
+    The following settings control the behavior of the staticfiles app.
+    Configuring the global settings :setting:`STATIC_ROOT` and
+    :setting:`STATIC_URL` is **required**.
 
 .. setting:: STATICFILES_DIRS
 
@@ -98,7 +61,7 @@ tuples, e.g.::
 
 With this configuration, the :djadmin:`collectstatic` management command would
 for example collect the stats files in a ``'downloads'`` directory. So
-assuming you have :setting:`STATICFILES_URL` set ``'/static/'``, this would
+assuming you have :setting:`STATIC_URL` set ``'/static/'``, this would
 allow you to refer to the file ``'/opt/webfiles/stats/polls_20101022.tar.gz'``
 with ``'/static/downloads/polls_20101022.tar.gz'`` in your templates.
 
@@ -153,14 +116,14 @@ Management Commands
 
 .. highlight:: console
 
-``django.contrib.staticfiles`` exposes two management commands.
+``django.contrib.staticfiles`` exposes three management commands.
 
 collectstatic
 -------------
 
 .. django-admin:: collectstatic
 
-Collects the static files into :setting:`STATICFILES_ROOT`.
+Collects the static files into :setting:`STATIC_ROOT`.
 
 Duplicate file names are by default resolved in a similar way to how template
 resolution works: the file that is first found in one of the specified
@@ -218,44 +181,76 @@ for each relative path, use the ``--first`` option::
 This is a debugging aid; it'll show you exactly which static file will be
 collected for a given path.
 
+runserver
+---------
+
+Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app
+is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static
+files and the following new options.
+
+.. django-admin-option:: --nostatic
+
+Use the ``--nostatic`` option to disable serving of static files with the
+:doc:`staticfiles </ref/contrib/staticfiles>` app entirely. This option is
+only available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
+in your project's :setting:`INSTALLED_APPS` setting.
+
+Example usage::
+
+    django-admin.py runserver --nostatic
+
+.. django-admin-option:: --insecure
+
+Use the ``--insecure`` option to force serving of static files with the
+:doc:`staticfiles </ref/contrib/staticfiles>` app even if the :setting:`DEBUG`
+setting is ``False``. By using this you acknowledge the fact that it's
+**grossly inefficient** and probably **insecure**. This is only intended for
+local development, should **never be used in production** and is only
+available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
+in your project's :setting:`INSTALLED_APPS` setting.
+
+Example usage::
+
+    django-admin.py runserver --insecure
+
 .. currentmodule:: None
 
 Other Helpers
 =============
 
-The ``staticfiles`` context processor
--------------------------------------
+The ``static`` context processor
+--------------------------------
 
-.. function:: django.contrib.staticfiles.context_processors.staticfiles
+.. function:: django.core.context_processors.static
 
-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.
+This context processor adds the :setting:`STATIC_URL` into each template
+context as the variable ``{{ STATIC_URL }}``. To use it, make sure that
+``'django.core.context_processors.static'`` 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
+.. templatetag:: get_static_prefix
 
-The ``get_staticfiles_prefix`` templatetag
-==========================================
+The ``get_static_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
+more control over exactly where and how :setting:`STATIC_URL` is injected
+into the template, you can use the :ttag:`get_static_prefix` template tag
 instead::
 
-    {% load staticfiles %}
-    <img src="{% get_staticfiles_prefix %}images/hi.jpg" />
+    {% load static %}
+    <img src="{% get_static_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 %}
+    {% load static %}
+    {% get_static_prefix as STATIC_PREFIX %}
 
     <img src="{{ STATIC_PREFIX }}images/hi.jpg" />
     <img src="{{ STATIC_PREFIX }}images/hi2.jpg" />
@@ -292,7 +287,7 @@ primary URL configuration::
        )
 
 Note, the begin of the pattern (``r'^static/'``) should be your
-:setting:`STATICFILES_URL` setting.
+:setting:`STATIC_URL` setting.
 
 Since this is a bit finicky, there's also a helper function that'll do this for you:
 
@@ -307,3 +302,8 @@ already defined pattern list. Use it like this::
 
    urlpatterns += staticfiles_urlpatterns()
 
+.. warning::
+
+    This helper function will only work if :setting:`DEBUG` is ``True``
+    and your :setting:`STATIC_URL` setting is neither empty nor a full
+    URL such as ``http://static.example.com/``.
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 43e55acab2..ea49e2372d 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -681,35 +681,6 @@ Example usage::
 
     django-admin.py runserver --noreload
 
-.. django-admin-option:: --nostatic
-
-Use the ``--nostatic`` option to disable serving of static files with the
-:doc:`staticfiles </ref/contrib/staticfiles>` app entirely. This option is
-only available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
-in your project's :setting:`INSTALLED_APPS` setting.
-
-Example usage::
-
-    django-admin.py runserver --nostatic
-
-.. django-admin-option:: --insecure
-
-Use the ``--insecure`` option to force serving of static files with the
-:doc:`staticfiles </ref/contrib/staticfiles>` app even if the :setting:`DEBUG`
-setting is ``False``. By using this you acknowledge the fact that it's
-**grossly inefficient** and probably **insecure**. This is only intended for
-local development, should **never be used in production** and is only
-available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
-in your project's :setting:`INSTALLED_APPS` setting.
-
-See the :doc:`reference documentation of the app </ref/contrib/staticfiles>`
-for more details and learn how to :doc:`manage and deploy static files
-</howto/static-files>` correctly.
-
-Example usage::
-
-    django-admin.py runserver --insecure
-
 Examples of using different ports and addresses
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 95e6861bb6..7f4157c363 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -53,10 +53,10 @@ Default: ``'/static/admin/'``
 
 The URL prefix for admin media -- CSS, JavaScript and images used by the Django
 administrative interface. Make sure to use a trailing slash, and to have this be
-different from the :setting:``MEDIA_URL`` setting (since the same URL cannot be
+different from the :setting:`MEDIA_URL` setting (since the same URL cannot be
 mapped onto two different sets of files). For integration with :doc:`staticfiles
 </ref/contrib/staticfiles>`, this should be the same as
-:setting:`STATICFILES_URL` followed by ``'admin/'``.
+:setting:`STATIC_URL` followed by ``'admin/'``.
 
 .. setting:: ADMINS
 
@@ -1122,12 +1122,12 @@ Default: ``''`` (Empty string)
 URL that handles the media served from :setting:`MEDIA_ROOT`, used
 for :doc:`managing stored files </topics/files>`.
 
-Example: ``"http://media.lawrence.com"``
+Example: ``"http://media.lawrence.com/"``
 
 Note that this should have a trailing slash if it has a path component.
 
- * Good: ``"http://www.example.com/static/"``
- * Bad: ``"http://www.example.com/static"``
+ * Good: ``"http://www.example.com/media/"``
+ * Bad: ``"http://www.example.com/media"``
 
 MESSAGE_LEVEL
 -------------
@@ -1486,6 +1486,49 @@ See :doc:`/ref/contrib/sites`.
 
 .. _site framework docs: ../sites/
 
+.. setting:: STATIC_ROOT
+
+STATIC_ROOT
+-----------
+
+Default: ``''`` (Empty string)
+
+The absolute path to the directory that contains static content.
+
+Example: ``"/home/example.com/static/"``
+
+When using the :djadmin:`collectstatic` management command of the optional,
+:doc:`staticfiles</ref/contrib/staticfiles>` app this will be used to collect
+static files into and served from :setting:`STATIC_URL`.
+
+In that case this is a **required setting**, unless you've overridden
+:setting:`STATICFILES_STORAGE` and are using a custom storage backend.
+
+This is not a place to store your static files permanently under version
+control; you should do that in directories that will be found by your
+:setting:`STATICFILES_FINDERS` (by default, per-app ``static/`` subdirectories,
+and any directories you include in :setting:`STATICFILES_DIRS`). Files from
+those locations will be collected into :setting:`STATIC_ROOT`.
+
+See :doc:`/ref/contrib/staticfiles` and :setting:`STATIC_URL`.
+
+.. setting:: STATIC_URL
+
+STATIC_URL
+----------
+
+Default: ``None``
+
+URL that handles the files served from :setting:`STATIC_ROOT`.
+
+Example: ``"/site_media/static/"`` or ``"http://static.example.com/"``
+
+If not ``None``, this will be used as the base path for
+:ref:`media definitions<form-media-paths>` and the
+:doc:`staticfiles app</ref/contrib/staticfiles>`.
+
+See :setting:`STATIC_ROOT`.
+
 .. setting:: TEMPLATE_CONTEXT_PROCESSORS
 
 TEMPLATE_CONTEXT_PROCESSORS
@@ -1496,7 +1539,8 @@ Default::
     ("django.contrib.auth.context_processors.auth",
     "django.core.context_processors.debug",
     "django.core.context_processors.i18n",
-    "django.contrib.staticfiles.context_processors.staticfiles",
+    "django.core.context_processors.media",
+    "django.core.context_processors.static",
     "django.contrib.messages.context_processors.messages")
 
 A tuple of callables that are used to populate the context in ``RequestContext``.
@@ -1513,6 +1557,10 @@ of items to be merged into the context.
     ``django.core.context_processors.auth`` to
     ``django.contrib.auth.context_processors.auth``.
 
+.. versionadded:: 1.3
+    The ``django.core.context_processors.static`` context processor
+    was added in this release.
+
 .. setting:: TEMPLATE_DEBUG
 
 TEMPLATE_DEBUG
diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index aa4951eebe..e02debe39b 100644
--- a/docs/ref/templates/api.txt
+++ b/docs/ref/templates/api.txt
@@ -312,8 +312,8 @@ and return a dictionary of items to be merged into the context. By default,
     "django.core.context_processors.debug",
     "django.core.context_processors.i18n",
     "django.core.context_processors.media",
-    "django.contrib.messages.context_processors.messages",
-    "django.contrib.staticfiles.context_processors.staticfiles")
+    "django.core.context_processors.static",
+    "django.contrib.messages.context_processors.messages")
 
 .. versionadded:: 1.2
    In addition to these, ``RequestContext`` always uses
@@ -435,6 +435,15 @@ 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.
 
+django.core.context_processors.static
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.3
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain a variable ``STATIC_URL``, providing the
+value of the :setting:`STATIC_URL` setting.
+
 django.core.context_processors.csrf
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~