Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #15983 and #16032 -- Another pass over the staticfiles docs. Ma…

…ny thanks to Frank Wiles and EvilDMP.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16235 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 091c9b530e3f27cadaaf952a304bfcb2fd639567 1 parent ee8f6ca
Jannis Leidel authored May 18, 2011
108  docs/howto/static-files.txt
@@ -34,85 +34,91 @@ single location that can easily be served in production.
34 34
 Using ``django.contrib.staticfiles``
35 35
 ====================================
36 36
 
37  
-Here's the basic usage in a nutshell:
  37
+Basic usage
  38
+-----------
38 39
 
39  
-    1. Put your static files somewhere that ``staticfiles`` will find them.
  40
+1. Put your static files somewhere that ``staticfiles`` will find them.
40 41
 
41  
-       By default, this means within ``static/`` subdirectories of apps in your
42  
-       :setting:`INSTALLED_APPS`.
  42
+   By default, this means within ``static/`` subdirectories of apps in your
  43
+   :setting:`INSTALLED_APPS`.
43 44
 
44  
-       Many projects will also have static assets that aren't tied to a
45  
-       particular app; you can give ``staticfiles`` additional directories to
46  
-       search via the :setting:`STATICFILES_DIRS` setting .
  45
+   Your project will probably also have static assets that aren't tied to a
  46
+   particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of
  47
+   filesystem directories to check when loading static files. It's a search
  48
+   path that is by default empty. See the :setting:`STATICFILES_DIRS` docs
  49
+   how to extend this list of additional paths.
47 50
 
48  
-       See the documentation for the :setting:`STATICFILES_FINDERS` setting for
49  
-       details on how ``staticfiles`` finds your files.
  51
+   Additionally, see the documentation for the :setting:`STATICFILES_FINDERS`
  52
+   setting for details on how ``staticfiles`` finds your files.
50 53
 
51  
-    2. Set the :setting:`STATIC_URL` setting to the URL you want to use
52  
-       for pointing to your static files, e.g.::
  54
+2. Make sure that ``django.contrib.staticfiles`` is included in your
  55
+   :setting:`INSTALLED_APPS`.
53 56
 
54  
-           STATIC_URL = '/static/'
  57
+   For :ref:`local development<staticfiles-development>`, if you are using
  58
+   :ref:`runserver<staticfiles-runserver>` or adding
  59
+   :ref:`staticfiles_urlpatterns<staticfiles-development>` to your
  60
+   URLconf, you're done with the setup -- your static files will
  61
+   automatically be served at the default (for
  62
+   :djadmin:`newly created<startproject>` projects) :setting:`STATIC_URL`
  63
+   of ``/static/``.
55 64
 
56  
-       In projects freshly created with the :djadmin:`startproject`
57  
-       management command this will be preset to ``'/static/'``.
  65
+3. You'll probably need to refer to these files in your templates. The
  66
+   easiest method is to use the included context processor which allows
  67
+   template code like:
58 68
 
59  
-    3. Make sure that ``django.contrib.staticfiles`` is in your
60  
-       :setting:`INSTALLED_APPS`.
  69
+   .. code-block:: html+django
61 70
 
62  
-       For :ref:`local development<staticfiles-development>`, if you are using
63  
-       :ref:`runserver<staticfiles-runserver>` or adding
64  
-       :ref:`staticfiles_urlpatterns<staticfiles-development>` to your URLconf,
65  
-       you're done! Your static files will automatically be served at the
66  
-       :setting:`STATIC_URL` you specified in step 2.
  71
+       <img src="{{ STATIC_URL }}images/hi.jpg />
67 72
 
68  
-    4. You'll probably need to refer to these files in your templates. The
69  
-       easiest method is to use the included context processor which will allow
70  
-       template code like:
  73
+   See :ref:`staticfiles-in-templates` for more details, including an
  74
+   alternate method using a template tag.
71 75
 
72  
-          .. code-block:: html+django
73  
-
74  
-               <img src="{{ STATIC_URL }}images/hi.jpg />
75  
-
76  
-       See :ref:`staticfiles-in-templates` for more details, including an
77  
-       alternate method (using a template tag).
  76
+Deploying static files in a nutshell
  77
+------------------------------------
78 78
 
79 79
 When you're ready to move out of local development and deploy your project:
80 80
 
