From c1b3deedaa647034668e6c0fc0464d9d9608f152 Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Sat, 23 Oct 2010 14:32:20 +0000 Subject: [PATCH] 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 --- docs/howto/static-files.txt | 14 +++--- docs/ref/contrib/staticfiles.txt | 74 +++++++++++++++++++------------- 2 files changed, 53 insertions(+), 35 deletions(-) diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt index 113e1d4995..16a3e3fc99 100644 --- a/docs/howto/static-files.txt +++ b/docs/howto/static-files.txt @@ -190,7 +190,7 @@ The static files tools are mostly designed to help with getting static media successfully deployed into production. This usually means a separate, dedicated media server, which is a lot of overhead to mess with when developing locally. Thus, the ``staticfiles`` app ships with a quick and dirty helper view that you -can use to serve media locally in development. +can use to serve files locally in development. To enable this view, you'll add a couple of lines to your URLconf. The first 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:: This will inspect your :setting:`STATICFILES_URL` and :setting:`STATICFILES_ROOT` settings and wire up the view to serve static media -accordingly. +accordingly. Don't forget to set the :setting:`STATICFILES_DIRS` setting +appropriately to let ``django.contrib.staticfiles`` know where to look for +files. .. warning:: @@ -250,7 +252,8 @@ __ http://fabfile.org/ Below, and in the following sections, we'll show off a few example fabfiles (i.e. Fabric scripts) that automate these media deployment options. The syntax -of a fabfile is fairly streightforward but won't be covered here; consult `Fabric's documentation`__, for a complete explanation of the syntax.. +of a fabfile is fairly streightforward but won't be covered here; consult +`Fabric's documentation`__, for a complete explanation of the syntax.. __ http://docs.fabfile.org/ @@ -343,7 +346,7 @@ storage backend, you can tell :djadmin:`collectstatic` to use it by setting For example, if you've written an S3 storage backend in ``myproject.storage.S3Storage`` you could use it with:: - STATICFILES_STORAGE = 'storages.backends.s3.S3Storage' + STATICFILES_STORAGE = 'myproject.storage.S3Storage' Once that's done, all you have to do is run :djadmin:`collectstatic` and your 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, .. seealso:: The `django-storages`__ project is a 3rd party app that provides many - storage backends for many common file storage APIs (including S3). + storage backends for many common file storage APIs (including `S3`__). __ http://s3.amazonaws.com/ +__ http://code.welldev.org/django-storages/ __ http://code.welldev.org/django-storages/wiki/S3Storage Upgrading from ``django-staticfiles`` diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index 0ef4b58fd7..4edfed6e9b 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -7,9 +7,9 @@ The staticfiles app .. versionadded:: 1.3 -``django.contrib.staticfiles`` collects media from each of your applications -(and any other places you specify) into a single location that can easily be -served in production. +``django.contrib.staticfiles`` collects static files from each of your +applications (and any other places you specify) into a single location that +can easily be served in production. .. seealso:: @@ -23,7 +23,7 @@ Settings .. highlight:: python -The following settings control the behavior of the static files app. Only +The following settings control the behavior of the staticfiles app. Only :setting:`STATICFILES_ROOT` is required, but you'll probably also need to configure :setting:`STATICFILES_URL` as well. @@ -54,7 +54,7 @@ The URL that handles the files served from :setting:`STATICFILES_ROOT`, e.g.:: ... or perhaps:: - STATICFILES_URL = 'http://media.exmaple.com/' + STATICFILES_URL = 'http://static.example.com/' This should **always** have a trailing slash. @@ -70,13 +70,29 @@ if the :class:`FileSystemFinder` finder is enabled, e.g. if you use the :djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the static file serving view. -It should be defined as a sequence of ``(prefix, path)`` tuples, e.g.:: +This should be set to a list or tuple of strings that contain full paths to +your additional files directory(ies) e.g.:: - STATICFILES_DIRS = ( - ('', '/home/special.polls.com/polls/media'), - ('', '/home/polls.com/polls/media'), - ('common', '/opt/webfiles/common'), - ) + STATICFILES_DIRS = ( + "/home/special.polls.com/polls/static", + "/home/polls.com/polls/static", + "/opt/webfiles/common", + ) + +In case you want to refer to files in one of the locations with a 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:`STATICFILES_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. .. setting:: STATICFILES_STORAGE @@ -138,16 +154,15 @@ collectstatic Collects the static files into :setting:`STATICFILES_ROOT`. -Duplicate file names are resolved in a similar way to how template resolution -works: files from apps later in :setting:`INSTALLED_APPS` overwrite those from -earlier apps, and files from storage directories later in -:setting:`STATICFILES_DIRS` overwrite those from earlier. If you're confused, -the :djadmin:`findstatic` command can help show you where +Duplicate file names are by default resolved in a similar way to how template +resolution works: the file that is first found in one of the specified +locations will be used. If you're confused, the :djadmin:`findstatic` command +can help show you which files are found. -Files are searched by using the :ref:`enabled finders -`. The default is to look in all locations defined in -:ref:`staticfiles-dirs` and in the ``media`` directory of apps specified by the -:setting:`INSTALLED_APPS` setting. +Files are searched by using the :setting:`enabled finders +`. The default is to look in all locations defined in +:setting:`STATICFILES_DIRS` and in the ``'static'`` directory of apps +specified by the :setting:`INSTALLED_APPS` setting. Some commonly used options are: @@ -182,24 +197,24 @@ Searches for one or more relative paths with the enabled finders. For example:: $ python manage.py findstatic css/base.css admin/js/core.js - /home/special.polls.com/core/media/css/base.css - /home/polls.com/core/media/css/base.css + /home/special.polls.com/core/static/css/base.css + /home/polls.com/core/static/css/base.css /home/polls.com/src/django/contrib/admin/media/js/core.js By default, all matching locations are found. To only return the first match for each relative path, use the ``--first`` option:: $ python manage.py findstatic css/base.css --first - /home/special.polls.com/core/media/css/base.css - + /home/special.polls.com/core/static/css/base.css + This is a debugging aid; it'll show you exactly which static file will be collected for a given path. Other Helpers ============= -The ``media`` context processor -------------------------------- +The ``staticfiles`` context processor +------------------------------------- .. function:: django.contrib.staticfiles.context_processors.staticfiles @@ -226,8 +241,8 @@ instead:: {% load staticfiles %} -There's also a second form you can use to avoid extra processing if you need the -value multiple times:: +There's also a second form you can use to avoid extra processing if you need +the value multiple times:: {% load staticfiles %} {% get_staticfiles_prefix as STATIC_PREFIX %} @@ -244,7 +259,7 @@ Static file development view .. function:: django.contrib.staticfiles.views.serve(request, path) -This view function serves static media in in development. +This view function serves static files in development. .. warning:: @@ -280,4 +295,3 @@ already defined pattern list. Use it like this:: urlpatterns += staticfiles_urlpatterns() -