Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #14528 and #14538 -- Refined staticfiles documentation. Thanks,…

… gremmie and romaniuk.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14323 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit c1b3deedaa647034668e6c0fc0464d9d9608f152 1 parent 4674ef2
Jannis Leidel authored October 23, 2010
14  docs/howto/static-files.txt
@@ -190,7 +190,7 @@ The static files tools are mostly designed to help with getting static media
190 190
 successfully deployed into production. This usually means a separate, dedicated
191 191
 media server, which is a lot of overhead to mess with when developing locally.
192 192
 Thus, the ``staticfiles`` app ships with a quick and dirty helper view that you
193  
-can use to serve media locally in development.
  193
+can use to serve files locally in development.
194 194
 
195 195
 To enable this view, you'll add a couple of lines to your URLconf. The first
196 196
 line goes at the top of the file, and the last line at the bottom::
@@ -203,7 +203,9 @@ line goes at the top of the file, and the last line at the bottom::
203 203
 
204 204
 This will inspect your :setting:`STATICFILES_URL` and
205 205
 :setting:`STATICFILES_ROOT` settings and wire up the view to serve static media
206  
-accordingly.
  206
+accordingly. Don't forget to set the :setting:`STATICFILES_DIRS` setting
  207
+appropriately to let ``django.contrib.staticfiles`` know where to look for
  208
+files.
207 209
 
208 210
 .. warning::
209 211
 
@@ -250,7 +252,8 @@ __ http://fabfile.org/
250 252
 
251 253
 Below, and in the following sections, we'll show off a few example fabfiles
252 254
 (i.e. Fabric scripts) that automate these media deployment options. The syntax
253  
-of a fabfile is fairly streightforward but won't be covered here; consult `Fabric's documentation`__, for a complete explanation of the syntax..
  255
+of a fabfile is fairly streightforward but won't be covered here; consult
  256
+`Fabric's documentation`__, for a complete explanation of the syntax..
254 257
 
255 258
 __ http://docs.fabfile.org/
256 259
 
@@ -343,7 +346,7 @@ storage backend, you can tell :djadmin:`collectstatic` to use it by setting
343 346
 For example, if you've written an S3 storage backend in
344 347
 ``myproject.storage.S3Storage`` you could use it with::
345 348
 
346  
-    STATICFILES_STORAGE = 'storages.backends.s3.S3Storage'
  349
+    STATICFILES_STORAGE = 'myproject.storage.S3Storage'
347 350
 
348 351
 Once that's done, all you have to do is run :djadmin:`collectstatic` and your
349 352
 media would be pushed through your storage package up to S3. If you later needed
@@ -356,9 +359,10 @@ For details on how you'd write one of these backends,
356 359
 .. seealso::
357 360
 
358 361
     The `django-storages`__ project is a 3rd party app that provides many
359  
-    storage backends for many common file storage APIs (including S3).
  362
+    storage backends for many common file storage APIs (including `S3`__).
360 363
 
361 364
 __ http://s3.amazonaws.com/
  365
+__ http://code.welldev.org/django-storages/
362 366
 __ http://code.welldev.org/django-storages/wiki/S3Storage
363 367
 
364 368
 Upgrading from ``django-staticfiles``
74  docs/ref/contrib/staticfiles.txt
@@ -7,9 +7,9 @@ The staticfiles app
7 7
 
8 8
 .. versionadded:: 1.3
9 9
 
10  
-``django.contrib.staticfiles`` collects media from each of your applications
11  
-(and any other places you specify) into a single location that can easily be
12  
-served in production.
  10
+``django.contrib.staticfiles`` collects static files from each of your
  11
+applications (and any other places you specify) into a single location that
  12
+can easily be served in production.
13 13
 
14 14
 .. seealso::
15 15
 
@@ -23,7 +23,7 @@ Settings
23 23
 
24 24
 .. highlight:: python
25 25
 
26  
-The following settings control the behavior of the static files app. Only
  26
+The following settings control the behavior of the staticfiles app. Only
27 27
 :setting:`STATICFILES_ROOT` is required, but you'll probably also need to
28 28
 configure :setting:`STATICFILES_URL` as well.
29 29
 
@@ -54,7 +54,7 @@ The URL that handles the files served from :setting:`STATICFILES_ROOT`, e.g.::
54 54
    
55 55
 ... or perhaps::
56 56
 
57  
-    STATICFILES_URL = 'http://media.exmaple.com/'
  57
+    STATICFILES_URL = 'http://static.example.com/'
58 58
 
59 59
 This should **always** have a trailing slash.
60 60
 
@@ -70,13 +70,29 @@ if the :class:`FileSystemFinder` finder is enabled, e.g. if you use the
70 70
 :djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
71 71
 static file serving view.
72 72
 
73  
-It should be defined as a sequence of ``(prefix, path)`` tuples, e.g.::
  73
+This should be set to a list or tuple of strings that contain full paths to
  74
+your additional files directory(ies) e.g.::
74 75
 
