Some tweaks to the staticfiles docs to clarify things for new users. Thanks Jannis and brutasse for review and discussion.

* Rearranged 'in a nutshell' usage docs to clarify app-dirs vs STATICFILES_DIRS, initially focus on the simplest path to working local dev, and remove the need for repetitive 'you don't need this in local dev' notes.
* Added docs on using staticfiles serve view for non-staticfiles (e.g. user-uploaded files).

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

docs/howto/static-files.txt

@@ -7,7 +7,7 @@ Managing static files
 .. versionadded:: 1.3
 
 Django developers mostly concern themselves with the dynamic parts of web
-applications -- the views and templates that render new for each request. But
+applications -- the views and templates that render anew for each request. But
 web applications have other parts: the static files (images, CSS,
 Javascript, etc.) that are needed to render a complete web page.
 
@@ -38,69 +38,30 @@ Using ``django.contrib.staticfiles``
 
 Here's the basic usage in a nutshell:
 
-    1. Put your static files somewhere that staticfiles will find it.
+    1. Put your static files somewhere that ``staticfiles`` will find them.
 
-       Most of the time this place will be in a ``static`` directory within
+       By default, this means within ``static/`` subdirectories of apps in your
-       your application, but it could also be a specific directory you've put
+       :setting:`INSTALLED_APPS`.
-       into your settings file. See the the documentation for the
-       :setting:`STATICFILES_DIRS` and :setting:`STATICFILES_FINDERS` settings
-       for details on where you can put static files.
 
-    2. Add some ``staticfiles``-related settings to your settings file.
+       Many projects will also have static assets that aren't tied to a
+       particular app; you can give ``staticfiles`` additional directories to
+       search via the :setting:`STATICFILES_DIRS` setting .
 
-       First, you'll need to make sure that ``django.contrib.staticfiles``
+       See the documentation for the :setting:`STATICFILES_FINDERS` setting for
-       is in your :setting:`INSTALLED_APPS`.
+       details on how ``staticfiles`` finds your files.
 
-       Next, you'll need to set the :setting:`STATIC_URL` setting, though
+    2. Make sure that ``django.contrib.staticfiles`` is in your
-       the default value (of ``'/static/'``) is perfect for local development.
+       :setting:`INSTALLED_APPS`.
-       See also the :setting:`STATIC_URL` documentation.
 
-       Then, edit the :setting:`STATIC_ROOT` setting to point to where
+       For :ref:`local development<staticfiles-development>`, if you are using
-       you'd like your static files collected at (when using the
+       :ref:`runserver<staticfiles-runserver>` or adding
-       :djadmin:`collectstatic`, see below). For example::
+       :ref:`staticfiles_urlpatterns<staticfiles-development>` to your URLconf,
+       you're done! Your static files will automatically be served at the
+       default :setting:`STATIC_URL` of ``/static/``.
 
-            STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
+    3. You'll probably need to refer to these files in your templates. The
-
+       easiest method is to use the included context processor which will allow
-       There are a number of other options available that let you control
+       template code like:
-       *how* static files are stored, where ``staticfiles`` searches for
-       files, and how files will be served; see :ref:`the staticfiles
-       settings reference <staticfiles-settings>` for details.
-
-    3. Run the :djadmin:`collectstatic` management command::
-
-            ./manage.py collectstatic
-
-       This'll churn through your static file storage and move them into the
-       directory given by :setting:`STATIC_ROOT`.
-
-       .. note:: This is **not necessary in local development** if you are
-           using :djadmin:`runserver<staticfiles-runserver>` or adding
-           ``staticfiles_urlpatterns`` to your URLconf; see below).
-
-    4. Deploy those files.
-
-       If you're using the built-in development server (the
-       :djadmin:`runserver` management command) and have the :setting:`DEBUG`
-       setting set to ``True``, your staticfiles will automatically be served
-       from :setting:`STATIC_URL` in development. You don't need to run
-       :djadmin:`collectstatic` in that case because ``staticfiles``'s
-       runserver command handle the serving of static files.
-
-       But, in case you are using some other server for local development,
-       you can quickly serve static files locally by adding::
-
-            from django.contrib.staticfiles.urls import staticfiles_urlpatterns
-            urlpatterns += staticfiles_urlpatterns()
-
-       to the bottom of your URLconf. See :ref:`staticfiles-development` for
-       details.
-
-       When it comes time to deploy to production, :ref:`staticfiles-production`
-       covers some common deployment strategies for static files.
-
-       However you choose to deploy those files, you'll probably need to refer
-       to them in your templates. The easiest method is to use the included
-       context processor which will allow template code like:
 
           .. code-block:: html+django
 
@@ -109,6 +70,31 @@ Here's the basic usage in a nutshell:
        See :ref:`staticfiles-in-templates` for more details, including an
        alternate method (using a template tag).
 
