Reworded parts of the staticfiles documentation after receiving various user feedback. Thanks, all!

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

2 files changed, 32 insertions, 20 deletions

diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
index 57f0d1cac5..2b8fee1200 100644
--- a/docs/ref/contrib/staticfiles.txt
+++ b/docs/ref/contrib/staticfiles.txt
@@ -50,20 +50,29 @@ your additional files directory(ies) e.g.::
         "/opt/webfiles/common",
     )
 
+Prefixes (optional)
+"""""""""""""""""""
+
 In case you want to refer to files in one of the locations with an additional
 namespace, you can **optionally** provide a prefix as ``(prefix, path)``
 tuples, e.g.::
 
     STATICFILES_DIRS = (
-        "/home/polls.com/polls/static",
+        # ...
         ("downloads", "/opt/webfiles/stats"),
     )
 
-With this configuration, the :djadmin:`collectstatic` management command would
-for example collect the stats files in a ``'downloads'`` directory. So
-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.
+Example:
+
+Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the
+:djadmin:`collectstatic` management command would collect the "stats" files
+in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`.
+
+This would allow you to refer to the local file
+``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with
+``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.::
+
+    <a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">
 
 .. setting:: STATICFILES_STORAGE
 
@@ -183,6 +192,8 @@ collected for a given path.
 runserver
 ---------
 
+.. django-admin:: staticfiles-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.
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 5140d3519d..d21c3ab044 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1628,24 +1628,25 @@ STATIC_ROOT
 
 Default: ``''`` (Empty string)
 
-The absolute path to the directory that contains static content.
+The absolute path to the directory that contains static files.
 
 Example: ``"/home/example.com/static/"``
 
-When using the :djadmin:`collectstatic` management command of the optional,
-:doc:`staticfiles</ref/contrib/staticfiles>` app this will be used to collect
-static files into and served from :setting:`STATIC_URL`.
+If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
+(default) this will be used as the directory which the
+:djadmin:`collectstatic` management command collects static files in. See
+the howto on :doc:`managing static files</howto/static-files>` for more
+details about usage.
 
-In that case this is a **required setting**, unless you've overridden
-:setting:`STATICFILES_STORAGE` and are using a custom storage backend.
+.. warning:: This is not a place to store your static files permanently;
+    you should do that in directories that will be found by
+    :doc:`staticfiles</ref/contrib/staticfiles>`'s
+    :setting:`finders<STATICFILES_FINDERS>`, which by default, are
+    ``'static'`` app sub directories and any directories you include in
+    the :setting:`STATICFILES_DIRS`).
 
-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:`STATIC_ROOT`.
-
-See :doc:`/ref/contrib/staticfiles` and :setting:`STATIC_URL`.
+See :doc:`staticfiles reference</ref/contrib/staticfiles>` and
+:setting:`STATIC_URL`.
 
 .. setting:: STATIC_URL
 
@@ -1654,7 +1655,7 @@ STATIC_URL
 
 Default: ``None``
 
-URL that handles the files served from :setting:`STATIC_ROOT`.
+URL to use when referring to static files located in :setting:`STATIC_ROOT`.
 
 Example: ``"/site_media/static/"`` or ``"http://static.example.com/"``