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

Some tweaks to the staticfiles docs to clarify things for new users. Thanks Jannis and brutasse for review and discussion. 

* Rearranged 'in a nutshell' usage docs to clarify app-dirs vs STATICFILES_DIRS, initially focus on the simplest path to working local dev, and remove the need for repetitive 'you don't need this in local dev' notes.
* Added docs on using staticfiles serve view for non-staticfiles (e.g. user-uploaded files).

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15380 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Carl Meyer 2011-01-31 22:06:53 +00:00
parent 553adfa6d1
commit 0bf5fbfa76
2 changed files with 84 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -7,7 +7,7 @@ Managing static files
.. versionadded:: 1.3
Django developers mostly concern themselves with the dynamic parts of web
applications -- the views and templates that render new for each request. But
applications -- the views and templates that render anew for each request. But
web applications have other parts: the static files (images, CSS,
Javascript, etc.) that are needed to render a complete web page.
@ -38,69 +38,30 @@ Using ``django.contrib.staticfiles``
Here's the basic usage in a nutshell:
1. Put your static files somewhere that staticfiles will find it.
1. Put your static files somewhere that ``staticfiles`` will find them.
Most of the time this place will be in a ``static`` directory within
your application, but it could also be a specific directory you've put
into your settings file. See the the documentation for the
:setting:`STATICFILES_DIRS` and :setting:`STATICFILES_FINDERS` settings
for details on where you can put static files.
By default, this means within ``static/`` subdirectories of apps in your
:setting:`INSTALLED_APPS`.
2. Add some ``staticfiles``-related settings to your settings file.
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 .
First, you'll need to make sure that ``django.contrib.staticfiles``
is in your :setting:`INSTALLED_APPS`.
See the documentation for the :setting:`STATICFILES_FINDERS` setting for
details on how ``staticfiles`` finds your files.
Next, you'll need to set the :setting:`STATIC_URL` setting, though
the default value (of ``'/static/'``) is perfect for local development.
See also the :setting:`STATIC_URL` documentation.
2. Make sure that ``django.contrib.staticfiles`` is in your
:setting:`INSTALLED_APPS`.
Then, edit the :setting:`STATIC_ROOT` setting to point to where
you'd like your static files collected at (when using the
:djadmin:`collectstatic`, see below). For example::
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
default :setting:`STATIC_URL` of ``/static/``.
STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
There are a number of other options available that let you control
*how* static files are stored, where ``staticfiles`` searches for
files, and how files will be served; see :ref:`the staticfiles
settings reference <staticfiles-settings>` for details.
3. Run the :djadmin:`collectstatic` management command::
./manage.py collectstatic
This'll churn through your static file storage and move them into the
directory given by :setting:`STATIC_ROOT`.
.. note:: This is **not necessary in local development** if you are
using :djadmin:`runserver<staticfiles-runserver>` or adding
``staticfiles_urlpatterns`` to your URLconf; see below).
4. Deploy those files.
If you're using the built-in development server (the
:djadmin:`runserver` management command) and have the :setting:`DEBUG`
setting set to ``True``, your staticfiles will automatically be served
from :setting:`STATIC_URL` in development. You don't need to run
:djadmin:`collectstatic` in that case because ``staticfiles``'s
runserver command handle the serving of static files.
But, in case you are using some other server for local development,
you can quickly serve static files locally by adding::
from django.contrib.staticfiles.urls import staticfiles_urlpatterns
urlpatterns += staticfiles_urlpatterns()
to the bottom of your URLconf. See :ref:`staticfiles-development` for
details.
When it comes time to deploy to production, :ref:`staticfiles-production`
covers some common deployment strategies for static files.
However you choose to deploy those files, you'll probably need to refer
to them in your templates. The easiest method is to use the included
context processor which will allow template code like:
3. 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:
.. code-block:: html+django
@ -109,6 +70,31 @@ Here's the basic usage in a nutshell:
See :ref:`staticfiles-in-templates` for more details, including an
alternate method (using a template tag).
When you're ready to move out of local development and deploy your project:
1. Set the :setting:`STATIC_URL` setting to the public URL for your static
files (in some cases, the default value of ``/static/`` may still be
fine).
2. 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::
STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
3. Run the :djadmin:`collectstatic` management command::
./manage.py collectstatic
This'll churn through your static file storage and copy them into the
directory given by :setting:`STATIC_ROOT`.
4. Deploy those files by configuring your webserver of choice to serve the
files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
: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>`.
@ -123,7 +109,10 @@ the framework see :doc:`the staticfiles reference </ref/contrib/staticfiles>`.
: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.
user-uploaded files at all. You can, however, use ``staticfiles``'
:func:`~django.contrib.staticfiles.views.serve` view for serving
:setting:`MEDIA_ROOT` in development; see
:ref:`staticfiles-serve-other-directories`.
.. _staticfiles-in-templates:
@ -221,7 +210,8 @@ developing locally. Thus, the ``staticfiles`` app ships with a
development.
This view is automatically enabled and will serve your static files at
:setting:`STATIC_URL` when you use the built-in :djadmin:`runserver`.
:setting:`STATIC_URL` when you use the built-in
:ref:`runserver<staticfiles-runserver>` management command.
To enable this view if you are using some other server for local development,
you'll add a couple of lines to your URLconf. The first line goes at the top
@ -275,7 +265,7 @@ If you want to serve your static files from the same server that's already
serving your site, the basic outline gets modified to look something like:
* Push your code up to the deployment server.
* On the server, run :djadmin:`collectstatic` to move all the static files
* On the server, run :djadmin:`collectstatic` to copy all the static files
into :setting:`STATIC_ROOT`.
* Point your web server at :setting:`STATIC_ROOT`. For example, here's
:ref:`how to do this under Apache and mod_wsgi <serving-media-files>`.
@ -426,8 +416,8 @@ you're upgrading from `django-staticfiles`_ < ``1.0``` (e.g. ``0.3.4``) to
``staticfiles.storage.StaticFileStorage`` to
``staticfiles.storage.StaticFilesStorage``
* If using :djadmin:`runserver` for local development (and the
:setting:`DEBUG` setting is ``True``), you no longer need to add
* If using :ref:`runserver<staticfiles-runserver>` for local development
(and the :setting:`DEBUG` setting is ``True``), you no longer need to add
anything to your URLconf for serving static files in development.
Learn more

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