+When you're ready to move out of local development and deploy your project:
+
+    1. Set the :setting:`STATIC_URL` setting to the public URL for your static
+       files (in some cases, the default value of ``/static/`` may still be
+       fine).
+
+    2. Set the :setting:`STATIC_ROOT` setting to point to where you'd like your
+       static files collected to when you use the :djadmin:`collectstatic`
+       management command. For example::
+
+            STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
+
+    3. Run the :djadmin:`collectstatic` management command::
+
+            ./manage.py collectstatic
+
+       This'll churn through your static file storage and copy them into the
+       directory given by :setting:`STATIC_ROOT`.
+
+    4. Deploy those files by configuring your webserver of choice to serve the
+       files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
+
+       :ref:`staticfiles-production` covers some common deployment strategies
+       for static files.
+
 Those are the basics. For more details on common configuration options, read on;
 for a detailed reference of the settings, commands, and other bits included with
 the framework see :doc:`the staticfiles reference </ref/contrib/staticfiles>`.
@@ -123,7 +109,10 @@ the framework see :doc:`the staticfiles reference </ref/contrib/staticfiles>`.
    :setting:`MEDIA_URL` different from your :setting:`STATIC_ROOT` and
    :setting:`STATIC_URL`. You will need to arrange for serving of files in
    :setting:`MEDIA_ROOT` yourself; ``staticfiles`` does not deal with
-   user-uploaded files at all.
+   user-uploaded files at all. You can, however, use ``staticfiles``'
+   :func:`~django.contrib.staticfiles.views.serve` view for serving
+   :setting:`MEDIA_ROOT` in development; see
+   :ref:`staticfiles-serve-other-directories`.
 
 .. _staticfiles-in-templates:
 
@@ -221,7 +210,8 @@ developing locally. Thus, the ``staticfiles`` app ships with a
 development.
 
 This view is automatically enabled and will serve your static files at
-:setting:`STATIC_URL` when you use the built-in :djadmin:`runserver`.
+:setting:`STATIC_URL` when you use the built-in
+:ref:`runserver<staticfiles-runserver>` management command.
 
 To enable this view if you are using some other server for local development,
 you'll add a couple of lines to your URLconf. The first line goes at the top
@@ -275,7 +265,7 @@ If you want to serve your static files from the same server that's already
 serving your site, the basic outline gets modified to look something like:
 
     * Push your code up to the deployment server.
-    * On the server, run :djadmin:`collectstatic` to move all the static files
+    * On the server, run :djadmin:`collectstatic` to copy all the static files
       into :setting:`STATIC_ROOT`.
     * Point your web server at :setting:`STATIC_ROOT`. For example, here's
       :ref:`how to do this under Apache and mod_wsgi <serving-media-files>`.
@@ -426,8 +416,8 @@ you're upgrading from `django-staticfiles`_ < ``1.0``` (e.g. ``0.3.4``) to
       ``staticfiles.storage.StaticFileStorage`` to
       ``staticfiles.storage.StaticFilesStorage``
 
-    * If using :djadmin:`runserver` for local development (and the
+    * If using :ref:`runserver<staticfiles-runserver>` for local development
-      :setting:`DEBUG` setting is ``True``), you no longer need to add
+      (and the :setting:`DEBUG` setting is ``True``), you no longer need to add
       anything to your URLconf for serving static files in development.
 
 Learn more

docs/ref/contrib/staticfiles.txt

@@ -189,10 +189,12 @@ 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.
 
+.. _staticfiles-runserver:
+
 runserver
 ---------
 
-.. django-admin:: staticfiles-runserver
+.. django-admin:: runserver
 
 Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app
 is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static
@@ -317,3 +319,31 @@ already defined pattern list. Use it like this::
     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/``.
+
+.. _staticfiles-serve-other-directories:
+
+Serving other directories
+"""""""""""""""""""""""""
+
+There may be files other than your project's static assets that, for
+convenience, you'd like to have Django serve for you in local development. The
+:func:`~django.contrib.staticfiles.views.serve` view can be used to serve any
+directory you give it. (Again, this view is **not** hardened for production
+use, and should be used only as a development aid; you should serve these files
+in production using a real front-end webserver).
+
+The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`.
+``staticfiles`` is intended for static assets and has no built-in handling for
+user-uploaded files, but you can have Django serve your :setting:`MEDIA_ROOT`
+by appending something like this to your URLconf::
+
+   from django.conf import settings
+
+   if settings.DEBUG:
+       urlpatterns += patterns('django.contrib.staticfiles.views',
+           url(r'^media/(?P<path>.*)$', 'serve',
+               {'document_root': settings.MEDIA_ROOT}),
+       )
+
+This snippet assumes you've also set your :setting:`MEDIA_URL` (in development)
+to ``/media/``.