81  
-    1. Set the :setting:`STATIC_ROOT` setting to point to where you'd like your
82  
-       static files collected to when you use the :djadmin:`collectstatic`
83  
-       management command. For example::
  81
+1. Set the :setting:`STATIC_URL` setting to the public URL for your static
  82
+   files (in most cases, the default value of ``/static/`` is just fine).
84 83
 
85  
-            STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
  84
+2. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path
  85
+   you'd like your static files collected to when you use the
  86
+   :djadmin:`collectstatic` management command. For example::
86 87
 
87  
-    2. Run the :djadmin:`collectstatic` management command::
  88
+       STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
88 89
 
89  
-            ./manage.py collectstatic
  90
+3. Run the :djadmin:`collectstatic` management command::
90 91
 
91  
-       This'll churn through your static file storage and copy them into the
92  
-       directory given by :setting:`STATIC_ROOT`.
  92
+       ./manage.py collectstatic
93 93
 
94  
-    3. Deploy those files by configuring your webserver of choice to serve the
95  
-       files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
  94
+   This'll churn through your static file storage and copy them into the
  95
+   directory given by :setting:`STATIC_ROOT`.
96 96
 
97  
-       :ref:`staticfiles-production` covers some common deployment strategies
98  
-       for static files.
  97
+4. Deploy those files by configuring your webserver of choice to serve the
  98
+   files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
99 99
 
100  
-Those are the basics. For more details on common configuration options, read on;
101  
-for a detailed reference of the settings, commands, and other bits included with
102  
-the framework see :doc:`the staticfiles reference </ref/contrib/staticfiles>`.
  100
+   :ref:`staticfiles-production` covers some common deployment strategies
  101
+   for static files.
  102
+
  103
+Those are the **basics**. For more details on common configuration options,
  104
+read on; for a detailed reference of the settings, commands, and other bits
  105
+included with the framework see
  106
+:doc:`the staticfiles reference </ref/contrib/staticfiles>`.
103 107
 
104 108
 .. note::
105 109
 
106 110
    In previous versions of Django, it was common to place static assets in
107  
-   :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both at
108  
-   :setting:`MEDIA_URL`. Part of the purpose of introducing the ``staticfiles``
109  
-   app is to make it easier to keep static files separate from user-uploaded
110  
-   files. For this reason, you need to make your :setting:`MEDIA_ROOT` and
  111
+   :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both
  112
+   at :setting:`MEDIA_URL`. Part of the purpose of introducing the
  113
+   ``staticfiles`` app is to make it easier to keep static files separate
  114
+   from user-uploaded files.
  115
+
  116
+   For this reason, you need to make your :setting:`MEDIA_ROOT` and
111 117
    :setting:`MEDIA_URL` different from your :setting:`STATIC_ROOT` and
112 118
    :setting:`STATIC_URL`. You will need to arrange for serving of files in
113 119
    :setting:`MEDIA_ROOT` yourself; ``staticfiles`` does not deal with
114 120
    user-uploaded files at all. You can, however, use
115  
-   :func:`~django.views.static.serve` view for serving :setting:`MEDIA_ROOT`
  121
+   :func:`django.views.static.serve` view for serving :setting:`MEDIA_ROOT`
116 122
    in development; see :ref:`staticfiles-other-directories`.
117 123
 
118 124
 .. _staticfiles-in-templates:
@@ -303,7 +309,7 @@ development::
303 309
 
304 310
 .. note::
305 311
 
306  
-    The helper function will only be operational in debug mode and if
  312
+    This helper function will only be operational in debug mode and if
307 313
     the given prefix is local (e.g. ``/static/``) and not a URL (e.g.
308 314
     ``http://static.example.com/``).
309 315
 
2  docs/ref/contrib/staticfiles.txt
@@ -296,7 +296,7 @@ primary URL configuration::
296 296
            url(r'^static/(?P<path>.*)$', 'serve'),
297 297
        )
298 298
 
299  
-Note, the begin of the pattern (``r'^static/'``) should be your
  299
+Note, the beginning of the pattern (``r'^static/'``) should be your
300 300
 :setting:`STATIC_URL` setting.
301 301
 
302 302
 Since this is a bit finicky, there's also a helper function that'll do this for you:

0 notes on commit 091c9b5

Please sign in to comment.
Something went wrong with that request. Please try again.