Fixed #14524, #14582, #14617, #14665 and #14667 -- Tweaked staticfiles app.

* Updated StaticFilesHandler and AdminMediaHandler
  to make use of the 404 handler if needed.

* Updated runserver management command to serve static files
  only in DEBUG mode (or if specified the --insecure option)
  and if the staticfiles app is in INSTALLED_APPS. Also added
  an option to disable serving completely (--nostatic).

* Added check in debug mode if STATICFILES_* settings are
  different to MEDIA_* settings.

* Removed a faulty PendingDeprecationWarning in AdminMediaHandler
  that is triggered every time runserver is used.

* Fixed an issue with the modification time checks when
  running collectstatic.

* Extended and refined documentation.

Thanks to everyone for input, especially to Carl Meyer, Ted Kaemming and
Adam Vandenberg for patches.

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

3 files changed, 57 insertions, 16 deletions

diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
index 046e84f8ca..f82fd79024 100644
--- a/docs/ref/contrib/staticfiles.txt
+++ b/docs/ref/contrib/staticfiles.txt
@@ -34,13 +34,21 @@ STATICFILES_ROOT
 
 Default: ``''`` (Empty string)
 
-The absolute path to the directory that holds static files::
+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
@@ -51,7 +59,7 @@ 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/'
@@ -130,7 +138,7 @@ 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:: 
+.. note::
 
     When using the :class:`AppDirectoriesFinder` finder, make sure your apps can
     be found by Django's app loading mechanism. Simply include a ``models``
@@ -271,11 +279,13 @@ This view function serves static files in development.
     **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::
+This view is automatically enabled by :djadmin:`runserver` (with a
+:setting:`DEBUG` setting set to ``True``). To use the view with a different
+local development server, 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'),
@@ -292,8 +302,8 @@ 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/django-admin.txt b/docs/ref/django-admin.txt
index ea49e2372d..14fc69f99e 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -681,6 +681,31 @@ 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.
+
+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 acknoledge the fact that it's
+**grossly inefficient** and probably **insecure**. This is only intended for
+local development, and should **never be used in production**.
+
+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 78b5fd995e..2c338df6c7 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -53,7 +53,7 @@ Default: ``'/media/'``
 
 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 ``MEDIA_URL`` setting
+slash, and to have this be different from the :setting:`MEDIA_URL` setting
 (since the same URL cannot be mapped onto two different sets of
 files).
 
@@ -1104,8 +1104,12 @@ MEDIA_ROOT
 
 Default: ``''`` (Empty string)
 
-Absolute path to the directory that holds media for this installation.
-Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``.
+Absolute path to the directory that holds media for this installation, used
+for :doc:`managing stored files </topics/files>`.
+
+Example: ``"/home/media/media.lawrence.com/"``
+
+See also :setting:`MEDIA_URL`.
 
 .. setting:: MEDIA_URL
 
@@ -1114,15 +1118,15 @@ MEDIA_URL
 
 Default: ``''`` (Empty string)
 
-URL that handles the media served from ``MEDIA_ROOT``.
+URL that handles the media served from :setting:`MEDIA_ROOT`, used
+for :doc:`managing stored files </topics/files>`.
+
 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"``
-
-.. setting:: MIDDLEWARE_CLASSES
+ * Good: ``"http://www.example.com/static/"``
+ * Bad: ``"http://www.example.com/static"``
 
 MESSAGE_LEVEL
 -------------
@@ -1161,6 +1165,8 @@ Default::
 Sets the mapping of message levels to message tags. See the
 :doc:`messages documentation </ref/contrib/messages>` for more details.
 
+.. setting:: MIDDLEWARE_CLASSES
+
 MIDDLEWARE_CLASSES
 ------------------