From 0bf5fbfa76544fe921d051619127748ae10237bd Mon Sep 17 00:00:00 2001
From: Carl Meyer <carl@oddbird.net>
Date: Mon, 31 Jan 2011 22:06:53 +0000
Subject: 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      | 106 ++++++++++++++++++---------------------
 docs/ref/contrib/staticfiles.txt |  32 +++++++++++-
 2 files changed, 79 insertions(+), 59 deletions(-)

(limited to 'docs')

diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt
index e5b97403a1..94e04bb738 100644
--- a/docs/howto/static-files.txt
+++ b/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::
-
-            ./manage.py collectstatic
+    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:
 
-       This'll churn through your static file storage and move them into the
-       directory given by :setting:`STATIC_ROOT`.
+          .. code-block:: html+django
 
-       .. 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).
+               <img src="{{ STATIC_URL }}images/hi.jpg />
 
-    4. Deploy those files.
+       See :ref:`staticfiles-in-templates` for more details, including an
+       alternate method (using a template tag).
 
-       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.
+When you're ready to move out of local development and deploy your project:
 
-       But, in case you are using some other server for local development,
-       you can quickly serve static files locally by adding::
+    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).
 
-            from django.contrib.staticfiles.urls import staticfiles_urlpatterns
-            urlpatterns += staticfiles_urlpatterns()
+    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::
 
-       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
diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
index 2b8fee1200..4944c284d2 100644
--- a/docs/ref/contrib/staticfiles.txt
+++ b/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/``.
-- 
cgit v1.3