Code

Opened 14 months ago

Closed 13 months ago

Last modified 13 months ago

#19897 closed Cleanup/optimization (fixed)

Improve static files documentation

Reported by: wimfeijen Owned by: timo
Component: Documentation Version: master
Severity: Normal Keywords: staticfiles
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Attachments (0)

Change History (14)

comment:1 Changed 14 months ago by wimfeijen

  • Needs documentation unset
  • Needs tests unset
  • Owner changed from nobody to wimfeijen
  • Patch needs improvement unset
  • Status changed from new to assigned
  • Triage Stage changed from Unreviewed to Accepted

comment:3 Changed 14 months ago by wimfeijen

  • Triage Stage changed from Accepted to Ready for checkin

comment:4 Changed 14 months ago by wimfeijen

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

comment:5 Changed 14 months ago by reinout

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

comment:6 Changed 14 months ago by reinout

  • Has patch set

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

comment:7 Changed 14 months ago by aaugustin

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

comment:8 Changed 14 months ago by timo

  • Owner changed from wimfeijen to timo

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

Version 0, edited 14 months ago by timo (next)

comment:9 Changed 14 months ago by timo

  • Triage Stage changed from Ready for checkin to Accepted

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

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

comment:10 Changed 13 months ago by jezdez

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.
  1. Hm, the context processor should definitely be documented, although the ref section should be enough. Everybody should use the template tag.
  1. 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.
  1. Oh, that's odd, hm, this should definitely be mentioned in a reference doc style. It's not important for the tutorial though, IMO.

comment:11 Changed 13 months ago by jezdez

  1. Ah, makes sense.

comment:12 Changed 13 months ago by timo

  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

comment:13 Changed 13 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from assigned to closed

In 6c730da1f6d34f5c38fa1d990d368286e016546c:

Fixed #19897 - Updated static files howto.

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

comment:14 Changed 13 months ago by 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.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.