Ticket #17935: 0001-cleaning-media-and-static-files-docs-urls.patch

File 0001-cleaning-media-and-static-files-docs-urls.patch, 67.1 KB (added by Adrien Lemaire, 13 years ago)

  • deleted file docs/howto/static-files.txt 

    From 4966dae988a921034d31c1b856078f96eba7373d Mon Sep 17 00:00:00 2001
From: Adrien Lemaire <lemaire.adrien@gmail.com>
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
    + -  
    1 =====================
    2 Managing static files
    3 =====================
    4 
    5 .. versionadded:: 1.3
    6 
    7 Django developers mostly concern themselves with the dynamic parts of web
    8 applications -- the views and templates that render anew for each request. But
    9 web applications have other parts: the static files (images, CSS,
    10 Javascript, etc.) that are needed to render a complete web page.
    11 
    12 For small projects, this isn't a big deal, because you can just keep the
    13 static files somewhere your web server can find it. However, in bigger
    14 projects -- especially those comprised of multiple apps -- dealing with the
    15 multiple sets of static files provided by each application starts to get
    16 tricky.
    17 
    18 That's what ``django.contrib.staticfiles`` is for: it collects static files
    19 from each of your applications (and any other places you specify) into a
    20 single location that can easily be served in production.
    21 
    22 .. note::
    23 
    24     If you've used the `django-staticfiles`_ third-party app before, then
    25     ``django.contrib.staticfiles`` will look very familiar. That's because
    26     they're essentially the same code: ``django.contrib.staticfiles`` started
    27     its life as `django-staticfiles`_ and was merged into Django 1.3.
    28 
    29     If you're upgrading from ``django-staticfiles``, please see `Upgrading from
    30     django-staticfiles`_, below, for a few minor changes you'll need to make.
    31 
    32 .. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
    33 
    34 Using ``django.contrib.staticfiles``
    35 ====================================
    36 
    37 Basic usage
    38 -----------
    39 
    40 1. Put your static files somewhere that ``staticfiles`` will find them.
    41 
    42    By default, this means within ``static/`` subdirectories of apps in your
    43    :setting:`INSTALLED_APPS`.
    44 
    45    Your project will probably also have static assets that aren't tied to a
    46    particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of
    47    filesystem directories to check when loading static files. It's a search
    48    path that is by default empty. See the :setting:`STATICFILES_DIRS` docs
    49    how to extend this list of additional paths.
    50 
    51    Additionally, see the documentation for the :setting:`STATICFILES_FINDERS`
    52    setting for details on how ``staticfiles`` finds your files.
    53 
    54 2. Make sure that ``django.contrib.staticfiles`` is included in your
    55    :setting:`INSTALLED_APPS`.
    56 
    57    For :ref:`local development<staticfiles-development>`, if you are using
    58    :ref:`runserver<staticfiles-runserver>` or adding
    59    :ref:`staticfiles_urlpatterns<staticfiles-development>` to your
    60    URLconf, you're done with the setup -- your static files will
    61    automatically be served at the default (for
    62    :djadmin:`newly created<startproject>` projects) :setting:`STATIC_URL`
    63    of ``/static/``.
    64 
    65 3. You'll probably need to refer to these files in your templates. The
    66    easiest method is to use the included context processor which allows
    67    template code like:
    68 
    69    .. code-block:: html+django
    70 
    71        <img src="{{ STATIC_URL }}images/hi.jpg" />
    72 
    73    See :ref:`staticfiles-in-templates` for more details, **including** an
    74    alternate method using a template tag.
    75 
    76 Deploying static files in a nutshell
    77 ------------------------------------
    78 
    79 When you're ready to move out of local development and deploy your project:
    80 
    81 1. Set the :setting:`STATIC_URL` setting to the public URL for your static
    82    files (in most cases, the default value of ``/static/`` is just fine).
    83 
    84 2. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path
    85    you'd like your static files collected to when you use the
    86    :djadmin:`collectstatic` management command. For example::
    87 
    88        STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
    89 
    90 3. Run the :djadmin:`collectstatic` management command::
    91 
    92        ./manage.py collectstatic
    93 
    94    This'll churn through your static file storage and copy them into the
    95    directory given by :setting:`STATIC_ROOT`.
    96 
    97 4. Deploy those files by configuring your webserver of choice to serve the
    98    files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
    99 
    100    :ref:`staticfiles-production` covers some common deployment strategies
    101    for static files.
    102 
    103 Those are the **basics**. For more details on common configuration options,
    104 read on; for a detailed reference of the settings, commands, and other bits
    105 included with the framework see
    106 :doc:`the staticfiles reference </ref/contrib/staticfiles>`.
    107 
    108 .. note::
    109 
    110    In previous versions of Django, it was common to place static assets in
    111    :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both
    112    at :setting:`MEDIA_URL`. Part of the purpose of introducing the
    113    ``staticfiles`` app is to make it easier to keep static files separate
    114    from user-uploaded files.
    115 
    116    For this reason, you need to make your :setting:`MEDIA_ROOT` and
    117    :setting:`MEDIA_URL` different from your :setting:`STATIC_ROOT` and
    118    :setting:`STATIC_URL`. You will need to arrange for serving of files in
    119    :setting:`MEDIA_ROOT` yourself; ``staticfiles`` does not deal with
    120    user-uploaded files at all. You can, however, use
    121    :func:`django.views.static.serve` view for serving :setting:`MEDIA_ROOT`
    122    in development; see :ref:`staticfiles-other-directories`.
    123 
    124 .. _staticfiles-in-templates:
    125 
    126 Referring to static files in templates
    127 ======================================
    128 
    129 At some point, you'll probably need to link to static files in your templates.
    130 You could, of course, simply hardcode the path to you assets in the templates:
    131 
    132 .. code-block:: html
    133 
    134     <img src="http://static.example.com/static/myimage.jpg" />
    135 
    136 Of course, there are some serious problems with this: it doesn't work well in
    137 development, and it makes it *very* hard to change where you've deployed your
    138 static files. If, for example, you wanted to switch to using a content
    139 delivery network (CDN), then you'd need to change more or less every single
    140 template.
    141 
    142 A far better way is to use the value of the :setting:`STATIC_URL` setting
    143 directly in your templates. This means that a switch of static files servers
    144 only requires changing that single value. Much better!
    145 
    146 Django includes multiple built-in ways of using this setting in your
    147 templates: a context processor and a template tag.
    148 
    149 With a context processor
    150 ------------------------
    151 
    152 The included context processor is the easy way. Simply make sure
    153 ``'django.core.context_processors.static'`` is in your
    154 :setting:`TEMPLATE_CONTEXT_PROCESSORS`. It's there by default, and if you're
    155 editing that setting by hand it should look something like::
    156 
    157     TEMPLATE_CONTEXT_PROCESSORS = (
    158         'django.core.context_processors.debug',
    159         'django.core.context_processors.i18n',
    160         'django.core.context_processors.media',
    161         'django.core.context_processors.static',
    162         'django.contrib.auth.context_processors.auth',
    163         'django.contrib.messages.context_processors.messages',
    164     )
    165 
    166 Once that's done, you can refer to :setting:`STATIC_URL` in your templates:
    167 
    168 .. code-block:: html+django
    169 
    170      <img src="{{ STATIC_URL }}images/hi.jpg" />
    171 
    172 If ``{{ STATIC_URL }}`` isn't working in your template, you're probably not
    173 using :class:`~django.template.RequestContext` when rendering the template.
    174 
    175 As a brief refresher, context processors add variables into the contexts of
    176 every template. However, context processors require that you use
    177 :class:`~django.template.RequestContext` when rendering templates. This happens
    178 automatically if you're using a :doc:`generic view </ref/class-based-views>`,
    179 but in views written by hand you'll need to explicitly use ``RequestContext``
    180 To see how that works, and to read more details, check out
    181 :ref:`subclassing-context-requestcontext`.
    182 
    183 Another option is the :ttag:`get_static_prefix` template tag that is part of
    184 Django's core.
    185 
    186 With a template tag
    187 -------------------
    188 
    189 The more powerful tool is the :ttag:`static<staticfiles-static>` template
    190 tag. It builds the URL for the given relative path by using the configured
    191 :setting:`STATICFILES_STORAGE` storage.
    192 
    193 .. code-block:: html+django
    194 
    195     {% load staticfiles %}
    196     <img src="{% static "images/hi.jpg" %}" />
    197 
    198 It is also able to consume standard context variables, e.g. assuming a
    199 ``user_stylesheet`` variable is passed to the template:
    200 
    201 .. code-block:: html+django
    202 
    203     {% load staticfiles %}
    204     <link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" />
    205 
    206 .. note::
    207 
    208     There is also a template tag named :ttag:`static` in Django's core set
    209     of :ref:`built in template tags<ref-templates-builtins-tags>` which has
    210     the same argument signature but only uses `urlparse.urljoin()`_ with the
    211     :setting:`STATIC_URL` setting and the given path. This has the
    212     disadvantage of not being able to easily switch the storage backend
    213     without changing the templates, so in doubt use the ``staticfiles``
    214     :ttag:`static<staticfiles-static>`
    215     template tag.
    216 
    217 .. _`urlparse.urljoin()`: http://docs.python.org/library/urlparse.html#urlparse.urljoin
    218 
    219 .. _staticfiles-development:
    220 
    221 Serving static files in development
    222 ===================================
    223 
    224 The static files tools are mostly designed to help with getting static files
    225 successfully deployed into production. This usually means a separate,
    226 dedicated static file server, which is a lot of overhead to mess with when
    227 developing locally. Thus, the ``staticfiles`` app ships with a
    228 **quick and dirty helper view** that you can use to serve files locally in
    229 development.
    230 
    231 This view is automatically enabled and will serve your static files at
    232 :setting:`STATIC_URL` when you use the built-in
    233 :ref:`runserver<staticfiles-runserver>` management command.
    234 
    235 To enable this view if you are using some other server for local development,
    236 you'll add a couple of lines to your URLconf. The first line goes at the top
    237 of the file, and the last line at the bottom::
    238 
    239     from django.contrib.staticfiles.urls import staticfiles_urlpatterns
    240 
    241     # ... the rest of your URLconf goes here ...
    242 
    243     urlpatterns += staticfiles_urlpatterns()
    244 
    245 This will inspect your :setting:`STATIC_URL` setting and wire up the view
    246 to serve static files accordingly. Don't forget to set the
    247 :setting:`STATICFILES_DIRS` setting appropriately to let
    248 ``django.contrib.staticfiles`` know where to look for files additionally to
    249 files in app directories.
    250 
    251 .. warning::
    252 
    253     This will only work if :setting:`DEBUG` is ``True``.
    254 
    255     That's because this view is **grossly inefficient** and probably
    256     **insecure**. This is only intended for local development, and should
    257     **never be used in production**.
    258 
    259     Additionally, when using ``staticfiles_urlpatterns`` your
    260     :setting:`STATIC_URL` setting can't be empty or a full URL, such as
    261     ``http://static.example.com/``.
    262 
    263 For a few more details on how the ``staticfiles`` can be used during
    264 development, see :ref:`staticfiles-development-view`.
    265 
    266 .. _staticfiles-other-directories:
    267 
    268 Serving other directories
    269 -------------------------
    270 
    271 .. currentmodule:: django.views.static
    272 .. function:: serve(request, path, document_root, show_indexes=False)
    273 
    274 There may be files other than your project's static assets that, for
    275 convenience, you'd like to have Django serve for you in local development.
    276 The :func:`~django.views.static.serve` view can be used to serve any directory
    277 you give it. (Again, this view is **not** hardened for production
    278 use, and should be used only as a development aid; you should serve these files
    279 in production using a real front-end webserver).
    280 
    281 The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`.
    282 ``staticfiles`` is intended for static assets and has no built-in handling
    283 for user-uploaded files, but you can have Django serve your
    284 :setting:`MEDIA_ROOT` by appending something like this to your URLconf::
    285 
    286     from django.conf import settings
    287 
    288     # ... the rest of your URLconf goes here ...
    289 
    290     if settings.DEBUG:
    291         urlpatterns += patterns('',
    292             url(r'^media/(?P<path>.*)$', 'django.views.static.serve', {
    293                 'document_root': settings.MEDIA_ROOT,
    294             }),
    295        )
    296 
    297 Note, the snippet assumes your :setting:`MEDIA_URL` has a value of
    298 ``'/media/'``. This will call the :func:`~django.views.static.serve` view,
    299 passing in the path from the URLconf and the (required) ``document_root``
    300 parameter.
    301 
    302 .. currentmodule:: django.conf.urls.static
    303 .. function:: static(prefix, view='django.views.static.serve', **kwargs)
    304 
    305 Since it can become a bit cumbersome to define this URL pattern, Django
    306 ships with a small URL helper function
    307 :func:`~django.conf.urls.static.static` that takes as parameters the prefix
    308 such as :setting:`MEDIA_URL` and a dotted path to a view, such as
    309 ``'django.views.static.serve'``. Any other function parameter will be
    310 transparently passed to the view.
    311 
    312 An example for serving :setting:`MEDIA_URL` (``'/media/'``) during
    313 development::
    314 
    315     from django.conf import settings
    316     from django.conf.urls.static import static
    317 
    318     urlpatterns = patterns('',
    319         # ... the rest of your URLconf goes here ...
    320     ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
    321 
    322 .. note::
    323 
    324     This helper function will only be operational in debug mode and if
    325     the given prefix is local (e.g. ``/static/``) and not a URL (e.g.
    326     ``http://static.example.com/``).
    327 
    328 .. _staticfiles-production:
    329 
    330 Serving static files in production
    331 ==================================
    332 
    333 The basic outline of putting static files into production is simple: run the
    334 :djadmin:`collectstatic` command when static files change, then arrange for
    335 the collected static files directory (:setting:`STATIC_ROOT`) to be moved to
    336 the static file server and served.
    337 
    338 Of course, as with all deployment tasks, the devil's in the details. Every
    339 production setup will be a bit different, so you'll need to adapt the basic
    340 outline to fit your needs. Below are a few common patterns that might help.
    341 
    342 Serving the app and your static files from the same server
    343 ----------------------------------------------------------
    344 
    345 If you want to serve your static files from the same server that's already
    346 serving your site, the basic outline gets modified to look something like:
    347 
    348 * Push your code up to the deployment server.
    349 * On the server, run :djadmin:`collectstatic` to copy all the static files
    350   into :setting:`STATIC_ROOT`.
    351 * Point your web server at :setting:`STATIC_ROOT`. For example, here's
    352   :ref:`how to do this under Apache and mod_wsgi <serving-files>`.
    353 
    354 You'll probably want to automate this process, especially if you've got
    355 multiple web servers. There's any number of ways to do this automation, but
    356 one option that many Django developers enjoy is `Fabric`__.
    357 
    358 __ http://fabfile.org/
    359 
    360 Below, and in the following sections, we'll show off a few example fabfiles
    361 (i.e. Fabric scripts) that automate these file deployment options. The syntax
    362 of a fabfile is fairly straightforward but won't be covered here; consult
    363 `Fabric's documentation`__, for a complete explanation of the syntax..
    364 
    365 __ http://docs.fabfile.org/
    366 
    367 So, a fabfile to deploy static files to a couple of web servers might look
    368 something like::
    369 
    370     from fabric.api import *
    371 
    372     # Hosts to deploy onto
    373     env.hosts = ['www1.example.com', 'www2.example.com']
    374 
    375     # Where your project code lives on the server
    376     env.project_root = '/home/www/myproject'
    377 
    378     def deploy_static():
    379         with cd(env.project_root):
    380             run('./manage.py collectstatic -v0 --noinput')
    381 
    382 Serving static files from a dedicated server
    383 --------------------------------------------
    384 
    385 Most larger Django apps use a separate Web server -- i.e., one that's not also
    386 running Django -- for serving static files. This server often runs a different
    387 type of web server -- faster but less full-featured. Some good choices are:
    388 
    389 * lighttpd_
    390 * Nginx_
    391 * TUX_
    392 * Cherokee_
    393 * A stripped-down version of Apache_
    394 
    395 .. _lighttpd: http://www.lighttpd.net/
    396 .. _Nginx: http://wiki.nginx.org/Main
    397 .. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
    398 .. _Apache: http://httpd.apache.org/
    399 .. _Cherokee: http://www.cherokee-project.com/
    400 
    401 Configuring these servers is out of scope of this document; check each
    402 server's respective documentation for instructions.
    403 
    404 Since your static file server won't be running Django, you'll need to modify
    405 the deployment strategy to look something like:
    406 
    407 * When your static files change, run :djadmin:`collectstatic` locally.
    408 * Push your local :setting:`STATIC_ROOT` up to the static file server
    409   into the directory that's being served. ``rsync`` is a good
    410   choice for this step since it only needs to transfer the
    411   bits of static files that have changed.
    412 
    413 Here's how this might look in a fabfile::
    414 
    415     from fabric.api import *
    416     from fabric.contrib import project
    417 
    418     # Where the static files get collected locally
    419     env.local_static_root = '/tmp/static'
    420 
    421     # Where the static files should go remotely
    422     env.remote_static_root = '/home/www/static.example.com'
    423 
    424     @roles('static')
    425     def deploy_static():
    426         local('./manage.py collectstatic')
    427         project.rysnc_project(
    428             remote_dir = env.remote_static_root,
    429             local_dir = env.local_static_root,
    430             delete = True
    431         )
    432 
    433 .. _staticfiles-from-cdn:
    434 
    435 Serving static files from a cloud service or CDN
    436 ------------------------------------------------
    437 
    438 Another common tactic is to serve static files from a cloud storage provider
    439 like Amazon's S3__ and/or a CDN (content delivery network). This lets you
    440 ignore the problems of serving static files, and can often make for
    441 faster-loading webpages (especially when using a CDN).
    442 
    443 When using these services, the basic workflow would look a bit like the above,
    444 except that instead of using ``rsync`` to transfer your static files to the
    445 server you'd need to transfer the static files to the storage provider or CDN.
    446 
    447 There's any number of ways you might do this, but if the provider has an API a
    448 :doc:`custom file storage backend </howto/custom-file-storage>` will make the
    449 process incredibly simple. If you've written or are using a 3rd party custom
    450 storage backend, you can tell :djadmin:`collectstatic` to use it by setting
    451 :setting:`STATICFILES_STORAGE` to the storage engine.
    452 
    453 For example, if you've written an S3 storage backend in
    454 ``myproject.storage.S3Storage`` you could use it with::
    455 
    456     STATICFILES_STORAGE = 'myproject.storage.S3Storage'
    457 
    458 Once that's done, all you have to do is run :djadmin:`collectstatic` and your
    459 static files would be pushed through your storage package up to S3. If you
    460 later needed to switch to a different storage provider, it could be as simple
    461 as changing your :setting:`STATICFILES_STORAGE` setting.
    462 
    463 For details on how you'd write one of these backends,
    464 :doc:`/howto/custom-file-storage`.
    465 
    466 .. seealso::
    467 
    468     The `django-storages`__ project is a 3rd party app that provides many
    469     storage backends for many common file storage APIs (including `S3`__).
    470 
    471 __ http://s3.amazonaws.com/
    472 __ http://code.larlet.fr/django-storages/
    473 __ http://django-storages.readthedocs.org/en/latest/backends/amazon-S3.html
    474 
    475 Upgrading from ``django-staticfiles``
    476 =====================================
    477 
    478 ``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If
    479 you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to
    480 ``django.contrib.staticfiles``, you'll need to make a few changes:
    481 
    482 * Application files should now live in a ``static`` directory in each app
    483   (`django-staticfiles`_ used the name ``media``, which was slightly
    484   confusing).
    485 
    486 * The management commands ``build_static`` and ``resolve_static`` are now
    487   called :djadmin:`collectstatic` and :djadmin:`findstatic`.
    488 
    489 * The settings ``STATICFILES_PREPEND_LABEL_APPS``,
    490   ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were
    491   removed.
    492 
    493 * The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the
    494   new :setting:`STATICFILES_FINDERS`.
    495 
    496 * The default for :setting:`STATICFILES_STORAGE` was renamed from
    497   ``staticfiles.storage.StaticFileStorage`` to
    498   ``staticfiles.storage.StaticFilesStorage``
    499 
    500 * If using :ref:`runserver<staticfiles-runserver>` for local development
    501   (and the :setting:`DEBUG` setting is ``True``), you no longer need to add
    502   anything to your URLconf for serving static files in development.
    503 
    504 Learn more
    505 ==========
    506 
    507 This document has covered the basics and some common usage patterns. For
    508 complete details on all the settings, commands, template tags, and other pieces
    509 include in ``django.contrib.staticfiles``, see :doc:`the staticfiles reference
    510 </ref/contrib/staticfiles>`.

  • docs/index.txt 

    diff --git a/docs/index.txt b/docs/index.txt
index a5d2e13..11ddc41 100644
    a b The view layer  
    102102  :doc:`Overview <topics/http/file-uploads>` |
    103103  :doc:`File objects <ref/files/file>` |
    104104  :doc:`Storage API <ref/files/storage>` |
    105   :doc:`Managing files <topics/files>` |
     105  :doc:`Managing media files <topics/files/media` |
    106106  :doc:`Custom storage <howto/custom-file-storage>`
    107107
    108108* **Generic views:**
    … … The development process  
    158158  :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` |
    159159  :doc:`Apache/mod_python (deprecated) <howto/deployment/modpython>` |
    160160  :doc:`Apache authentication <howto/apache-auth>` |
    161   :doc:`Handling static files <howto/static-files>` |
     161  :doc:`Managing static files <topics/files/static>` |
    162162  :doc:`Tracking code errors by email <howto/error-reporting>`
    163163
    164164Other batteries included

  • docs/misc/api-stability.txt 

    diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt
index 75fa6b4..08e9496 100644
    a b of 1.0. This includes these APIs:  
    4747
    4848- :doc:`Sending email </topics/email>`.
    4949
    50 - :doc:`File handling and storage </topics/files>`
     50- :doc:`Managing media files </topics/files/media`
    5151
    5252- :doc:`Forms </topics/forms/index>`
    5353

  • docs/ref/contrib/staticfiles.txt 

    diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
index 1dbd00b..119b559 100644
    a b can easily be served in production.  
    1414.. seealso::
    1515
    1616    For an introduction to the static files app and some usage examples, see
    17     :doc:`/howto/static-files`.
     17    :doc:`/topics/files/static`.
    1818
    1919.. _staticfiles-settings:
    2020

  • docs/ref/django-admin.txt 

    diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 5ea7280..deaa0eb 100644
    a b Serving static files with the development server  
    766766
    767767By default, the development server doesn't serve any static files for your site
    768768(such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
    769 you want to configure Django to serve static media, read :doc:`/howto/static-files`.
     769you want to configure Django to serve static media, read :doc:`/topics/files/static`.
    770770
    771771shell
    772772-----
    … … collectstatic  
    12681268~~~~~~~~~~~~~
    12691269
    12701270This command is only available if the :doc:`static files application
    1271 </howto/static-files>` (``django.contrib.staticfiles``) is installed.
     1271</topics/files/static>` (``django.contrib.staticfiles``) is installed.
    12721272
    12731273Please refer to its :djadmin:`description <collectstatic>` in the
    12741274:doc:`staticfiles </ref/contrib/staticfiles>` documentation.
    … … findstatic  
    12771277~~~~~~~~~~
    12781278
    12791279This command is only available if the :doc:`static files application
    1280 </howto/static-files>` (``django.contrib.staticfiles``) is installed.
     1280</topics/files/static>` (``django.contrib.staticfiles``) is installed.
    12811281
    12821282Please refer to its :djadmin:`description <findstatic>` in the :doc:`staticfiles
    12831283</ref/contrib/staticfiles>` documentation.

  • docs/ref/models/fields.txt 

    diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 36bf60e..fe4f60d 100644
    a b Also has one optional argument:  
    533533.. attribute:: FileField.storage
    534534
    535535    Optional. A storage object, which handles the storage and retrieval of your
    536     files. See :doc:`/topics/files` for details on how to provide this object.
     536    files. See :doc:`/topics/files/media for details on how to provide this object.
    537537
    538538The admin represents this field as an ``<input type="file">`` (a file-upload
    539539widget).
    … … If you wanted to retrieve the uploaded file's on-disk filename, or the file's  
    569569size, you could use the :attr:`~django.core.files.File.name` and
    570570:attr:`~django.core.files.File.size` attributes respectively; for more
    571571information on the available attributes and methods, see the
    572 :class:`~django.core.files.File` class reference and the :doc:`/topics/files`
     572:class:`~django.core.files.File` class reference and the :doc:`/topics/files/media
    573573topic guide.
    574574
    575575.. note::
    … … Or you can construct one from a Python string like this::  
    645645    from django.core.files.base import ContentFile
    646646    myfile = ContentFile("hello world")
    647647
    648 For more information, see :doc:`/topics/files`.
     648For more information, see :doc:`/topics/files/media.
    649649
    650650.. method:: FieldFile.delete(save=True)
    651651

  • docs/ref/request-response.txt 

    diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt
index c0ae73e..99a3e63 100644
    a b All attributes except ``session`` should be considered read-only.  
    128128    ``FILES`` is the ``name`` from the ``<input type="file" name="" />``. Each
    129129    value in ``FILES`` is an :class:`UploadedFile` as described below.
    130130
    131     See :doc:`/topics/files` for more information.
     131    See :doc:`/topics/files/media for more information.
    132132
    133133    Note that ``FILES`` will only contain data if the request method was POST
    134134    and the ``<form>`` that posted to the request had

  • docs/ref/settings.txt 

    diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index c06ef1a..ecc8c83 100644
    a b DEFAULT_FILE_STORAGE  
    877877Default: :class:`django.core.files.storage.FileSystemStorage`
    878878
    879879Default file storage class to be used for any file-related operations that don't
    880 specify a particular storage system. See :doc:`/topics/files`.
     880specify a particular storage system. See :doc:`/topics/files/media.
    881881
    882882.. setting:: DEFAULT_FROM_EMAIL
    883883
    … … Default::  
    10301030    ("django.core.files.uploadhandler.MemoryFileUploadHandler",
    10311031     "django.core.files.uploadhandler.TemporaryFileUploadHandler",)
    10321032
    1033 A tuple of handlers to use for uploading. See :doc:`/topics/files` for details.
     1033A tuple of handlers to use for uploading. See :doc:`/topics/files/media for details.
    10341034
    10351035.. setting:: FILE_UPLOAD_MAX_MEMORY_SIZE
    10361036
    … … FILE_UPLOAD_MAX_MEMORY_SIZE  
    10401040Default: ``2621440`` (i.e. 2.5 MB).
    10411041
    10421042The maximum size (in bytes) that an upload will be before it gets streamed to
    1043 the file system. See :doc:`/topics/files` for details.
     1043the file system. See :doc:`/topics/files/media for details.
    10441044
    10451045.. setting:: FILE_UPLOAD_PERMISSIONS
    10461046
    … … The directory to store data temporarily while uploading files. If ``None``,  
    10791079Django will use the standard temporary directory for the operating system. For
    10801080example, this will default to '/tmp' on \*nix-style operating systems.
    10811081
    1082 See :doc:`/topics/files` for details.
     1082See :doc:`/topics/files/media for details.
    10831083
    10841084.. setting:: FIRST_DAY_OF_WEEK
    10851085
    … … MEDIA_ROOT  
    14021402Default: ``''`` (Empty string)
    14031403
    14041404Absolute path to the directory that holds media for this installation, used
    1405 for :doc:`managing stored files </topics/files>`.
     1405for :doc:`managing media files </topics/files/media`.
    14061406
    14071407Example: ``"/home/media/media.lawrence.com/"``
    14081408
    … … MEDIA_URL  
    14161416Default: ``''`` (Empty string)
    14171417
    14181418URL that handles the media served from :setting:`MEDIA_ROOT`, used
    1419 for :doc:`managing stored files </topics/files>`.
     1419for :doc:`managing media files </topics/files/media`.
    14201420
    14211421Example: ``"http://media.lawrence.com/"``
    14221422
    … … Example: ``"/home/example.com/static/"``  
    18861886If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
    18871887(default) the :djadmin:`collectstatic` management command will collect static
    18881888files into this directory. See the howto on :doc:`managing static
    1889 files</howto/static-files>` for more details about usage.
     1889files</topics/files/static>` for more details about usage.
    18901890
    18911891.. warning::
    18921892

  • docs/releases/1.0-alpha-2.txt 

    diff --git a/docs/releases/1.0-alpha-2.txt b/docs/releases/1.0-alpha-2.txt
index a26a214..85483d0 100644
    a b Pluggable file storage  
    3636    Django's built-in ``FileField`` and ``ImageField`` now can take advantage of
    3737    pluggable file-storage backends, allowing extensive customization of where
    3838    and how uploaded files get stored by Django. For details, see :doc:`the
    39     files documentation </topics/files>`; big thanks go to Marty Alchin for
     39    files documentation </topics/files/media`; big thanks go to Marty Alchin for
    4040    putting in the hard work to get this completed.
    4141
    4242Jython compatibility

  • docs/releases/1.0.txt 

    diff --git a/docs/releases/1.0.txt b/docs/releases/1.0.txt
index e752b02..8678f2a 100644
    a b Pluggable file storage  
    141141Django's built-in ``FileField`` and ``ImageField`` now can take advantage of
    142142pluggable file-storage backends, allowing extensive customization of where and
    143143how uploaded files get stored by Django. For details, see :doc:`the files
    144 documentation </topics/files>`; big thanks go to Marty Alchin for putting in the
     144documentation </topics/files/media`; big thanks go to Marty Alchin for putting in the
    145145hard work to get this completed.
    146146
    147147Jython compatibility

  • docs/releases/1.3-alpha-1.txt 

    diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt
index f1ff23b..983bcbb 100644
    a b arrange for serving of files in :setting:`MEDIA_ROOT` yourself;  
    7373
    7474See the :doc:`reference documentation of the app </ref/contrib/staticfiles>`
    7575for more details or learn how to :doc:`manage static files
    76 </howto/static-files>`.
     76</topics/files/static>`.
    7777
    7878``unittest2`` support
    7979~~~~~~~~~~~~~~~~~~~~~

  • docs/releases/1.3-beta-1.txt 

    diff --git a/docs/releases/1.3-beta-1.txt b/docs/releases/1.3-beta-1.txt
index 02c038f..f5fd101 100644
    a b Based on feedback from the community this release adds two new options to the  
    3737
    3838See the :doc:`staticfiles reference documentation </ref/contrib/staticfiles>`
    3939for more details, or learn :doc:`how to manage static files
    40 </howto/static-files>`.
     40</topics/files/static>`.
    4141
    4242Translation comments
    4343~~~~~~~~~~~~~~~~~~~~

  • docs/releases/1.3.txt 

    diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt
index 224cd47..3bdbc49 100644
    a b at :setting:`STATIC_URL`.  
    115115
    116116See the :doc:`reference documentation of the app </ref/contrib/staticfiles>`
    117117for more details or learn how to :doc:`manage static files
    118 </howto/static-files>`.
     118</topics/files/static>`.
    119119
    120120unittest2 support
    121121~~~~~~~~~~~~~~~~~

  • docs/releases/1.4-alpha-1.txt 

    diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt
index b5ec782..09aa4a1 100644
    a b If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g.  
    578578``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT`
    579579are configured and your web server serves the files correctly. The development
    580580server continues to serve the admin files just like before. Don't hesitate to
    581 consult the :doc:`static files howto </howto/static-files>` for further
     581consult the :doc:`static files topic </topics/files/static>` for further
    582582details.
    583583
    584584In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.

  • docs/releases/1.4-beta-1.txt 

    diff --git a/docs/releases/1.4-beta-1.txt b/docs/releases/1.4-beta-1.txt
index 88f32ea..8213425 100644
    a b If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g.  
    646646``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT`
    647647are configured and your web server serves the files correctly. The development
    648648server continues to serve the admin files just like before. Don't hesitate to
    649 consult the :doc:`static files howto </howto/static-files>` for further
     649consult the :doc:`static files topic </topics/files/static>` for further
    650650details.
    651651
    652652In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.

  • docs/releases/1.4.txt 

    diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index 51766dc..b999fcc 100644
    a b If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g.  
    708708``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT`
    709709are configured and your Web server serves those files correctly. The
    710710development server continues to serve the admin files just like before. Read
    711 the :doc:`static files howto </howto/static-files>` for more details.
     711the :doc:`static files topic </topics/files/static>` for more details.
    712712
    713713If your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.
    714714``http://media.example.com/admin/``), make sure to also set your

  • deleted file docs/topics/files.txt 

    diff --git a/docs/topics/files.txt b/docs/topics/files.txt
deleted file mode 100644
index 9ab8d5c..0000000
    + -  
    1 ==============
    2 Managing files
    3 ==============
    4 
    5 This document describes Django's file access APIs.
    6 
    7 By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and
    8 :setting:`MEDIA_URL` settings. The examples below assume that you're using these
    9 defaults.
    10 
    11 However, Django provides ways to write custom `file storage systems`_ that
    12 allow you to completely customize where and how Django stores files. The
    13 second half of this document describes how these storage systems work.
    14 
    15 .. _file storage systems: `File storage`_
    16 
    17 Using files in models
    18 =====================
    19 
    20 When you use a :class:`~django.db.models.FileField` or
    21 :class:`~django.db.models.ImageField`, Django provides a set of APIs you can use
    22 to deal with that file.
    23 
    24 Consider the following model, using an :class:`~django.db.models.ImageField` to
    25 store a photo::
    26 
    27     class Car(models.Model):
    28         name = models.CharField(max_length=255)
    29         price = models.DecimalField(max_digits=5, decimal_places=2)
    30         photo = models.ImageField(upload_to='cars')
    31 
    32 Any ``Car`` instance will have a ``photo`` attribute that you can use to get at
    33 the details of the attached photo::
    34 
    35     >>> car = Car.objects.get(name="57 Chevy")
    36     >>> car.photo
    37     <ImageFieldFile: chevy.jpg>
    38     >>> car.photo.name
    39     u'cars/chevy.jpg'
    40     >>> car.photo.path
    41     u'/media/cars/chevy.jpg'
    42     >>> car.photo.url
    43     u'http://media.example.com/cars/chevy.jpg'
    44 
    45 This object -- ``car.photo`` in the example -- is a ``File`` object, which means
    46 it has all the methods and attributes described below.
    47 
    48 .. note::
    49     The file is saved as part of saving the model in the database, so the actual
    50     file name used on disk cannot be relied on until after the model has been
    51     saved.
    52 
    53 
    54 The ``File`` object
    55 ===================
    56 
    57 Internally, Django uses a :class:`django.core.files.File` instance any time it
    58 needs to represent a file. This object is a thin wrapper around Python's
    59 `built-in file object`_ with some Django-specific additions.
    60 
    61 .. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects
    62 
    63 Most of the time you'll simply use a ``File`` that Django's given you (i.e. a
    64 file attached to a model as above, or perhaps an uploaded file).
    65 
    66 If you need to construct a ``File`` yourself, the easiest way is to create one
    67 using a Python built-in ``file`` object::
    68 
    69     >>> from django.core.files import File
    70 
    71     # Create a Python file object using open()
    72     >>> f = open('/tmp/hello.world', 'w')
    73     >>> myfile = File(f)
    74 
    75 Now you can use any of the documented attributes and methods
    76 of the :class:`~django.core.files.File` class.
    77 
    78 File storage
    79 ============
    80 
    81 Behind the scenes, Django delegates decisions about how and where to store files
    82 to a file storage system. This is the object that actually understands things
    83 like file systems, opening and reading files, etc.
    84 
    85 Django's default file storage is given by the :setting:`DEFAULT_FILE_STORAGE`
    86 setting; if you don't explicitly provide a storage system, this is the one that
    87 will be used.
    88 
    89 See below for details of the built-in default file storage system, and see
    90 :doc:`/howto/custom-file-storage` for information on writing your own file
    91 storage system.
    92 
    93 Storage objects
    94 ---------------
    95 
    96 Though most of the time you'll want to use a ``File`` object (which delegates to
    97 the proper storage for that file), you can use file storage systems directly.
    98 You can create an instance of some custom file storage class, or -- often more
    99 useful -- you can use the global default storage system::
    100 
    101     >>> from django.core.files.storage import default_storage
    102     >>> from django.core.files.base import ContentFile
    103 
    104     >>> path = default_storage.save('/path/to/file', ContentFile('new content'))
    105     >>> path
    106     u'/path/to/file'
    107 
    108     >>> default_storage.size(path)
    109     11
    110     >>> default_storage.open(path).read()
    111     'new content'
    112 
    113     >>> default_storage.delete(path)
    114     >>> default_storage.exists(path)
    115     False
    116 
    117 See :doc:`/ref/files/storage` for the file storage API.
    118 
    119 The built-in filesystem storage class
    120 -------------------------------------
    121 
    122 Django ships with a built-in ``FileSystemStorage`` class (defined in
    123 ``django.core.files.storage``) which implements basic local filesystem file
    124 storage. Its initializer takes two arguments:
    125 
    126 ======================  ===================================================
    127 Argument                Description
    128 ======================  ===================================================
    129 ``location``            Optional. Absolute path to the directory that will
    130                         hold the files. If omitted, it will be set to the
    131                         value of your :setting:`MEDIA_ROOT` setting.
    132 ``base_url``            Optional. URL that serves the files stored at this
    133                         location. If omitted, it will default to the value
    134                         of your :setting:`MEDIA_URL` setting.
    135 ======================  ===================================================
    136 
    137 For example, the following code will store uploaded files under
    138 ``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::
    139 
    140     from django.db import models
    141     from django.core.files.storage import FileSystemStorage
    142 
    143     fs = FileSystemStorage(location='/media/photos')
    144 
    145     class Car(models.Model):
    146         ...
    147         photo = models.ImageField(storage=fs)
    148 
    149 :doc:`Custom storage systems </howto/custom-file-storage>` work the same way:
    150 you can pass them in as the ``storage`` argument to a
    151 :class:`~django.db.models.FileField`.

  • new file docs/topics/files/media.txt 

    diff --git a/docs/topics/files/media.txt b/docs/topics/files/media.txt
new file mode 100644
index 0000000..ec82fab
    - +  
     1====================
     2Managing media files
     3====================
     4
     5This document describes Django's file access APIs for media files.
     6Il you want to handle static files (JS, CSS, etc), see
     7:doc:`/topics/files/static`
     8
     9By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and
     10:setting:`MEDIA_URL` settings. The examples below assume that you're using these
     11defaults.
     12
     13However, Django provides ways to write custom `file storage systems`_ that
     14allow you to completely customize where and how Django stores files. The
     15second half of this document describes how these storage systems work.
     16
     17.. _file storage systems: `File storage`_
     18
     19Using files in models
     20=====================
     21
     22When you use a :class:`~django.db.models.FileField` or
     23:class:`~django.db.models.ImageField`, Django provides a set of APIs you can use
     24to deal with that file.
     25
     26Consider the following model, using an :class:`~django.db.models.ImageField` to
     27store a photo::
     28
     29    class Car(models.Model):
     30        name = models.CharField(max_length=255)
     31        price = models.DecimalField(max_digits=5, decimal_places=2)
     32        photo = models.ImageField(upload_to='cars')
     33
     34Any ``Car`` instance will have a ``photo`` attribute that you can use to get at
     35the details of the attached photo::
     36
     37    >>> car = Car.objects.get(name="57 Chevy")
     38    >>> car.photo
     39    <ImageFieldFile: chevy.jpg>
     40    >>> car.photo.name
     41    u'cars/chevy.jpg'
     42    >>> car.photo.path
     43    u'/media/cars/chevy.jpg'
     44    >>> car.photo.url
     45    u'http://media.example.com/cars/chevy.jpg'
     46
     47This object -- ``car.photo`` in the example -- is a ``File`` object, which means
     48it has all the methods and attributes described below.
     49
     50.. note::
     51    The file is saved as part of saving the model in the database, so the actual
     52    file name used on disk cannot be relied on until after the model has been
     53    saved.
     54
     55
     56The ``File`` object
     57===================
     58
     59Internally, Django uses a :class:`django.core.files.File` instance any time it
     60needs to represent a file. This object is a thin wrapper around Python's
     61`built-in file object`_ with some Django-specific additions.
     62
     63.. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects
     64
     65Most of the time you'll simply use a ``File`` that Django's given you (i.e. a
     66file attached to a model as above, or perhaps an uploaded file).
     67
     68If you need to construct a ``File`` yourself, the easiest way is to create one
     69using a Python built-in ``file`` object::
     70
     71    >>> from django.core.files import File
     72
     73    # Create a Python file object using open()
     74    >>> f = open('/tmp/hello.world', 'w')
     75    >>> myfile = File(f)
     76
     77Now you can use any of the documented attributes and methods
     78of the :class:`~django.core.files.File` class.
     79
     80File storage
     81============
     82
     83Behind the scenes, Django delegates decisions about how and where to store files
     84to a file storage system. This is the object that actually understands things
     85like file systems, opening and reading files, etc.
     86
     87Django's default file storage is given by the :setting:`DEFAULT_FILE_STORAGE`
     88setting; if you don't explicitly provide a storage system, this is the one that
     89will be used.
     90
     91See below for details of the built-in default file storage system, and see
     92:doc:`/howto/custom-file-storage` for information on writing your own file
     93storage system.
     94
     95Storage objects
     96---------------
     97
     98Though most of the time you'll want to use a ``File`` object (which delegates to
     99the proper storage for that file), you can use file storage systems directly.
     100You can create an instance of some custom file storage class, or -- often more
     101useful -- you can use the global default storage system::
     102
     103    >>> from django.core.files.storage import default_storage
     104    >>> from django.core.files.base import ContentFile
     105
     106    >>> path = default_storage.save('/path/to/file', ContentFile('new content'))
     107    >>> path
     108    u'/path/to/file'
     109
     110    >>> default_storage.size(path)
     111    11
     112    >>> default_storage.open(path).read()
     113    'new content'
     114
     115    >>> default_storage.delete(path)
     116    >>> default_storage.exists(path)
     117    False
     118
     119See :doc:`/ref/files/storage` for the file storage API.
     120
     121The built-in filesystem storage class
     122-------------------------------------
     123
     124Django ships with a built-in ``FileSystemStorage`` class (defined in
     125``django.core.files.storage``) which implements basic local filesystem file
     126storage. Its initializer takes two arguments:
     127
     128======================  ===================================================
     129Argument                Description
     130======================  ===================================================
     131``location``            Optional. Absolute path to the directory that will
     132                        hold the files. If omitted, it will be set to the
     133                        value of your :setting:`MEDIA_ROOT` setting.
     134``base_url``            Optional. URL that serves the files stored at this
     135                        location. If omitted, it will default to the value
     136                        of your :setting:`MEDIA_URL` setting.
     137======================  ===================================================
     138
     139For example, the following code will store uploaded files under
     140``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::
     141
     142    from django.db import models
     143    from django.core.files.storage import FileSystemStorage
     144
     145    fs = FileSystemStorage(location='/media/photos')
     146
     147    class Car(models.Model):
     148        ...
     149        photo = models.ImageField(storage=fs)
     150
     151:doc:`Custom storage systems </howto/custom-file-storage>` work the same way:
     152you can pass them in as the ``storage`` argument to a
     153:class:`~django.db.models.FileField`.

  • new file docs/topics/files/static.txt 

    diff --git a/docs/topics/files/static.txt b/docs/topics/files/static.txt
