Some tweaks to the staticfiles docs to clarify things for new users. Thanks…

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,76 +38,62 @@ 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
-       your application, but it could also be a specific directory you've put
-       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.
+       By default, this means within ``static/`` subdirectories of apps in your
+       :setting:`INSTALLED_APPS`.
 
-    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``
-       is in your :setting:`INSTALLED_APPS`.
+       See the documentation for the :setting:`STATICFILES_FINDERS` setting for
+       details on how ``staticfiles`` finds your files.
 
-       Next, you'll need to set the :setting:`STATIC_URL` setting, though
-       the default value (of ``'/static/'``) is perfect for local development.
-       See also the :setting:`STATIC_URL` documentation.
+    2. Make sure that ``django.contrib.staticfiles`` is in your
+       :setting:`INSTALLED_APPS`.
 
-       Then, edit the :setting:`STATIC_ROOT` setting to point to where
-       you'd like your static files collected at (when using the
-       :djadmin:`collectstatic`, see below). For example::
+       For :ref:`local development<staticfiles-development>`, if you are using
+       :ref:`runserver<staticfiles-runserver>` or adding
+       :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"
-
-       There are a number of other options available that let you control
-       *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::
+    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
+       template code like:
 
-            ./manage.py collectstatic
+          .. code-block:: html+django
 
-       This'll churn through your static file storage and move them into the
-       directory given by :setting:`STATIC_ROOT`.
+               <img src="{{ STATIC_URL }}images/hi.jpg />
 
-       .. 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).
+       See :ref:`staticfiles-in-templates` for more details, including an
+       alternate method (using a template tag).
 
-    4. Deploy those files.
+When you're ready to move out of local development and deploy your project:
 
-       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.
+    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).
 
-       But, in case you are using some other server for local development,
-       you can quickly serve static files locally by adding::
+    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::
 
-            from django.contrib.staticfiles.urls import staticfiles_urlpatterns
-            urlpatterns += staticfiles_urlpatterns()
-
-       to the bottom of your URLconf. See :ref:`staticfiles-development` for
-       details.
+            STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
 
-       When it comes time to deploy to production, :ref:`staticfiles-production`
-       covers some common deployment strategies for static files.
+    3. Run the :djadmin:`collectstatic` management command::
 
-       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:
+            ./manage.py collectstatic
 
-          .. code-block:: html+django
+       This'll churn through your static file storage and copy them into the
+       directory given by :setting:`STATIC_ROOT`.
 
-               <img src="{{ STATIC_URL }}images/hi.jpg />
+    4. Deploy those files by configuring your webserver of choice to serve the
+       files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
 
-       See :ref:`staticfiles-in-templates` for more details, including an
-       alternate method (using a template tag).
+       :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
@@ -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
-      :setting:`DEBUG` setting is ``True``), you no longer need to add
+    * If using :ref:`runserver<staticfiles-runserver>` for local development
+      (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/``.