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

1 files changed, 61 insertions, 61 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/``.