Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

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
  • Loading branch information...
commit 0bf5fbfa76544fe921d051619127748ae10237bd 1 parent 553adfa
@carljm carljm authored
Showing with 79 additions and 59 deletions.
  1. +48 −58 docs/howto/static-files.txt
  2. +31 −1 docs/ref/contrib/staticfiles.txt
View
106 docs/howto/static-files.txt
@@ -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,76 +38,62 @@ 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
+ 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:
- This'll churn through your static file storage and move them into the
- directory given by :setting:`STATIC_ROOT`.
+ .. code-block:: html+django
- .. 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).
+ <img src="{{ STATIC_URL }}images/hi.jpg />
- 4. Deploy those files.
+ See :ref:`staticfiles-in-templates` for more details, including an
+ alternate method (using a template tag).
- 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.
+When you're ready to move out of local development and deploy your project:
- But, in case you are using some other server for local development,
- you can quickly serve static files locally by adding::
+ 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).
- from django.contrib.staticfiles.urls import staticfiles_urlpatterns
- urlpatterns += staticfiles_urlpatterns()
+ 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::
- to the bottom of your URLconf. See :ref:`staticfiles-development` for
- details.
+ STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
- When it comes time to deploy to production, :ref:`staticfiles-production`
- covers some common deployment strategies for static files.
+ 3. Run the :djadmin:`collectstatic` management command::
- 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:
+ ./manage.py collectstatic
- .. code-block:: html+django
+ This'll churn through your static file storage and copy them into the
+ directory given by :setting:`STATIC_ROOT`.
- <img src="{{ STATIC_URL }}images/hi.jpg />
+ 4. Deploy those files by configuring your webserver of choice to serve the
+ files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
- See :ref:`staticfiles-in-templates` for more details, including an
- alternate method (using a template tag).
+ :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
@@ -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
View
32 docs/ref/contrib/staticfiles.txt
@@ -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/``.
Please sign in to comment.
Something went wrong with that request. Please try again.