p15693087
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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
This commit is contained in:
Jannis Leidel 2010-10-23 14:32:20 +00:00
parent 4674ef2781
commit c1b3deedaa
2 changed files with 53 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/howto/static-files.txt
View File

@ -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 successfully deployed into production. This usually means a separate, dedicated
media server, which is a lot of overhead to mess with when developing locally. 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 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 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:: 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 This will inspect your :setting:`STATICFILES_URL` and
:setting:`STATICFILES_ROOT` settings and wire up the view to serve static media :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:: .. warning::
@ -250,7 +252,8 @@ __ http://fabfile.org/
Below, and in the following sections, we'll show off a few example fabfiles 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 (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/ __ 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 For example, if you've written an S3 storage backend in
``myproject.storage.S3Storage`` you could use it with:: ``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 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 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:: .. seealso::
The `django-storages`__ project is a 3rd party app that provides many 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://s3.amazonaws.com/
__ http://code.welldev.org/django-storages/
__ http://code.welldev.org/django-storages/wiki/S3Storage __ http://code.welldev.org/django-storages/wiki/S3Storage
Upgrading from ``django-staticfiles`` Upgrading from ``django-staticfiles``

68
docs/ref/contrib/staticfiles.txt
View File

@ -7,9 +7,9 @@ The staticfiles app
.. versionadded:: 1.3 .. versionadded:: 1.3
``django.contrib.staticfiles`` collects media from each of your applications ``django.contrib.staticfiles`` collects static files from each of your
(and any other places you specify) into a single location that can easily be applications (and any other places you specify) into a single location that
served in production. can easily be served in production.
.. seealso:: .. seealso::
@ -23,7 +23,7 @@ Settings
.. highlight:: python .. 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 :setting:`STATICFILES_ROOT` is required, but you'll probably also need to
configure :setting:`STATICFILES_URL` as well. 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:: ... or perhaps::
STATICFILES_URL = 'http://media.exmaple.com/' STATICFILES_URL = 'http://static.example.com/'
This should **always** have a trailing slash. This should **always** have a trailing slash.
@ -70,14 +70,30 @@ if the :class:`FileSystemFinder` finder is enabled, e.g. if you use the
:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the :djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
static file serving view. 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 = ( STATICFILES_DIRS = (
('', '/home/special.polls.com/polls/media'), "/home/special.polls.com/polls/static",
('', '/home/polls.com/polls/media'), "/home/polls.com/polls/static",
('common', '/opt/webfiles/common'), "/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 .. setting:: STATICFILES_STORAGE
STATICFILES_STORAGE STATICFILES_STORAGE
@ -138,16 +154,15 @@ collectstatic
Collects the static files into :setting:`STATICFILES_ROOT`. Collects the static files into :setting:`STATICFILES_ROOT`.
Duplicate file names are resolved in a similar way to how template resolution Duplicate file names are by default resolved in a similar way to how template
works: files from apps later in :setting:`INSTALLED_APPS` overwrite those from resolution works: the file that is first found in one of the specified
earlier apps, and files from storage directories later in locations will be used. If you're confused, the :djadmin:`findstatic` command
:setting:`STATICFILES_DIRS` overwrite those from earlier. If you're confused, can help show you which files are found.
the :djadmin:`findstatic` command can help show you where
Files are searched by using the :ref:`enabled finders Files are searched by using the :setting:`enabled finders
<staticfiles-finders>`. The default is to look in all locations defined in <STATICFILES_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:`STATICFILES_DIRS` and in the ``'static'`` directory of apps
:setting:`INSTALLED_APPS` setting. specified by the :setting:`INSTALLED_APPS` setting.
Some commonly used options are: Some commonly used options are:
@ -182,15 +197,15 @@ Searches for one or more relative paths with the enabled finders.
For example:: For example::
$ python manage.py findstatic css/base.css admin/js/core.js $ python manage.py findstatic css/base.css admin/js/core.js
/home/special.polls.com/core/media/css/base.css /home/special.polls.com/core/static/css/base.css
/home/polls.com/core/media/css/base.css /home/polls.com/core/static/css/base.css
/home/polls.com/src/django/contrib/admin/media/js/core.js /home/polls.com/src/django/contrib/admin/media/js/core.js
By default, all matching locations are found. To only return the first match By default, all matching locations are found. To only return the first match
for each relative path, use the ``--first`` option:: for each relative path, use the ``--first`` option::
$ python manage.py findstatic css/base.css --first $ 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 This is a debugging aid; it'll show you exactly which static file will be
collected for a given path. collected for a given path.
@ -198,8 +213,8 @@ collected for a given path.
Other Helpers Other Helpers
============= =============
The ``media`` context processor The ``staticfiles`` context processor
------------------------------- -------------------------------------
.. function:: django.contrib.staticfiles.context_processors.staticfiles .. function:: django.contrib.staticfiles.context_processors.staticfiles
@ -226,8 +241,8 @@ instead::
{% load staticfiles %} {% load staticfiles %}
<img src="{% get_staticfiles_prefix %}images/hi.jpg" /> <img src="{% get_staticfiles_prefix %}images/hi.jpg" />
There's also a second form you can use to avoid extra processing if you need the There's also a second form you can use to avoid extra processing if you need
value multiple times:: the value multiple times::
{% load staticfiles %} {% load staticfiles %}
{% get_staticfiles_prefix as STATIC_PREFIX %} {% get_staticfiles_prefix as STATIC_PREFIX %}
@ -244,7 +259,7 @@ Static file development view
.. function:: django.contrib.staticfiles.views.serve(request, path) .. 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:: .. warning::
@ -280,4 +295,3 @@ already defined pattern list. Use it like this::
urlpatterns += staticfiles_urlpatterns() urlpatterns += staticfiles_urlpatterns()