@ -189,10 +189,12 @@ for each relative path, use the ``--first`` option::
This is a debugging aid; it'll show you exactly which static file will be
collected for a given path.
.. _staticfiles-runserver:
runserver
---------
.. django-admin:: staticfiles-runserver
.. django-admin:: runserver
Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app
is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static
@ -317,3 +319,31 @@ already defined pattern list. Use it like this::
This helper function will only work if :setting:`DEBUG` is ``True``
and your :setting:`STATIC_URL` setting is neither empty nor a full
URL such as ``http://static.example.com/``.
.. _staticfiles-serve-other-directories:
Serving other directories
"""""""""""""""""""""""""
There may be files other than your project's static assets that, for
convenience, you'd like to have Django serve for you in local development. The
:func:`~django.contrib.staticfiles.views.serve` view can be used to serve any
directory you give it. (Again, this view is **not** hardened for production
use, and should be used only as a development aid; you should serve these files
in production using a real front-end webserver).
The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`.
``staticfiles`` is intended for static assets and has no built-in handling for
user-uploaded files, but you can have Django serve your :setting:`MEDIA_ROOT`
by appending something like this to your URLconf::
from django.conf import settings
if settings.DEBUG:
urlpatterns += patterns('django.contrib.staticfiles.views',
url(r'^media/(?P<path>.*)$', 'serve',
{'document_root': settings.MEDIA_ROOT}),
)
This snippet assumes you've also set your :setting:`MEDIA_URL` (in development)
to ``/media/``.