75  
-   STATICFILES_DIRS = (
76  
-       ('', '/home/special.polls.com/polls/media'),
77  
-       ('', '/home/polls.com/polls/media'),
78  
-       ('common', '/opt/webfiles/common'),
79  
-   )
  76
+    STATICFILES_DIRS = (
  77
+        "/home/special.polls.com/polls/static",
  78
+        "/home/polls.com/polls/static",
  79
+        "/opt/webfiles/common",
  80
+    )
  81
+
  82
+In case you want to refer to files in one of the locations with a additional
  83
+namespace, you can **optionally** provide a prefix as ``(prefix, path)``
  84
+tuples, e.g.::
  85
+
  86
+    STATICFILES_DIRS = (
  87
+        "/home/polls.com/polls/static",
  88
+        ("downloads", "/opt/webfiles/stats"),
  89
+    )
  90
+
  91
+With this configuration, the :djadmin:`collectstatic` management command would
  92
+for example collect the stats files in a ``'downloads'`` directory. So
  93
+assuming you have :setting:`STATICFILES_URL` set ``'/static/'``, this would
  94
+allow you to refer to the file ``'/opt/webfiles/stats/polls_20101022.tar.gz'``
  95
+with ``'/static/downloads/polls_20101022.tar.gz'`` in your templates.
80 96
 
81 97
 .. setting:: STATICFILES_STORAGE
82 98
 
@@ -138,16 +154,15 @@ collectstatic
138 154
 
139 155
 Collects the static files into :setting:`STATICFILES_ROOT`.
140 156
 
141  
-Duplicate file names are resolved in a similar way to how template resolution
142  
-works: files from apps later in :setting:`INSTALLED_APPS` overwrite those from
143  
-earlier apps, and files from storage directories later in
144  
-:setting:`STATICFILES_DIRS` overwrite those from earlier. If you're confused,
145  
-the :djadmin:`findstatic` command can help show you where 
  157
+Duplicate file names are by default resolved in a similar way to how template
  158
+resolution works: the file that is first found in one of the specified
  159
+locations will be used. If you're confused, the :djadmin:`findstatic` command
  160
+can help show you which files are found.
146 161
 
147  
-Files are searched by using the :ref:`enabled finders
148  
-<staticfiles-finders>`. The default is to look in all locations defined in
149  
-:ref:`staticfiles-dirs` and in the ``media`` directory of apps specified by the
150  
-:setting:`INSTALLED_APPS` setting.
  162
+Files are searched by using the :setting:`enabled finders
  163
+<STATICFILES_FINDERS>`. The default is to look in all locations defined in
  164
+:setting:`STATICFILES_DIRS` and in the ``'static'`` directory of apps
  165
+specified by the :setting:`INSTALLED_APPS` setting.
151 166
 
152 167
 Some commonly used options are:
153 168
 
@@ -182,24 +197,24 @@ Searches for one or more relative paths with the enabled finders.
182 197
 For example::
183 198
 
184 199
    $ python manage.py findstatic css/base.css admin/js/core.js
185  
-   /home/special.polls.com/core/media/css/base.css
186  
-   /home/polls.com/core/media/css/base.css
  200
+   /home/special.polls.com/core/static/css/base.css
  201
+   /home/polls.com/core/static/css/base.css
187 202
    /home/polls.com/src/django/contrib/admin/media/js/core.js
188 203
 
189 204
 By default, all matching locations are found. To only return the first match
190 205
 for each relative path, use the ``--first`` option::
191 206
 
192 207
    $ python manage.py findstatic css/base.css --first
193  
-   /home/special.polls.com/core/media/css/base.css
194  
-   
  208
+   /home/special.polls.com/core/static/css/base.css
  209
+
195 210
 This is a debugging aid; it'll show you exactly which static file will be
196 211
 collected for a given path.
197 212
 
198 213
 Other Helpers
199 214
 =============
200 215
 
201  
-The ``media`` context processor
202  
--------------------------------
  216
+The ``staticfiles`` context processor
  217
+-------------------------------------
203 218
 
204 219
 .. function:: django.contrib.staticfiles.context_processors.staticfiles
205 220
 
@@ -226,8 +241,8 @@ instead::
226 241
     {% load staticfiles %}
227 242
     <img src="{% get_staticfiles_prefix %}images/hi.jpg" />
228 243
 
229  
-There's also a second form you can use to avoid extra processing if you need the
230  
-value multiple times::
  244
+There's also a second form you can use to avoid extra processing if you need
  245
+the value multiple times::
231 246
 
232 247
     {% load staticfiles %}
233 248
     {% get_staticfiles_prefix as STATIC_PREFIX %}
@@ -244,7 +259,7 @@ Static file development view
244 259
 
245 260
 .. function:: django.contrib.staticfiles.views.serve(request, path)
246 261
 
247  
-This view function serves static media in in development.
  262
+This view function serves static files in development.
248 263
 
249 264
 .. warning::
250 265
 
@@ -280,4 +295,3 @@ already defined pattern list. Use it like this::
280 295
    
281 296
    urlpatterns += staticfiles_urlpatterns()
282 297
 
283  
-

0 notes on commit c1b3dee

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