new file mode 100644
index 0000000..e3a40a1
    - +  
     1=====================
     2Managing static files
     3=====================
     4
     5.. versionadded:: 1.3
     6
     7Django developers mostly concern themselves with the dynamic parts of web
     8applications -- the views and templates that render anew for each request. But
     9web applications have other parts: the static files (images, CSS,
     10Javascript, etc.) that are needed to render a complete web page.
     11
     12For small projects, this isn't a big deal, because you can just keep the
     13static files somewhere your web server can find it. However, in bigger
     14projects -- especially those comprised of multiple apps -- dealing with the
     15multiple sets of static files provided by each application starts to get
     16tricky.
     17
     18That's what ``django.contrib.staticfiles`` is for: it collects static files
     19from each of your applications (and any other places you specify) into a
     20single location that can easily be served in production.
     21
     22.. note::
     23
     24    If you've used the `django-staticfiles`_ third-party app before, then
     25    ``django.contrib.staticfiles`` will look very familiar. That's because
     26    they're essentially the same code: ``django.contrib.staticfiles`` started
     27    its life as `django-staticfiles`_ and was merged into Django 1.3.
     28
     29    If you're upgrading from ``django-staticfiles``, please see `Upgrading from
     30    django-staticfiles`_, below, for a few minor changes you'll need to make.
     31
     32.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
     33
     34Using ``django.contrib.staticfiles``
     35====================================
     36
     37Basic usage
     38-----------
     39
     401. Put your static files somewhere that ``staticfiles`` will find them.
     41
     42   By default, this means within ``static/`` subdirectories of apps in your
     43   :setting:`INSTALLED_APPS`.
     44
     45   Your project will probably also have static assets that aren't tied to a
     46   particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of
     47   filesystem directories to check when loading static files. It's a search
     48   path that is by default empty. See the :setting:`STATICFILES_DIRS` docs
     49   how to extend this list of additional paths.
     50
     51   Additionally, see the documentation for the :setting:`STATICFILES_FINDERS`
     52   setting for details on how ``staticfiles`` finds your files.
     53
     542. Make sure that ``django.contrib.staticfiles`` is included in your
     55   :setting:`INSTALLED_APPS`.
     56
     57   For :ref:`local development<staticfiles-development>`, if you are using
     58   :ref:`runserver<staticfiles-runserver>` or adding
     59   :ref:`staticfiles_urlpatterns<staticfiles-development>` to your
     60   URLconf, you're done with the setup -- your static files will
     61   automatically be served at the default (for
     62   :djadmin:`newly created<startproject>` projects) :setting:`STATIC_URL`
     63   of ``/static/``.
     64
     653. You'll probably need to refer to these files in your templates. The
     66   easiest method is to use the included context processor which allows
     67   template code like:
     68
     69   .. code-block:: html+django
     70
     71       <img src="{{ STATIC_URL }}images/hi.jpg" />
     72
     73   See :ref:`staticfiles-in-templates` for more details, **including** an
     74   alternate method using a template tag.
     75
     76Deploying static files in a nutshell
     77------------------------------------
     78
     79When you're ready to move out of local development and deploy your project:
     80
     811. Set the :setting:`STATIC_URL` setting to the public URL for your static
     82   files (in most cases, the default value of ``/static/`` is just fine).
     83
     842. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path
     85   you'd like your static files collected to when you use the
     86   :djadmin:`collectstatic` management command. For example::
     87
     88       STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
     89
     903. Run the :djadmin:`collectstatic` management command::
     91
     92       ./manage.py collectstatic
     93
     94   This'll churn through your static file storage and copy them into the
     95   directory given by :setting:`STATIC_ROOT`.
     96
     974. Deploy those files by configuring your webserver of choice to serve the
     98   files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
     99
     100   :ref:`staticfiles-production` covers some common deployment strategies
     101   for static files.
     102
     103Those are the **basics**. For more details on common configuration options,
     104read on; for a detailed reference of the settings, commands, and other bits
     105included with the framework see
     106:doc:`the staticfiles reference </ref/contrib/staticfiles>`.
     107
     108.. note::
     109
     110   In previous versions of Django, it was common to place static assets in
     111   :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both
     112   at :setting:`MEDIA_URL`. Part of the purpose of introducing the
     113   ``staticfiles`` app is to make it easier to keep static files separate
     114   from user-uploaded files.
     115
     116   For this reason, you need to make your :setting:`MEDIA_ROOT` and
     117   :setting:`MEDIA_URL` different from your :setting:`STATIC_ROOT` and
     118   :setting:`STATIC_URL`. You will need to arrange for serving of files in
     119   :setting:`MEDIA_ROOT` yourself; ``staticfiles`` does not deal with
     120   user-uploaded files at all. You can, however, use
     121   :func:`django.views.static.serve` view for serving :setting:`MEDIA_ROOT`
     122   in development; see :ref:`staticfiles-other-directories`.
     123
     124.. _staticfiles-in-templates:
     125
     126Referring to static files in templates
     127======================================
     128
     129At some point, you'll probably need to link to static files in your templates.
     130You could, of course, simply hardcode the path to you assets in the templates:
     131
     132.. code-block:: html
     133
     134    <img src="http://static.example.com/static/myimage.jpg" />
     135
     136Of course, there are some serious problems with this: it doesn't work well in
     137development, and it makes it *very* hard to change where you've deployed your
     138static files. If, for example, you wanted to switch to using a content
     139delivery network (CDN), then you'd need to change more or less every single
     140template.
     141
     142A far better way is to use the value of the :setting:`STATIC_URL` setting
     143directly in your templates. This means that a switch of static files servers
     144only requires changing that single value. Much better!
     145
     146Django includes multiple built-in ways of using this setting in your
     147templates: a context processor and a template tag.
     148
     149With a context processor
     150------------------------
     151
     152The included context processor is the easy way. Simply make sure
     153``'django.core.context_processors.static'`` is in your
     154:setting:`TEMPLATE_CONTEXT_PROCESSORS`. It's there by default, and if you're
     155editing that setting by hand it should look something like::
     156
     157    TEMPLATE_CONTEXT_PROCESSORS = (
     158        'django.core.context_processors.debug',
     159        'django.core.context_processors.i18n',
     160        'django.core.context_processors.media',
     161        'django.core.context_processors.static',
     162        'django.contrib.auth.context_processors.auth',
     163        'django.contrib.messages.context_processors.messages',
     164    )
     165
     166Once that's done, you can refer to :setting:`STATIC_URL` in your templates:
     167
     168.. code-block:: html+django
     169
     170     <img src="{{ STATIC_URL }}images/hi.jpg" />
     171
     172If ``{{ STATIC_URL }}`` isn't working in your template, you're probably not
     173using :class:`~django.template.RequestContext` when rendering the template.
     174
     175As a brief refresher, context processors add variables into the contexts of
     176every template. However, context processors require that you use
     177:class:`~django.template.RequestContext` when rendering templates. This happens
     178automatically if you're using a :doc:`generic view </ref/class-based-views>`,
     179but in views written by hand you'll need to explicitly use ``RequestContext``
     180To see how that works, and to read more details, check out
     181:ref:`subclassing-context-requestcontext`.
     182
     183Another option is the :ttag:`get_static_prefix` template tag that is part of
     184Django's core.
     185
     186With a template tag
     187-------------------
     188
     189The more powerful tool is the :ttag:`static<staticfiles-static>` template
     190tag. It builds the URL for the given relative path by using the configured
     191:setting:`STATICFILES_STORAGE` storage.
     192
     193.. code-block:: html+django
     194
     195    {% load staticfiles %}
     196    <img src="{% static "images/hi.jpg" %}" />
     197
     198It is also able to consume standard context variables, e.g. assuming a
     199``user_stylesheet`` variable is passed to the template:
     200
     201.. code-block:: html+django
     202
     203    {% load staticfiles %}
     204    <link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" />
     205
     206.. note::
     207
     208    There is also a template tag named :ttag:`static` in Django's core set
     209    of :ref:`built in template tags<ref-templates-builtins-tags>` which has
     210    the same argument signature but only uses `urlparse.urljoin()`_ with the
     211    :setting:`STATIC_URL` setting and the given path. This has the
     212    disadvantage of not being able to easily switch the storage backend
     213    without changing the templates, so in doubt use the ``staticfiles``
     214    :ttag:`static<staticfiles-static>`
     215    template tag.
     216
     217.. _`urlparse.urljoin()`: http://docs.python.org/library/urlparse.html#urlparse.urljoin
     218
     219.. _staticfiles-development:
     220
     221Serving static files in development
     222===================================
     223
     224The static files tools are mostly designed to help with getting static files
     225successfully deployed into production. This usually means a separate,
     226dedicated static file server, which is a lot of overhead to mess with when
     227developing locally. Thus, the ``staticfiles`` app ships with a
     228**quick and dirty helper view** that you can use to serve files locally in
     229development.
     230
     231This view is automatically enabled and will serve your static files at
     232:setting:`STATIC_URL` when you use the built-in
     233:ref:`runserver<staticfiles-runserver>` management command.
     234
     235To enable this view if you are using some other server for local development,
     236you'll add a couple of lines to your URLconf. The first line goes at the top
     237of the file, and the last line at the bottom::
     238
     239    from django.contrib.staticfiles.urls import staticfiles_urlpatterns
     240
     241    # ... the rest of your URLconf goes here ...
     242
     243    urlpatterns += staticfiles_urlpatterns()
     244
     245This will inspect your :setting:`STATIC_URL` setting and wire up the view
     246to serve static files accordingly. Don't forget to set the
     247:setting:`STATICFILES_DIRS` setting appropriately to let
     248``django.contrib.staticfiles`` know where to look for files additionally to
     249files in app directories.
     250
     251.. warning::
     252
     253    This will only work if :setting:`DEBUG` is ``True``.
     254
     255    That's because this view is **grossly inefficient** and probably
     256    **insecure**. This is only intended for local development, and should
     257    **never be used in production**.
     258
     259    Additionally, when using ``staticfiles_urlpatterns`` your
     260    :setting:`STATIC_URL` setting can't be empty or a full URL, such as
     261    ``http://static.example.com/``.
     262
     263For a few more details on how the ``staticfiles`` can be used during
     264development, see :ref:`staticfiles-development-view`.
     265
     266.. _staticfiles-other-directories:
     267
     268Serving other directories
     269-------------------------
     270
     271.. currentmodule:: django.views.static
     272.. function:: serve(request, path, document_root, show_indexes=False)
     273
     274There may be files other than your project's static assets that, for
     275convenience, you'd like to have Django serve for you in local development.
     276The :func:`~django.views.static.serve` view can be used to serve any directory
     277you give it. (Again, this view is **not** hardened for production
     278use, and should be used only as a development aid; you should serve these files
     279in production using a real front-end webserver).
     280
     281The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`.
     282``staticfiles`` is intended for static assets and has no built-in handling
     283for user-uploaded files, but you can have Django serve your
     284:setting:`MEDIA_ROOT` by appending something like this to your URLconf::
     285
     286    from django.conf import settings
     287
     288    # ... the rest of your URLconf goes here ...
     289
     290    if settings.DEBUG:
     291        urlpatterns += patterns('',
     292            url(r'^media/(?P<path>.*)$', 'django.views.static.serve', {
     293                'document_root': settings.MEDIA_ROOT,
     294            }),
     295       )
     296
     297Note, the snippet assumes your :setting:`MEDIA_URL` has a value of
     298``'/media/'``. This will call the :func:`~django.views.static.serve` view,
     299passing in the path from the URLconf and the (required) ``document_root``
     300parameter.
     301
     302.. currentmodule:: django.conf.urls.static
     303.. function:: static(prefix, view='django.views.static.serve', **kwargs)
     304
     305Since it can become a bit cumbersome to define this URL pattern, Django
     306ships with a small URL helper function
     307:func:`~django.conf.urls.static.static` that takes as parameters the prefix
     308such as :setting:`MEDIA_URL` and a dotted path to a view, such as
     309``'django.views.static.serve'``. Any other function parameter will be
     310transparently passed to the view.
     311
     312An example for serving :setting:`MEDIA_URL` (``'/media/'``) during
     313development::
     314
     315    from django.conf import settings
     316    from django.conf.urls.static import static
     317
     318    urlpatterns = patterns('',
     319        # ... the rest of your URLconf goes here ...
     320    ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
     321
     322.. note::
     323
     324    This helper function will only be operational in debug mode and if
     325    the given prefix is local (e.g. ``/static/``) and not a URL (e.g.
     326    ``http://static.example.com/``).
     327
     328.. _staticfiles-production:
     329
     330Serving static files in production
     331==================================
     332
     333The basic outline of putting static files into production is simple: run the
     334:djadmin:`collectstatic` command when static files change, then arrange for
     335the collected static files directory (:setting:`STATIC_ROOT`) to be moved to
     336the static file server and served.
     337
     338Of course, as with all deployment tasks, the devil's in the details. Every
     339production setup will be a bit different, so you'll need to adapt the basic
     340outline to fit your needs. Below are a few common patterns that might help.
     341
     342Serving the app and your static files from the same server
     343----------------------------------------------------------
     344
     345If you want to serve your static files from the same server that's already
     346serving your site, the basic outline gets modified to look something like:
     347
     348* Push your code up to the deployment server.
     349* On the server, run :djadmin:`collectstatic` to copy all the static files
     350  into :setting:`STATIC_ROOT`.
     351* Point your web server at :setting:`STATIC_ROOT`. For example, here's
     352  :ref:`how to do this under Apache and mod_wsgi <serving-files>`.
     353
     354You'll probably want to automate this process, especially if you've got
     355multiple web servers. There's any number of ways to do this automation, but
     356one option that many Django developers enjoy is `Fabric`__.
     357
     358__ http://fabfile.org/
     359
     360Below, and in the following sections, we'll show off a few example fabfiles
     361(i.e. Fabric scripts) that automate these file deployment options. The syntax
     362of a fabfile is fairly straightforward but won't be covered here; consult
     363`Fabric's documentation`__, for a complete explanation of the syntax..
     364
     365__ http://docs.fabfile.org/
     366
     367So, a fabfile to deploy static files to a couple of web servers might look
     368something like::
     369
     370    from fabric.api import *
     371
     372    # Hosts to deploy onto
     373    env.hosts = ['www1.example.com', 'www2.example.com']
     374
     375    # Where your project code lives on the server
     376    env.project_root = '/home/www/myproject'
     377
     378    def deploy_static():
     379        with cd(env.project_root):
     380            run('./manage.py collectstatic -v0 --noinput')
     381
     382Serving static files from a dedicated server
     383--------------------------------------------
     384
     385Most larger Django apps use a separate Web server -- i.e., one that's not also
     386running Django -- for serving static files. This server often runs a different
     387type of web server -- faster but less full-featured. Some good choices are:
     388
     389* lighttpd_
     390* Nginx_
     391* TUX_
     392* Cherokee_
     393* A stripped-down version of Apache_
     394
     395.. _lighttpd: http://www.lighttpd.net/
     396.. _Nginx: http://wiki.nginx.org/Main
     397.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
     398.. _Apache: http://httpd.apache.org/
     399.. _Cherokee: http://www.cherokee-project.com/
     400
     401Configuring these servers is out of scope of this document; check each
     402server's respective documentation for instructions.
     403
     404Since your static file server won't be running Django, you'll need to modify
     405the deployment strategy to look something like:
     406
     407* When your static files change, run :djadmin:`collectstatic` locally.
     408* Push your local :setting:`STATIC_ROOT` up to the static file server
     409  into the directory that's being served. ``rsync`` is a good
     410  choice for this step since it only needs to transfer the
     411  bits of static files that have changed.
     412
     413Here's how this might look in a fabfile::
     414
     415    from fabric.api import *
     416    from fabric.contrib import project
     417
     418    # Where the static files get collected locally
     419    env.local_static_root = '/tmp/static'
     420
     421    # Where the static files should go remotely
     422    env.remote_static_root = '/home/www/static.example.com'
     423
     424    @roles('static')
     425    def deploy_static():
     426        local('./manage.py collectstatic')
     427        project.rysnc_project(
     428            remote_dir = env.remote_static_root,
     429            local_dir = env.local_static_root,
     430            delete = True
     431        )
     432
     433.. _staticfiles-from-cdn:
     434
     435Serving static files from a cloud service or CDN
     436------------------------------------------------
     437
     438Another common tactic is to serve static files from a cloud storage provider
     439like Amazon's S3__ and/or a CDN (content delivery network). This lets you
     440ignore the problems of serving static files, and can often make for
     441faster-loading webpages (especially when using a CDN).
     442
     443When using these services, the basic workflow would look a bit like the above,
     444except that instead of using ``rsync`` to transfer your static files to the
     445server you'd need to transfer the static files to the storage provider or CDN.
     446
     447There's any number of ways you might do this, but if the provider has an API a
     448:doc:`custom file storage backend </howto/custom-file-storage>` will make the
     449process incredibly simple. If you've written or are using a 3rd party custom
     450storage backend, you can tell :djadmin:`collectstatic` to use it by setting
     451:setting:`STATICFILES_STORAGE` to the storage engine.
     452
     453For example, if you've written an S3 storage backend in
     454``myproject.storage.S3Storage`` you could use it with::
     455
     456    STATICFILES_STORAGE = 'myproject.storage.S3Storage'
     457
     458Once that's done, all you have to do is run :djadmin:`collectstatic` and your
     459static files would be pushed through your storage package up to S3. If you
     460later needed to switch to a different storage provider, it could be as simple
     461as changing your :setting:`STATICFILES_STORAGE` setting.
     462
     463For details on how you'd write one of these backends,
     464:doc:`/howto/custom-file-storage`.
     465
     466.. seealso::
     467
     468    The `django-storages`__ project is a 3rd party app that provides many
     469    storage backends for many common file storage APIs (including `S3`__).
     470
     471__ http://s3.amazonaws.com/
     472__ http://code.larlet.fr/django-storages/
     473__ http://django-storages.readthedocs.org/en/latest/backends/amazon-S3.html
     474
     475Upgrading from ``django-staticfiles``
     476=====================================
     477
     478``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If
     479you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to
     480``django.contrib.staticfiles``, you'll need to make a few changes:
     481
     482* Application files should now live in a ``static`` directory in each app
     483  (`django-staticfiles`_ used the name ``media``, which was slightly
     484  confusing).
     485
     486* The management commands ``build_static`` and ``resolve_static`` are now
     487  called :djadmin:`collectstatic` and :djadmin:`findstatic`.
     488
     489* The settings ``STATICFILES_PREPEND_LABEL_APPS``,
     490  ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were
     491  removed.
     492
     493* The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the
     494  new :setting:`STATICFILES_FINDERS`.
     495
     496* The default for :setting:`STATICFILES_STORAGE` was renamed from
     497  ``staticfiles.storage.StaticFileStorage`` to
     498  ``staticfiles.storage.StaticFilesStorage``
     499
     500* If using :ref:`runserver<staticfiles-runserver>` for local development
     501  (and the :setting:`DEBUG` setting is ``True``), you no longer need to add
     502  anything to your URLconf for serving static files in development.
     503
     504Learn more
     505==========
     506
     507This document has covered the basics and some common usage patterns. For
     508complete details on all the settings, commands, template tags, and other pieces
     509include in ``django.contrib.staticfiles``, see :doc:`the staticfiles reference
     510</ref/contrib/staticfiles>`.

  • docs/topics/testing.txt 

    diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index 829e059..a72a2b7 100644
    a b out the `full reference`_ for more details.  
    19461946.. note::
    19471947
    19481948    ``LiveServerTestCase`` makes use of the :doc:`staticfiles contrib app
    1949     </howto/static-files>` so you'll need to have your project configured
     1949    </topics/files/static>` so you'll need to have your project configured
    19501950    accordingly (in particular by setting :setting:`STATIC_URL`).
    19511951
    19521952.. note::
Back to Top