From 091c9b530e3f27cadaaf952a304bfcb2fd639567 Mon Sep 17 00:00:00 2001
From: Jannis Leidel <jannis@leidel.info>
Date: Wed, 18 May 2011 09:51:24 +0000
Subject: [PATCH] Fixed #15983 and #16032 -- Another pass over the staticfiles
docs. Many thanks to Frank Wiles and EvilDMP.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16235 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
docs/howto/static-files.txt | 108 ++++++++++++++++---------------
docs/ref/contrib/staticfiles.txt | 2 +-
2 files changed, 58 insertions(+), 52 deletions(-)
diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt
index 633a663786..215b927f6f 100644
--- a/docs/howto/static-files.txt
+++ b/docs/howto/static-files.txt
@@ -34,85 +34,91 @@ single location that can easily be served in production.
Using ``django.contrib.staticfiles``
====================================
-Here's the basic usage in a nutshell:
+Basic usage
+-----------
- 1. Put your static files somewhere that ``staticfiles`` will find them.
+1. Put your static files somewhere that ``staticfiles`` will find them.
- By default, this means within ``static/`` subdirectories of apps in your
- :setting:`INSTALLED_APPS`.
+ By default, this means within ``static/`` subdirectories of apps in your
+ :setting:`INSTALLED_APPS`.
- 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 .
+ Your project will probably also have static assets that aren't tied to a
+ particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of
+ filesystem directories to check when loading static files. It's a search
+ path that is by default empty. See the :setting:`STATICFILES_DIRS` docs
+ how to extend this list of additional paths.
- See the documentation for the :setting:`STATICFILES_FINDERS` setting for
- details on how ``staticfiles`` finds your files.
+ Additionally, see the documentation for the :setting:`STATICFILES_FINDERS`
+ setting for details on how ``staticfiles`` finds your files.
- 2. Set the :setting:`STATIC_URL` setting to the URL you want to use
- for pointing to your static files, e.g.::
+2. Make sure that ``django.contrib.staticfiles`` is included in your
+ :setting:`INSTALLED_APPS`.
- STATIC_URL = '/static/'
+ 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 with the setup -- your static files will
+ automatically be served at the default (for
+ :djadmin:`newly created<startproject>` projects) :setting:`STATIC_URL`
+ of ``/static/``.
- In projects freshly created with the :djadmin:`startproject`
- management command this will be preset to ``'/static/'``.
+3. You'll probably need to refer to these files in your templates. The
+ easiest method is to use the included context processor which allows
+ template code like:
- 3. Make sure that ``django.contrib.staticfiles`` is in your
- :setting:`INSTALLED_APPS`.
+ .. code-block:: html+django
- 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
- :setting:`STATIC_URL` you specified in step 2.
+ <img src="{{ STATIC_URL }}images/hi.jpg />
- 4. 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:
+ See :ref:`staticfiles-in-templates` for more details, including an
+ alternate method using a template tag.
- .. code-block:: html+django
-
- <img src="{{ STATIC_URL }}images/hi.jpg />
-
- See :ref:`staticfiles-in-templates` for more details, including an
- alternate method (using a template tag).
+Deploying static files in a nutshell
+------------------------------------
When you're ready to move out of local development and deploy your project:
- 1. 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::
+1. Set the :setting:`STATIC_URL` setting to the public URL for your static
+ files (in most cases, the default value of ``/static/`` is just fine).
- STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
+2. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path
+ you'd like your static files collected to when you use the
+ :djadmin:`collectstatic` management command. For example::
- 2. Run the :djadmin:`collectstatic` management command::
+ STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
- ./manage.py collectstatic
+3. Run the :djadmin:`collectstatic` management command::
- This'll churn through your static file storage and copy them into the
- directory given by :setting:`STATIC_ROOT`.
+ ./manage.py collectstatic
- 3. Deploy those files by configuring your webserver of choice to serve the
- files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
+ This'll churn through your static file storage and copy them into the
+ directory given by :setting:`STATIC_ROOT`.
- :ref:`staticfiles-production` covers some common deployment strategies
- for static files.
+4. Deploy those files by configuring your webserver of choice to serve the
+ files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
-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>`.
+ :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>`.
.. note::
In previous versions of Django, it was common to place static assets in
- :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both at
- :setting:`MEDIA_URL`. Part of the purpose of introducing the ``staticfiles``
- app is to make it easier to keep static files separate from user-uploaded
- files. For this reason, you need to make your :setting:`MEDIA_ROOT` and
+ :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both
+ at :setting:`MEDIA_URL`. Part of the purpose of introducing the
+ ``staticfiles`` app is to make it easier to keep static files separate
+ from user-uploaded files.
+
+ For this reason, you need to make your :setting:`MEDIA_ROOT` and
: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. You can, however, use
- :func:`~django.views.static.serve` view for serving :setting:`MEDIA_ROOT`
+ :func:`django.views.static.serve` view for serving :setting:`MEDIA_ROOT`
in development; see :ref:`staticfiles-other-directories`.
.. _staticfiles-in-templates:
@@ -303,7 +309,7 @@ development::
.. note::
- The helper function will only be operational in debug mode and if
+ This helper function will only be operational in debug mode and if
the given prefix is local (e.g. ``/static/``) and not a URL (e.g.
``http://static.example.com/``).
diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
index b06620d085..eb8bbec105 100644
--- a/docs/ref/contrib/staticfiles.txt
+++ b/docs/ref/contrib/staticfiles.txt
@@ -296,7 +296,7 @@ primary URL configuration::
url(r'^static/(?P<path>.*)$', 'serve'),
)
-Note, the begin of the pattern (``r'^static/'``) should be your
+Note, the beginning of the pattern (``r'^static/'``) should be your
:setting:`STATIC_URL` setting.
Since this is a bit finicky, there's also a helper function that'll do this for you: