Improve static files documentation

[Wim Feijen]

In order to keep our patches straight, we splitted ticket 19582 into two parts.

https://code.djangoproject.com/ticket/19582 deals with adding a tutorial on static files, which is done by jpic,

This ticket is about rewriting the staticfiles how to.

[Wim Feijen]

​https://github.com/django/django/pull/801

[Wim Feijen]

For the record: this patch was written by Jan Murre, Reinout van Rees and Wim Feijen, and reviewed by Remco Wendt

[Reinout van Rees]

I made a bunch of sphinx-relations and wording fixes. Partially from the comments on github. The changes have been pushed to the pull request.

I've temporarily got the latest version of our docs at ​http://reinout.vanrees.org/download/tempdjango/howto/static-files.html and ​http://reinout.vanrees.org/download/tempdjango/howto/static-files-in-production.html in case that's handy.

One thing I myself wonder about is the "handling user-uploaded media" section in the howto. But apparently there's no other place where we can put it (and it comes up in questions about staticfiles).

[Reinout van Rees]

Some discussion with Jacob and Aymeric in #django-sprint. Some last fixes, like addition of link ​https://www.djangopackages.com/grids/g/storage-backends/ to replace the former link to just django-storages.

Really ready for checkin now? :-) ​https://github.com/django/django/pull/801

[Aymeric Augustin]

This should be merged simultaneously with #19582 as some bits are moved from the howto to the new tutorial.

[Tim Graham]

I'm reviewing this and will merge it when finished.

[Tim Graham]

Forgive me if I've missed IRC conversations that discuss the following. I appreciate the clarity this change adds by removing some redundant information, however, it seems to remove some potentially useful information as well.

1. The instructions for upgrading from django-staticfiles were removed. I'm assuming this is fine since we still have those instructions in older versions of the docs and they aren't useful in the long run as we have less people upgrading as time goes on.

2. The discussion of STATIC_URL and TEMPLATE_CONTEXT_PROCESSORS was removed. I understand if we don't want to promote this method.

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

     <img src="{{ STATIC_URL }}images/hi.jpg" alt="Hi!" />

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 </ref/class-based-views/index>`,
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.

... as well as a note describing the differences between MEDIA_ROOT/MEDIA_URL and STATIC_ROOT/STATIC_URL. While it references "previous versions of Django", it still seems useful to me in describing the differences even for those who are coming to Django for the first time.

.. 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`.

4. The documentation for django.views.static.serve and django.conf.urls.static.static was removed. I don't think we should remove them since our policy is that anything that's documented is "stable API."

.. _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<path>.*)$', '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.

5. Instead of howto/static-files and howto/static-files-in-production, I've added a directory: howto/static-files/index and howto/static-files/deployment.

Updated pull request: ​https://github.com/django/django/pull/889
rendered documents:
​http://techytim.com/django/19897/howto/static-files/index.html
​http://techytim.com/django/19897/howto/static-files/deployment.html

[Jannis Leidel]

Thanks for the review, timo! I'm just going to reply to your questions :)

1. django-staticfiles hasn't been updated for a while now and should be removed from our docs. contrib-staticfiles is the defacto staticfiles.

2. Hm, the context processor should definitely be documented, although the ref section should be enough. Everybody should use the template tag.

3. The note should maybe move to the deprecation timeline and linked from the staticfiles docs, many of the current beginners don't remember MEDIA_ROOT as the location of non-upload files anymore, so I think this section is purely historical.

4. Oh, that's odd, hm, this should definitely be mentioned in a reference doc style. It's not important for the tutorial though, IMO.

[Jannis Leidel]

5. Ah, makes sense.

[Tim Graham]

1. Will omit.
2. It's mentioned in docs/ref/templates/api.txt so we're good.
3. Not sure how to incorporate exactly, will omit for now at least.
4. Going to add docs/ref/views.txt for the view function and put the URL function in docs/ref/urls.txt

[Tim Graham <timograham@…>]

In 6c730da1f6d34f5c38fa1d990d368286e016546c:

Fixed #19897 - Updated static files howto.

Thanks Jan Murre, Reinout van Rees and Wim Feijen,
plus Remco Wendt for reviewing.

[Tim Graham <timograham@…>]

In c3779d42142eb83eb8694177a12066261b3243aa:

[1.5.x] Fixed #19897 - Updated static files howto.

Thanks Jan Murre, Reinout van Rees and Wim Feijen,
plus Remco Wendt for reviewing.

Backport of i6c730da1f from master.