From 4966dae988a921034d31c1b856078f96eba7373d Mon Sep 17 00:00:00 2001
From: Adrien Lemaire
Date: Wed, 28 Mar 2012 10:30:39 +0900
Subject: [PATCH] cleaning media and static files docs urls
---
docs/howto/static-files.txt | 510 --------------------------------------
docs/index.txt | 4 +-
docs/misc/api-stability.txt | 2 +-
docs/ref/contrib/staticfiles.txt | 2 +-
docs/ref/django-admin.txt | 6 +-
docs/ref/models/fields.txt | 6 +-
docs/ref/request-response.txt | 2 +-
docs/ref/settings.txt | 14 +-
docs/releases/1.0-alpha-2.txt | 2 +-
docs/releases/1.0.txt | 2 +-
docs/releases/1.3-alpha-1.txt | 2 +-
docs/releases/1.3-beta-1.txt | 2 +-
docs/releases/1.3.txt | 2 +-
docs/releases/1.4-alpha-1.txt | 2 +-
docs/releases/1.4-beta-1.txt | 2 +-
docs/releases/1.4.txt | 2 +-
docs/topics/files.txt | 151 -----------
docs/topics/files/media.txt | 153 ++++++++++++
docs/topics/files/static.txt | 510 ++++++++++++++++++++++++++++++++++++++
docs/topics/testing.txt | 2 +-
20 files changed, 690 insertions(+), 688 deletions(-)
delete mode 100644 docs/howto/static-files.txt
delete mode 100644 docs/topics/files.txt
create mode 100644 docs/topics/files/media.txt
create mode 100644 docs/topics/files/static.txt
diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt
deleted file mode 100644
index e3a40a1..0000000
--- a/docs/howto/static-files.txt
+++ /dev/null
@@ -1,510 +0,0 @@
-=====================
-Managing static files
-=====================
-
-.. versionadded:: 1.3
-
-Django developers mostly concern themselves with the dynamic parts of web
-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.
-
-For small projects, this isn't a big deal, because you can just keep the
-static files somewhere your web server can find it. However, in bigger
-projects -- especially those comprised of multiple apps -- dealing with the
-multiple sets of static files provided by each application starts to get
-tricky.
-
-That's what ``django.contrib.staticfiles`` is for: it 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.
-
-.. note::
-
- If you've used the `django-staticfiles`_ third-party app before, then
- ``django.contrib.staticfiles`` will look very familiar. That's because
- they're essentially the same code: ``django.contrib.staticfiles`` started
- its life as `django-staticfiles`_ and was merged into Django 1.3.
-
- If you're upgrading from ``django-staticfiles``, please see `Upgrading from
- django-staticfiles`_, below, for a few minor changes you'll need to make.
-
-.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
-
-Using ``django.contrib.staticfiles``
-====================================
-
-Basic usage
------------
-
-1. Put your static files somewhere that ``staticfiles`` will find them.
-
- By default, this means within ``static/`` subdirectories of apps in your
- :setting:`INSTALLED_APPS`.
-
- Your project will probably also have static assets that aren't tied to a
- particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of
- filesystem directories to check when loading static files. It's a search
- path that is by default empty. See the :setting:`STATICFILES_DIRS` docs
- how to extend this list of additional paths.
-
- Additionally, see the documentation for the :setting:`STATICFILES_FINDERS`
- setting for details on how ``staticfiles`` finds your files.
-
-2. Make sure that ``django.contrib.staticfiles`` is included in your
- :setting:`INSTALLED_APPS`.
-
- For :ref:`local development`, if you are using
- :ref:`runserver` or adding
- :ref:`staticfiles_urlpatterns` to your
- URLconf, you're done with the setup -- your static files will
- automatically be served at the default (for
- :djadmin:`newly created` projects) :setting:`STATIC_URL`
- of ``/static/``.
-
-3. You'll probably need to refer to these files in your templates. The
- easiest method is to use the included context processor which allows
- template code like:
-
- .. code-block:: html+django
-
-
-
- See :ref:`staticfiles-in-templates` for more details, **including** an
- alternate method using a template tag.
-
-Deploying static files in a nutshell
-------------------------------------
-
-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 most cases, the default value of ``/static/`` is just fine).
-
-2. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path
- 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 `.
-
-.. note::
-
- In previous versions of Django, it was common to place static assets in
- :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both
- at :setting:`MEDIA_URL`. Part of the purpose of introducing the
- ``staticfiles`` app is to make it easier to keep static files separate
- from user-uploaded files.
-
- For this reason, you need to make your :setting:`MEDIA_ROOT` and
- :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. You can, however, use
- :func:`django.views.static.serve` view for serving :setting:`MEDIA_ROOT`
- in development; see :ref:`staticfiles-other-directories`.
-
-.. _staticfiles-in-templates:
-
-Referring to static files in templates
-======================================
-
-At some point, you'll probably need to link to static files in your templates.
-You could, of course, simply hardcode the path to you assets in the templates:
-
-.. code-block:: html
-
-
-
-Of course, there are some serious problems with this: it doesn't work well in
-development, and it makes it *very* hard to change where you've deployed your
-static files. If, for example, you wanted to switch to using a content
-delivery network (CDN), then you'd need to change more or less every single
-template.
-
-A far better way is to use the value of the :setting:`STATIC_URL` setting
-directly in your templates. This means that a switch of static files servers
-only requires changing that single value. Much better!
-
-Django includes multiple built-in ways of using this setting in your
-templates: a context processor and a template tag.
-
-With a context processor
-------------------------
-
-The included context processor is the easy way. Simply make sure
-``'django.core.context_processors.static'`` is in your
-:setting:`TEMPLATE_CONTEXT_PROCESSORS`. It's there by default, and if you're
-editing that setting by hand it should look something like::
-
- TEMPLATE_CONTEXT_PROCESSORS = (
- 'django.core.context_processors.debug',
- 'django.core.context_processors.i18n',
- 'django.core.context_processors.media',
- 'django.core.context_processors.static',
- 'django.contrib.auth.context_processors.auth',
- 'django.contrib.messages.context_processors.messages',
- )
-
-Once that's done, you can refer to :setting:`STATIC_URL` in your templates:
-
-.. code-block:: html+django
-
-
-
-If ``{{ STATIC_URL }}`` isn't working in your template, you're probably not
-using :class:`~django.template.RequestContext` when rendering the template.
-
-As a brief refresher, context processors add variables into the contexts of
-every template. However, context processors require that you use
-:class:`~django.template.RequestContext` when rendering templates. This happens
-automatically if you're using a :doc:`generic view `,
-but in views written by hand you'll need to explicitly use ``RequestContext``
-To see how that works, and to read more details, check out
-:ref:`subclassing-context-requestcontext`.
-
-Another option is the :ttag:`get_static_prefix` template tag that is part of
-Django's core.
-
-With a template tag
--------------------
-
-The more powerful tool is the :ttag:`static` template
-tag. It builds the URL for the given relative path by using the configured
-:setting:`STATICFILES_STORAGE` storage.
-
-.. code-block:: html+django
-
- {% load staticfiles %}
-
-
-It is also able to consume standard context variables, e.g. assuming a
-``user_stylesheet`` variable is passed to the template:
-
-.. code-block:: html+django
-
- {% load staticfiles %}
-
-
-.. note::
-
- There is also a template tag named :ttag:`static` in Django's core set
- of :ref:`built in template tags` which has
- the same argument signature but only uses `urlparse.urljoin()`_ with the
- :setting:`STATIC_URL` setting and the given path. This has the
- disadvantage of not being able to easily switch the storage backend
- without changing the templates, so in doubt use the ``staticfiles``
- :ttag:`static`
- template tag.
-
-.. _`urlparse.urljoin()`: http://docs.python.org/library/urlparse.html#urlparse.urljoin
-
-.. _staticfiles-development:
-
-Serving static files in development
-===================================
-
-The static files tools are mostly designed to help with getting static files
-successfully deployed into production. This usually means a separate,
-dedicated static file 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 files locally in
-development.
-
-This view is automatically enabled and will serve your static files at
-:setting:`STATIC_URL` when you use the built-in
-:ref:`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
-of the file, and the last line at the bottom::
-
- from django.contrib.staticfiles.urls import staticfiles_urlpatterns
-
- # ... the rest of your URLconf goes here ...
-
- urlpatterns += staticfiles_urlpatterns()
-
-This will inspect your :setting:`STATIC_URL` setting and wire up the view
-to serve static files accordingly. Don't forget to set the
-:setting:`STATICFILES_DIRS` setting appropriately to let
-``django.contrib.staticfiles`` know where to look for files additionally to
-files in app directories.
-
-.. warning::
-
- This will only work if :setting:`DEBUG` is ``True``.
-
- That's because this view is **grossly inefficient** and probably
- **insecure**. This is only intended for local development, and should
- **never be used in production**.
-
- Additionally, when using ``staticfiles_urlpatterns`` your
- :setting:`STATIC_URL` setting can't be empty or a full URL, such as
- ``http://static.example.com/``.
-
-For a few more details on how the ``staticfiles`` can be used during
-development, see :ref:`staticfiles-development-view`.
-
-.. _staticfiles-other-directories:
-
-Serving other directories
--------------------------
-
-.. currentmodule:: django.views.static
-.. function:: serve(request, path, document_root, show_indexes=False)
-
-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.views.static.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
-
- # ... the rest of your URLconf goes here ...
-
- if settings.DEBUG:
- urlpatterns += patterns('',
- url(r'^media/(?P.*)$', 'django.views.static.serve', {
- 'document_root': settings.MEDIA_ROOT,
- }),
- )
-
-Note, the snippet assumes your :setting:`MEDIA_URL` has a value of
-``'/media/'``. This will call the :func:`~django.views.static.serve` view,
-passing in the path from the URLconf and the (required) ``document_root``
-parameter.
-
-.. currentmodule:: django.conf.urls.static
-.. function:: static(prefix, view='django.views.static.serve', **kwargs)
-
-Since it can become a bit cumbersome to define this URL pattern, Django
-ships with a small URL helper function
-:func:`~django.conf.urls.static.static` that takes as parameters the prefix
-such as :setting:`MEDIA_URL` and a dotted path to a view, such as
-``'django.views.static.serve'``. Any other function parameter will be
-transparently passed to the view.
-
-An example for serving :setting:`MEDIA_URL` (``'/media/'``) during
-development::
-
- from django.conf import settings
- from django.conf.urls.static import static
-
- urlpatterns = patterns('',
- # ... the rest of your URLconf goes here ...
- ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
-
-.. note::
-
- This helper function will only be operational in debug mode and if
- the given prefix is local (e.g. ``/static/``) and not a URL (e.g.
- ``http://static.example.com/``).
-
-.. _staticfiles-production:
-
-Serving static files in production
-==================================
-
-The basic outline of putting static files into production is simple: run the
-:djadmin:`collectstatic` command when static files change, then arrange for
-the collected static files directory (:setting:`STATIC_ROOT`) to be moved to
-the static file server and served.
-
-Of course, as with all deployment tasks, the devil's in the details. Every
-production setup will be a bit different, so you'll need to adapt the basic
-outline to fit your needs. Below are a few common patterns that might help.
-
-Serving the app and your static files from the same server
-----------------------------------------------------------
-
-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 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 `.
-
-You'll probably want to automate this process, especially if you've got
-multiple web servers. There's any number of ways to do this automation, but
-one option that many Django developers enjoy is `Fabric`__.
-
-__ http://fabfile.org/
-
-Below, and in the following sections, we'll show off a few example fabfiles
-(i.e. Fabric scripts) that automate these file deployment options. The syntax
-of a fabfile is fairly straightforward but won't be covered here; consult
-`Fabric's documentation`__, for a complete explanation of the syntax..
-
-__ http://docs.fabfile.org/
-
-So, a fabfile to deploy static files to a couple of web servers might look
-something like::
-
- from fabric.api import *
-
- # Hosts to deploy onto
- env.hosts = ['www1.example.com', 'www2.example.com']
-
- # Where your project code lives on the server
- env.project_root = '/home/www/myproject'
-
- def deploy_static():
- with cd(env.project_root):
- run('./manage.py collectstatic -v0 --noinput')
-
-Serving static files from a dedicated server
---------------------------------------------
-
-Most larger Django apps use a separate Web server -- i.e., one that's not also
-running Django -- for serving static files. This server often runs a different
-type of web server -- faster but less full-featured. Some good choices are:
-
-* lighttpd_
-* Nginx_
-* TUX_
-* Cherokee_
-* A stripped-down version of Apache_
-
-.. _lighttpd: http://www.lighttpd.net/
-.. _Nginx: http://wiki.nginx.org/Main
-.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
-.. _Apache: http://httpd.apache.org/
-.. _Cherokee: http://www.cherokee-project.com/
-
-Configuring these servers is out of scope of this document; check each
-server's respective documentation for instructions.
-
-Since your static file server won't be running Django, you'll need to modify
-the deployment strategy to look something like:
-
-* When your static files change, run :djadmin:`collectstatic` locally.
-* Push your local :setting:`STATIC_ROOT` up to the static file server
- into the directory that's being served. ``rsync`` is a good
- choice for this step since it only needs to transfer the
- bits of static files that have changed.
-
-Here's how this might look in a fabfile::
-
- from fabric.api import *
- from fabric.contrib import project
-
- # Where the static files get collected locally
- env.local_static_root = '/tmp/static'
-
- # Where the static files should go remotely
- env.remote_static_root = '/home/www/static.example.com'
-
- @roles('static')
- def deploy_static():
- local('./manage.py collectstatic')
- project.rysnc_project(
- remote_dir = env.remote_static_root,
- local_dir = env.local_static_root,
- delete = True
- )
-
-.. _staticfiles-from-cdn:
-
-Serving static files from a cloud service or CDN
-------------------------------------------------
-
-Another common tactic is to serve static files from a cloud storage provider
-like Amazon's S3__ and/or a CDN (content delivery network). This lets you
-ignore the problems of serving static files, and can often make for
-faster-loading webpages (especially when using a CDN).
-
-When using these services, the basic workflow would look a bit like the above,
-except that instead of using ``rsync`` to transfer your static files to the
-server you'd need to transfer the static files to the storage provider or CDN.
-
-There's any number of ways you might do this, but if the provider has an API a
-:doc:`custom file storage backend ` will make the
-process incredibly simple. If you've written or are using a 3rd party custom
-storage backend, you can tell :djadmin:`collectstatic` to use it by setting
-:setting:`STATICFILES_STORAGE` to the storage engine.
-
-For example, if you've written an S3 storage backend in
-``myproject.storage.S3Storage`` you could use it with::
-
- STATICFILES_STORAGE = 'myproject.storage.S3Storage'
-
-Once that's done, all you have to do is run :djadmin:`collectstatic` and your
-static files would be pushed through your storage package up to S3. If you
-later needed to switch to a different storage provider, it could be as simple
-as changing your :setting:`STATICFILES_STORAGE` setting.
-
-For details on how you'd write one of these backends,
-:doc:`/howto/custom-file-storage`.
-
-.. seealso::
-
- The `django-storages`__ project is a 3rd party app that provides many
- storage backends for many common file storage APIs (including `S3`__).
-
-__ http://s3.amazonaws.com/
-__ http://code.larlet.fr/django-storages/
-__ http://django-storages.readthedocs.org/en/latest/backends/amazon-S3.html
-
-Upgrading from ``django-staticfiles``
-=====================================
-
-``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If
-you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to
-``django.contrib.staticfiles``, you'll need to make a few changes:
-
-* Application files should now live in a ``static`` directory in each app
- (`django-staticfiles`_ used the name ``media``, which was slightly
- confusing).
-
-* The management commands ``build_static`` and ``resolve_static`` are now
- called :djadmin:`collectstatic` and :djadmin:`findstatic`.
-
-* The settings ``STATICFILES_PREPEND_LABEL_APPS``,
- ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were
- removed.
-
-* The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the
- new :setting:`STATICFILES_FINDERS`.
-
-* The default for :setting:`STATICFILES_STORAGE` was renamed from
- ``staticfiles.storage.StaticFileStorage`` to
- ``staticfiles.storage.StaticFilesStorage``
-
-* If using :ref:`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
-==========
-
-This document has covered the basics and some common usage patterns. For
-complete details on all the settings, commands, template tags, and other pieces
-include in ``django.contrib.staticfiles``, see :doc:`the staticfiles reference
-`.
diff --git a/docs/index.txt b/docs/index.txt
index a5d2e13..11ddc41 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -102,7 +102,7 @@ The view layer
:doc:`Overview ` |
:doc:`File objects ` |
:doc:`Storage API ` |
- :doc:`Managing files ` |
+ :doc:`Managing media files `
* **Generic views:**
@@ -158,7 +158,7 @@ The development process
:doc:`FastCGI/SCGI/AJP ` |
:doc:`Apache/mod_python (deprecated) ` |
:doc:`Apache authentication ` |
- :doc:`Handling static files ` |
+ :doc:`Managing static files ` |
:doc:`Tracking code errors by email `
Other batteries included
diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt
index 75fa6b4..08e9496 100644
--- a/docs/misc/api-stability.txt
+++ b/docs/misc/api-stability.txt
@@ -47,7 +47,7 @@ of 1.0. This includes these APIs:
- :doc:`Sending email `.
-- :doc:`File handling and storage `
+- :doc:`Managing media files `
diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
index 1dbd00b..119b559 100644
--- a/docs/ref/contrib/staticfiles.txt
+++ b/docs/ref/contrib/staticfiles.txt
@@ -14,7 +14,7 @@ can easily be served in production.
.. seealso::
For an introduction to the static files app and some usage examples, see
- :doc:`/howto/static-files`.
+ :doc:`/topics/files/static`.
.. _staticfiles-settings:
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 5ea7280..deaa0eb 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -766,7 +766,7 @@ Serving static files with the development server
By default, the development server doesn't serve any static files for your site
(such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
-you want to configure Django to serve static media, read :doc:`/howto/static-files`.
+you want to configure Django to serve static media, read :doc:`/topics/files/static`.
shell
-----
@@ -1268,7 +1268,7 @@ collectstatic
~~~~~~~~~~~~~
This command is only available if the :doc:`static files application
-` (``django.contrib.staticfiles``) is installed.
+` (``django.contrib.staticfiles``) is installed.
Please refer to its :djadmin:`description ` in the
:doc:`staticfiles ` documentation.
@@ -1277,7 +1277,7 @@ findstatic
~~~~~~~~~~
This command is only available if the :doc:`static files application
-` (``django.contrib.staticfiles``) is installed.
+` (``django.contrib.staticfiles``) is installed.
Please refer to its :djadmin:`description ` in the :doc:`staticfiles
` documentation.
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 36bf60e..fe4f60d 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -533,7 +533,7 @@ Also has one optional argument:
.. attribute:: FileField.storage
Optional. A storage object, which handles the storage and retrieval of your
- files. See :doc:`/topics/files` for details on how to provide this object.
+ files. See :doc:`/topics/files/media for details on how to provide this object.
The admin represents this field as an ```` (a file-upload
widget).
@@ -569,7 +569,7 @@ If you wanted to retrieve the uploaded file's on-disk filename, or the file's
size, you could use the :attr:`~django.core.files.File.name` and
:attr:`~django.core.files.File.size` attributes respectively; for more
information on the available attributes and methods, see the
-:class:`~django.core.files.File` class reference and the :doc:`/topics/files`
+:class:`~django.core.files.File` class reference and the :doc:`/topics/files/media
topic guide.
.. note::
@@ -645,7 +645,7 @@ Or you can construct one from a Python string like this::
from django.core.files.base import ContentFile
myfile = ContentFile("hello world")
-For more information, see :doc:`/topics/files`.
+For more information, see :doc:`/topics/files/media.
.. method:: FieldFile.delete(save=True)
diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt
index c0ae73e..99a3e63 100644
--- a/docs/ref/request-response.txt
+++ b/docs/ref/request-response.txt
@@ -128,7 +128,7 @@ All attributes except ``session`` should be considered read-only.
``FILES`` is the ``name`` from the ````. Each
value in ``FILES`` is an :class:`UploadedFile` as described below.
- See :doc:`/topics/files` for more information.
+ See :doc:`/topics/files/media for more information.
Note that ``FILES`` will only contain data if the request method was POST
and the ```` that posted to the request had
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index c06ef1a..ecc8c83 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -877,7 +877,7 @@ DEFAULT_FILE_STORAGE
Default: :class:`django.core.files.storage.FileSystemStorage`
Default file storage class to be used for any file-related operations that don't
-specify a particular storage system. See :doc:`/topics/files`.
+specify a particular storage system. See :doc:`/topics/files/media.
.. setting:: DEFAULT_FROM_EMAIL
@@ -1030,7 +1030,7 @@ Default::
("django.core.files.uploadhandler.MemoryFileUploadHandler",
"django.core.files.uploadhandler.TemporaryFileUploadHandler",)
-A tuple of handlers to use for uploading. See :doc:`/topics/files` for details.
+A tuple of handlers to use for uploading. See :doc:`/topics/files/media for details.
.. setting:: FILE_UPLOAD_MAX_MEMORY_SIZE
@@ -1040,7 +1040,7 @@ FILE_UPLOAD_MAX_MEMORY_SIZE
Default: ``2621440`` (i.e. 2.5 MB).
The maximum size (in bytes) that an upload will be before it gets streamed to
-the file system. See :doc:`/topics/files` for details.
+the file system. See :doc:`/topics/files/media for details.
.. setting:: FILE_UPLOAD_PERMISSIONS
@@ -1079,7 +1079,7 @@ The directory to store data temporarily while uploading files. If ``None``,
Django will use the standard temporary directory for the operating system. For
example, this will default to '/tmp' on \*nix-style operating systems.
-See :doc:`/topics/files` for details.
+See :doc:`/topics/files/media for details.
.. setting:: FIRST_DAY_OF_WEEK
@@ -1402,7 +1402,7 @@ MEDIA_ROOT
Default: ``''`` (Empty string)
Absolute path to the directory that holds media for this installation, used
-for :doc:`managing stored files `.
+for :doc:`managing media files `.
+for :doc:`managing media files ` contrib app is enabled
(default) the :djadmin:`collectstatic` management command will collect static
files into this directory. See the howto on :doc:`managing static
-files` for more details about usage.
+files` for more details about usage.
.. warning::
diff --git a/docs/releases/1.0-alpha-2.txt b/docs/releases/1.0-alpha-2.txt
index a26a214..85483d0 100644
--- a/docs/releases/1.0-alpha-2.txt
+++ b/docs/releases/1.0-alpha-2.txt
@@ -36,7 +36,7 @@ Pluggable file storage
Django's built-in ``FileField`` and ``ImageField`` now can take advantage of
pluggable file-storage backends, allowing extensive customization of where
and how uploaded files get stored by Django. For details, see :doc:`the
- files documentation `; big thanks go to Marty Alchin for
+ files documentation `; big thanks go to Marty Alchin for putting in the
+documentation `
for more details or learn how to :doc:`manage static files
-`.
+`.
``unittest2`` support
~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/releases/1.3-beta-1.txt b/docs/releases/1.3-beta-1.txt
index 02c038f..f5fd101 100644
--- a/docs/releases/1.3-beta-1.txt
+++ b/docs/releases/1.3-beta-1.txt
@@ -37,7 +37,7 @@ Based on feedback from the community this release adds two new options to the
See the :doc:`staticfiles reference documentation `
for more details, or learn :doc:`how to manage static files
-`.
+`.
Translation comments
~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt
index 224cd47..3bdbc49 100644
--- a/docs/releases/1.3.txt
+++ b/docs/releases/1.3.txt
@@ -115,7 +115,7 @@ at :setting:`STATIC_URL`.
See the :doc:`reference documentation of the app `
for more details or learn how to :doc:`manage static files
-`.
+`.
unittest2 support
~~~~~~~~~~~~~~~~~
diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt
index b5ec782..09aa4a1 100644
--- a/docs/releases/1.4-alpha-1.txt
+++ b/docs/releases/1.4-alpha-1.txt
@@ -578,7 +578,7 @@ If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g.
``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT`
are configured and your web server serves the files correctly. The development
server continues to serve the admin files just like before. Don't hesitate to
-consult the :doc:`static files howto ` for further
+consult the :doc:`static files topic ` for further
details.
In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.
diff --git a/docs/releases/1.4-beta-1.txt b/docs/releases/1.4-beta-1.txt
index 88f32ea..8213425 100644
--- a/docs/releases/1.4-beta-1.txt
+++ b/docs/releases/1.4-beta-1.txt
@@ -646,7 +646,7 @@ If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g.
``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT`
are configured and your web server serves the files correctly. The development
server continues to serve the admin files just like before. Don't hesitate to
-consult the :doc:`static files howto ` for further
+consult the :doc:`static files topic ` for further
details.
In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index 51766dc..b999fcc 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -708,7 +708,7 @@ If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g.
``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT`
are configured and your Web server serves those files correctly. The
development server continues to serve the admin files just like before. Read
-the :doc:`static files howto ` for more details.
+the :doc:`static files topic ` for more details.
If your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.
``http://media.example.com/admin/``), make sure to also set your
diff --git a/docs/topics/files.txt b/docs/topics/files.txt
deleted file mode 100644
index 9ab8d5c..0000000
--- a/docs/topics/files.txt
+++ /dev/null
@@ -1,151 +0,0 @@
-==============
-Managing files
-==============
-
-This document describes Django's file access APIs.
-
-By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and
-:setting:`MEDIA_URL` settings. The examples below assume that you're using these
-defaults.
-
-However, Django provides ways to write custom `file storage systems`_ that
-allow you to completely customize where and how Django stores files. The
-second half of this document describes how these storage systems work.
-
-.. _file storage systems: `File storage`_
-
-Using files in models
-=====================
-
-When you use a :class:`~django.db.models.FileField` or
-:class:`~django.db.models.ImageField`, Django provides a set of APIs you can use
-to deal with that file.
-
-Consider the following model, using an :class:`~django.db.models.ImageField` to
-store a photo::
-
- class Car(models.Model):
- name = models.CharField(max_length=255)
- price = models.DecimalField(max_digits=5, decimal_places=2)
- photo = models.ImageField(upload_to='cars')
-
-Any ``Car`` instance will have a ``photo`` attribute that you can use to get at
-the details of the attached photo::
-
- >>> car = Car.objects.get(name="57 Chevy")
- >>> car.photo
-
- >>> car.photo.name
- u'cars/chevy.jpg'
- >>> car.photo.path
- u'/media/cars/chevy.jpg'
- >>> car.photo.url
- u'http://media.example.com/cars/chevy.jpg'
-
-This object -- ``car.photo`` in the example -- is a ``File`` object, which means
-it has all the methods and attributes described below.
-
-.. note::
- The file is saved as part of saving the model in the database, so the actual
- file name used on disk cannot be relied on until after the model has been
- saved.
-
-
-The ``File`` object
-===================
-
-Internally, Django uses a :class:`django.core.files.File` instance any time it
-needs to represent a file. This object is a thin wrapper around Python's
-`built-in file object`_ with some Django-specific additions.
-
-.. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects
-
-Most of the time you'll simply use a ``File`` that Django's given you (i.e. a
-file attached to a model as above, or perhaps an uploaded file).
-
-If you need to construct a ``File`` yourself, the easiest way is to create one
-using a Python built-in ``file`` object::
-
- >>> from django.core.files import File
-
- # Create a Python file object using open()
- >>> f = open('/tmp/hello.world', 'w')
- >>> myfile = File(f)
-
-Now you can use any of the documented attributes and methods
-of the :class:`~django.core.files.File` class.
-
-File storage
-============
-
-Behind the scenes, Django delegates decisions about how and where to store files
-to a file storage system. This is the object that actually understands things
-like file systems, opening and reading files, etc.
-
-Django's default file storage is given by the :setting:`DEFAULT_FILE_STORAGE`
-setting; if you don't explicitly provide a storage system, this is the one that
-will be used.
-
-See below for details of the built-in default file storage system, and see
-:doc:`/howto/custom-file-storage` for information on writing your own file
-storage system.
-
-Storage objects
----------------
-
-Though most of the time you'll want to use a ``File`` object (which delegates to
-the proper storage for that file), you can use file storage systems directly.
-You can create an instance of some custom file storage class, or -- often more
-useful -- you can use the global default storage system::
-
- >>> from django.core.files.storage import default_storage
- >>> from django.core.files.base import ContentFile
-
- >>> path = default_storage.save('/path/to/file', ContentFile('new content'))
- >>> path
- u'/path/to/file'
-
- >>> default_storage.size(path)
- 11
- >>> default_storage.open(path).read()
- 'new content'
-
- >>> default_storage.delete(path)
- >>> default_storage.exists(path)
- False
-
-See :doc:`/ref/files/storage` for the file storage API.
-
-The built-in filesystem storage class
--------------------------------------
-
-Django ships with a built-in ``FileSystemStorage`` class (defined in
-``django.core.files.storage``) which implements basic local filesystem file
-storage. Its initializer takes two arguments:
-
-====================== ===================================================
-Argument Description
-====================== ===================================================
-``location`` Optional. Absolute path to the directory that will
- hold the files. If omitted, it will be set to the
- value of your :setting:`MEDIA_ROOT` setting.
-``base_url`` Optional. URL that serves the files stored at this
- location. If omitted, it will default to the value
- of your :setting:`MEDIA_URL` setting.
-====================== ===================================================
-
-For example, the following code will store uploaded files under
-``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::
-
- from django.db import models
- from django.core.files.storage import FileSystemStorage
-
- fs = FileSystemStorage(location='/media/photos')
-
- class Car(models.Model):
- ...
- photo = models.ImageField(storage=fs)
-
-:doc:`Custom storage systems ` work the same way:
-you can pass them in as the ``storage`` argument to a
-:class:`~django.db.models.FileField`.
diff --git a/docs/topics/files/media.txt b/docs/topics/files/media.txt
new file mode 100644
index 0000000..ec82fab
--- /dev/null
+++ b/docs/topics/files/media.txt
@@ -0,0 +1,153 @@
+====================
+Managing media files
+====================
+
+This document describes Django's file access APIs for media files.
+Il you want to handle static files (JS, CSS, etc), see
+:doc:`/topics/files/static`
+
+By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and
+:setting:`MEDIA_URL` settings. The examples below assume that you're using these
+defaults.
+
+However, Django provides ways to write custom `file storage systems`_ that
+allow you to completely customize where and how Django stores files. The
+second half of this document describes how these storage systems work.
+
+.. _file storage systems: `File storage`_
+
+Using files in models
+=====================
+
+When you use a :class:`~django.db.models.FileField` or
+:class:`~django.db.models.ImageField`, Django provides a set of APIs you can use
+to deal with that file.
+
+Consider the following model, using an :class:`~django.db.models.ImageField` to
+store a photo::
+
+ class Car(models.Model):
+ name = models.CharField(max_length=255)
+ price = models.DecimalField(max_digits=5, decimal_places=2)
+ photo = models.ImageField(upload_to='cars')
+
+Any ``Car`` instance will have a ``photo`` attribute that you can use to get at
+the details of the attached photo::
+
+ >>> car = Car.objects.get(name="57 Chevy")
+ >>> car.photo
+
+ >>> car.photo.name
+ u'cars/chevy.jpg'
+ >>> car.photo.path
+ u'/media/cars/chevy.jpg'
+ >>> car.photo.url
+ u'http://media.example.com/cars/chevy.jpg'
+
+This object -- ``car.photo`` in the example -- is a ``File`` object, which means
+it has all the methods and attributes described below.
+
+.. note::
+ The file is saved as part of saving the model in the database, so the actual
+ file name used on disk cannot be relied on until after the model has been
+ saved.
+
+
+The ``File`` object
+===================
+
+Internally, Django uses a :class:`django.core.files.File` instance any time it
+needs to represent a file. This object is a thin wrapper around Python's
+`built-in file object`_ with some Django-specific additions.
+
+.. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects
+
+Most of the time you'll simply use a ``File`` that Django's given you (i.e. a
+file attached to a model as above, or perhaps an uploaded file).
+
+If you need to construct a ``File`` yourself, the easiest way is to create one
+using a Python built-in ``file`` object::
+
+ >>> from django.core.files import File
+
+ # Create a Python file object using open()
+ >>> f = open('/tmp/hello.world', 'w')
+ >>> myfile = File(f)
+
+Now you can use any of the documented attributes and methods
+of the :class:`~django.core.files.File` class.
+
+File storage
+============
+
+Behind the scenes, Django delegates decisions about how and where to store files
+to a file storage system. This is the object that actually understands things
+like file systems, opening and reading files, etc.
+
+Django's default file storage is given by the :setting:`DEFAULT_FILE_STORAGE`
+setting; if you don't explicitly provide a storage system, this is the one that
+will be used.
+
+See below for details of the built-in default file storage system, and see
+:doc:`/howto/custom-file-storage` for information on writing your own file
+storage system.
+
+Storage objects
+---------------
+
+Though most of the time you'll want to use a ``File`` object (which delegates to
+the proper storage for that file), you can use file storage systems directly.
+You can create an instance of some custom file storage class, or -- often more
+useful -- you can use the global default storage system::
+
+ >>> from django.core.files.storage import default_storage
+ >>> from django.core.files.base import ContentFile
+
+ >>> path = default_storage.save('/path/to/file', ContentFile('new content'))
+ >>> path
+ u'/path/to/file'
+
+ >>> default_storage.size(path)
+ 11
+ >>> default_storage.open(path).read()
+ 'new content'
+
+ >>> default_storage.delete(path)
+ >>> default_storage.exists(path)
+ False
+
+See :doc:`/ref/files/storage` for the file storage API.
+
+The built-in filesystem storage class
+-------------------------------------
+
+Django ships with a built-in ``FileSystemStorage`` class (defined in
+``django.core.files.storage``) which implements basic local filesystem file
+storage. Its initializer takes two arguments:
+
+====================== ===================================================
+Argument Description
+====================== ===================================================
+``location`` Optional. Absolute path to the directory that will
+ hold the files. If omitted, it will be set to the
+ value of your :setting:`MEDIA_ROOT` setting.
+``base_url`` Optional. URL that serves the files stored at this
+ location. If omitted, it will default to the value
+ of your :setting:`MEDIA_URL` setting.
+====================== ===================================================
+
+For example, the following code will store uploaded files under
+``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::
+
+ from django.db import models
+ from django.core.files.storage import FileSystemStorage
+
+ fs = FileSystemStorage(location='/media/photos')
+
+ class Car(models.Model):
+ ...
+ photo = models.ImageField(storage=fs)
+
+:doc:`Custom storage systems ` work the same way:
+you can pass them in as the ``storage`` argument to a
+:class:`~django.db.models.FileField`.
diff --git a/docs/topics/files/static.txt b/docs/topics/files/static.txt
new file mode 100644
index 0000000..e3a40a1
--- /dev/null
+++ b/docs/topics/files/static.txt
@@ -0,0 +1,510 @@
+=====================
+Managing static files
+=====================
+
+.. versionadded:: 1.3
+
+Django developers mostly concern themselves with the dynamic parts of web
+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.
+
+For small projects, this isn't a big deal, because you can just keep the
+static files somewhere your web server can find it. However, in bigger
+projects -- especially those comprised of multiple apps -- dealing with the
+multiple sets of static files provided by each application starts to get
+tricky.
+
+That's what ``django.contrib.staticfiles`` is for: it 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.
+
+.. note::
+
+ If you've used the `django-staticfiles`_ third-party app before, then
+ ``django.contrib.staticfiles`` will look very familiar. That's because
+ they're essentially the same code: ``django.contrib.staticfiles`` started
+ its life as `django-staticfiles`_ and was merged into Django 1.3.
+
+ If you're upgrading from ``django-staticfiles``, please see `Upgrading from
+ django-staticfiles`_, below, for a few minor changes you'll need to make.
+
+.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
+
+Using ``django.contrib.staticfiles``
+====================================
+
+Basic usage
+-----------
+
+1. Put your static files somewhere that ``staticfiles`` will find them.
+
+ By default, this means within ``static/`` subdirectories of apps in your
+ :setting:`INSTALLED_APPS`.
+
+ Your project will probably also have static assets that aren't tied to a
+ particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of
+ filesystem directories to check when loading static files. It's a search
+ path that is by default empty. See the :setting:`STATICFILES_DIRS` docs
+ how to extend this list of additional paths.
+
+ Additionally, see the documentation for the :setting:`STATICFILES_FINDERS`
+ setting for details on how ``staticfiles`` finds your files.
+
+2. Make sure that ``django.contrib.staticfiles`` is included in your
+ :setting:`INSTALLED_APPS`.
+
+ For :ref:`local development`, if you are using
+ :ref:`runserver` or adding
+ :ref:`staticfiles_urlpatterns` to your
+ URLconf, you're done with the setup -- your static files will
+ automatically be served at the default (for
+ :djadmin:`newly created` projects) :setting:`STATIC_URL`
+ of ``/static/``.
+
+3. You'll probably need to refer to these files in your templates. The
+ easiest method is to use the included context processor which allows
+ template code like:
+
+ .. code-block:: html+django
+
+
+
+ See :ref:`staticfiles-in-templates` for more details, **including** an
+ alternate method using a template tag.
+
+Deploying static files in a nutshell
+------------------------------------
+
+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 most cases, the default value of ``/static/`` is just fine).
+
+2. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path
+ 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 `.
+
+.. note::
+
+ In previous versions of Django, it was common to place static assets in
+ :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both
+ at :setting:`MEDIA_URL`. Part of the purpose of introducing the
+ ``staticfiles`` app is to make it easier to keep static files separate
+ from user-uploaded files.
+
+ For this reason, you need to make your :setting:`MEDIA_ROOT` and
+ :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. You can, however, use
+ :func:`django.views.static.serve` view for serving :setting:`MEDIA_ROOT`
+ in development; see :ref:`staticfiles-other-directories`.
+
+.. _staticfiles-in-templates:
+
+Referring to static files in templates
+======================================
+
+At some point, you'll probably need to link to static files in your templates.
+You could, of course, simply hardcode the path to you assets in the templates:
+
+.. code-block:: html
+
+
+
+Of course, there are some serious problems with this: it doesn't work well in
+development, and it makes it *very* hard to change where you've deployed your
+static files. If, for example, you wanted to switch to using a content
+delivery network (CDN), then you'd need to change more or less every single
+template.
+
+A far better way is to use the value of the :setting:`STATIC_URL` setting
+directly in your templates. This means that a switch of static files servers
+only requires changing that single value. Much better!
+
+Django includes multiple built-in ways of using this setting in your
+templates: a context processor and a template tag.
+
+With a context processor
+------------------------
+
+The included context processor is the easy way. Simply make sure
+``'django.core.context_processors.static'`` is in your
+:setting:`TEMPLATE_CONTEXT_PROCESSORS`. It's there by default, and if you're
+editing that setting by hand it should look something like::
+
+ TEMPLATE_CONTEXT_PROCESSORS = (
+ 'django.core.context_processors.debug',
+ 'django.core.context_processors.i18n',
+ 'django.core.context_processors.media',
+ 'django.core.context_processors.static',
+ 'django.contrib.auth.context_processors.auth',
+ 'django.contrib.messages.context_processors.messages',
+ )
+
+Once that's done, you can refer to :setting:`STATIC_URL` in your templates:
+
+.. code-block:: html+django
+
+
+
+If ``{{ STATIC_URL }}`` isn't working in your template, you're probably not
+using :class:`~django.template.RequestContext` when rendering the template.
+
+As a brief refresher, context processors add variables into the contexts of
+every template. However, context processors require that you use
+:class:`~django.template.RequestContext` when rendering templates. This happens
+automatically if you're using a :doc:`generic view `,
+but in views written by hand you'll need to explicitly use ``RequestContext``
+To see how that works, and to read more details, check out
+:ref:`subclassing-context-requestcontext`.
+
+Another option is the :ttag:`get_static_prefix` template tag that is part of
+Django's core.
+
+With a template tag
+-------------------
+
+The more powerful tool is the :ttag:`static` template
+tag. It builds the URL for the given relative path by using the configured
+:setting:`STATICFILES_STORAGE` storage.
+
+.. code-block:: html+django
+
+ {% load staticfiles %}
+
+
+It is also able to consume standard context variables, e.g. assuming a
+``user_stylesheet`` variable is passed to the template:
+
+.. code-block:: html+django
+
+ {% load staticfiles %}
+
+
+.. note::
+
+ There is also a template tag named :ttag:`static` in Django's core set
+ of :ref:`built in template tags` which has
+ the same argument signature but only uses `urlparse.urljoin()`_ with the
+ :setting:`STATIC_URL` setting and the given path. This has the
+ disadvantage of not being able to easily switch the storage backend
+ without changing the templates, so in doubt use the ``staticfiles``
+ :ttag:`static`
+ template tag.
+
+.. _`urlparse.urljoin()`: http://docs.python.org/library/urlparse.html#urlparse.urljoin
+
+.. _staticfiles-development:
+
+Serving static files in development
+===================================
+
+The static files tools are mostly designed to help with getting static files
+successfully deployed into production. This usually means a separate,
+dedicated static file 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 files locally in
+development.
+
+This view is automatically enabled and will serve your static files at
+:setting:`STATIC_URL` when you use the built-in
+:ref:`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
+of the file, and the last line at the bottom::
+
+ from django.contrib.staticfiles.urls import staticfiles_urlpatterns
+
+ # ... the rest of your URLconf goes here ...
+
+ urlpatterns += staticfiles_urlpatterns()
+
+This will inspect your :setting:`STATIC_URL` setting and wire up the view
+to serve static files accordingly. Don't forget to set the
+:setting:`STATICFILES_DIRS` setting appropriately to let
+``django.contrib.staticfiles`` know where to look for files additionally to
+files in app directories.
+
+.. warning::
+
+ This will only work if :setting:`DEBUG` is ``True``.
+
+ That's because this view is **grossly inefficient** and probably
+ **insecure**. This is only intended for local development, and should
+ **never be used in production**.
+
+ Additionally, when using ``staticfiles_urlpatterns`` your
+ :setting:`STATIC_URL` setting can't be empty or a full URL, such as
+ ``http://static.example.com/``.
+
+For a few more details on how the ``staticfiles`` can be used during
+development, see :ref:`staticfiles-development-view`.
+
+.. _staticfiles-other-directories:
+
+Serving other directories
+-------------------------
+
+.. currentmodule:: django.views.static
+.. function:: serve(request, path, document_root, show_indexes=False)
+
+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.views.static.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
+
+ # ... the rest of your URLconf goes here ...
+
+ if settings.DEBUG:
+ urlpatterns += patterns('',
+ url(r'^media/(?P.*)$', 'django.views.static.serve', {
+ 'document_root': settings.MEDIA_ROOT,
+ }),
+ )
+
+Note, the snippet assumes your :setting:`MEDIA_URL` has a value of
+``'/media/'``. This will call the :func:`~django.views.static.serve` view,
+passing in the path from the URLconf and the (required) ``document_root``
+parameter.
+
+.. currentmodule:: django.conf.urls.static
+.. function:: static(prefix, view='django.views.static.serve', **kwargs)
+
+Since it can become a bit cumbersome to define this URL pattern, Django
+ships with a small URL helper function
+:func:`~django.conf.urls.static.static` that takes as parameters the prefix
+such as :setting:`MEDIA_URL` and a dotted path to a view, such as
+``'django.views.static.serve'``. Any other function parameter will be
+transparently passed to the view.
+
+An example for serving :setting:`MEDIA_URL` (``'/media/'``) during
+development::
+
+ from django.conf import settings
+ from django.conf.urls.static import static
+
+ urlpatterns = patterns('',
+ # ... the rest of your URLconf goes here ...
+ ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
+
+.. note::
+
+ This helper function will only be operational in debug mode and if
+ the given prefix is local (e.g. ``/static/``) and not a URL (e.g.
+ ``http://static.example.com/``).
+
+.. _staticfiles-production:
+
+Serving static files in production
+==================================
+
+The basic outline of putting static files into production is simple: run the
+:djadmin:`collectstatic` command when static files change, then arrange for
+the collected static files directory (:setting:`STATIC_ROOT`) to be moved to
+the static file server and served.
+
+Of course, as with all deployment tasks, the devil's in the details. Every
+production setup will be a bit different, so you'll need to adapt the basic
+outline to fit your needs. Below are a few common patterns that might help.
+
+Serving the app and your static files from the same server
+----------------------------------------------------------
+
+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 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 `.
+
+You'll probably want to automate this process, especially if you've got
+multiple web servers. There's any number of ways to do this automation, but
+one option that many Django developers enjoy is `Fabric`__.
+
+__ http://fabfile.org/
+
+Below, and in the following sections, we'll show off a few example fabfiles
+(i.e. Fabric scripts) that automate these file deployment options. The syntax
+of a fabfile is fairly straightforward but won't be covered here; consult
+`Fabric's documentation`__, for a complete explanation of the syntax..
+
+__ http://docs.fabfile.org/
+
+So, a fabfile to deploy static files to a couple of web servers might look
+something like::
+
+ from fabric.api import *
+
+ # Hosts to deploy onto
+ env.hosts = ['www1.example.com', 'www2.example.com']
+
+ # Where your project code lives on the server
+ env.project_root = '/home/www/myproject'
+
+ def deploy_static():
+ with cd(env.project_root):
+ run('./manage.py collectstatic -v0 --noinput')
+
+Serving static files from a dedicated server
+--------------------------------------------
+
+Most larger Django apps use a separate Web server -- i.e., one that's not also
+running Django -- for serving static files. This server often runs a different
+type of web server -- faster but less full-featured. Some good choices are:
+
+* lighttpd_
+* Nginx_
+* TUX_
+* Cherokee_
+* A stripped-down version of Apache_
+
+.. _lighttpd: http://www.lighttpd.net/
+.. _Nginx: http://wiki.nginx.org/Main
+.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
+.. _Apache: http://httpd.apache.org/
+.. _Cherokee: http://www.cherokee-project.com/
+
+Configuring these servers is out of scope of this document; check each
+server's respective documentation for instructions.
+
+Since your static file server won't be running Django, you'll need to modify
+the deployment strategy to look something like:
+
+* When your static files change, run :djadmin:`collectstatic` locally.
+* Push your local :setting:`STATIC_ROOT` up to the static file server
+ into the directory that's being served. ``rsync`` is a good
+ choice for this step since it only needs to transfer the
+ bits of static files that have changed.
+
+Here's how this might look in a fabfile::
+
+ from fabric.api import *
+ from fabric.contrib import project
+
+ # Where the static files get collected locally
+ env.local_static_root = '/tmp/static'
+
+ # Where the static files should go remotely
+ env.remote_static_root = '/home/www/static.example.com'
+
+ @roles('static')
+ def deploy_static():
+ local('./manage.py collectstatic')
+ project.rysnc_project(
+ remote_dir = env.remote_static_root,
+ local_dir = env.local_static_root,
+ delete = True
+ )
+
+.. _staticfiles-from-cdn:
+
+Serving static files from a cloud service or CDN
+------------------------------------------------
+
+Another common tactic is to serve static files from a cloud storage provider
+like Amazon's S3__ and/or a CDN (content delivery network). This lets you
+ignore the problems of serving static files, and can often make for
+faster-loading webpages (especially when using a CDN).
+
+When using these services, the basic workflow would look a bit like the above,
+except that instead of using ``rsync`` to transfer your static files to the
+server you'd need to transfer the static files to the storage provider or CDN.
+
+There's any number of ways you might do this, but if the provider has an API a
+:doc:`custom file storage backend ` will make the
+process incredibly simple. If you've written or are using a 3rd party custom
+storage backend, you can tell :djadmin:`collectstatic` to use it by setting
+:setting:`STATICFILES_STORAGE` to the storage engine.
+
+For example, if you've written an S3 storage backend in
+``myproject.storage.S3Storage`` you could use it with::
+
+ STATICFILES_STORAGE = 'myproject.storage.S3Storage'
+
+Once that's done, all you have to do is run :djadmin:`collectstatic` and your
+static files would be pushed through your storage package up to S3. If you
+later needed to switch to a different storage provider, it could be as simple
+as changing your :setting:`STATICFILES_STORAGE` setting.
+
+For details on how you'd write one of these backends,
+:doc:`/howto/custom-file-storage`.
+
+.. seealso::
+
+ The `django-storages`__ project is a 3rd party app that provides many
+ storage backends for many common file storage APIs (including `S3`__).
+
+__ http://s3.amazonaws.com/
+__ http://code.larlet.fr/django-storages/
+__ http://django-storages.readthedocs.org/en/latest/backends/amazon-S3.html
+
+Upgrading from ``django-staticfiles``
+=====================================
+
+``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If
+you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to
+``django.contrib.staticfiles``, you'll need to make a few changes:
+
+* Application files should now live in a ``static`` directory in each app
+ (`django-staticfiles`_ used the name ``media``, which was slightly
+ confusing).
+
+* The management commands ``build_static`` and ``resolve_static`` are now
+ called :djadmin:`collectstatic` and :djadmin:`findstatic`.
+
+* The settings ``STATICFILES_PREPEND_LABEL_APPS``,
+ ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were
+ removed.
+
+* The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the
+ new :setting:`STATICFILES_FINDERS`.
+
+* The default for :setting:`STATICFILES_STORAGE` was renamed from
+ ``staticfiles.storage.StaticFileStorage`` to
+ ``staticfiles.storage.StaticFilesStorage``
+
+* If using :ref:`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
+==========
+
+This document has covered the basics and some common usage patterns. For
+complete details on all the settings, commands, template tags, and other pieces
+include in ``django.contrib.staticfiles``, see :doc:`the staticfiles reference
+`.
diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index 829e059..a72a2b7 100644
--- a/docs/topics/testing.txt
+++ b/docs/topics/testing.txt
@@ -1946,7 +1946,7 @@ out the `full reference`_ for more details.
.. note::
``LiveServerTestCase`` makes use of the :doc:`staticfiles contrib app
- ` so you'll need to have your project configured
+ ` so you'll need to have your project configured
accordingly (in particular by setting :setting:`STATIC_URL`).
.. note::
--
1.7.9.4