Add tutorial on static files

[James Pic]

Maybe it's just me, but I've seen so many users confused by how django static files work.

Users trying to stuff their project-specific staticfiles into STATIC_ROOT for example, instead of adding a path in STATICFILES_DIRS.

A tutorial for static files could help many users.

[anonymous]

It's not just you. :)

Django docs contain two pages about static files:
​https://docs.djangoproject.com/en/dev/howto/static-files/
​https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/

The first one is hard to understand but does the job and acts as a kind of tutorial. In my opinion, we could re-write this information but make it more easy to understand.

If you are willing to make a contribution to Django, you are welcome to do so and apply a patch. I'll set easy pickings.

[Russell Keith-Magee]

Zed Shaw has provided ​a detailed teardown/rant on what is wrong with the current docs, and how to improve them. Summarizing, It looks like the confusion stems from three sources:

• Understanding what staticfiles is actually trying to do
• Ordering of information - the howto talks about production needs before development needs
• Clarity over the role played by various settings.

[alecperkins@…]

I took a stab at rewriting the first part of the ​static files howto (​rendered). This was based on, for the first time in literally years, trying to set up static files from scratch and finally wrapping my head around it.

For those coming at staticfiles with the expectation of "put files in this folder, they get served at this URL", the app-specific static files idea is confusing. This rewrite makes it more clear what's necessary to get that outcome, and explain why the process is the way it is.

[James Pic]

Here some things I'd like to change.

• given the general confusion on how to add a static file to a project, I would rewrite the first part so that it goes straight to the point: ie. "Install a static file in your project: how to add jQuery"
• second part of the tutorial would be deployment,
• third part would be using app/static subfolder,
• wording issues, for example "assets" is a word I (as a self learner, non english) learnt from reading about Rails, so I think it can be confusing for other users. It would be better to name "static files" just "static files"

Also, I have tried django 1.5 starter project: it looks like every django project that will need at least one static file (most projects) will have to setup STATICFILES_DIRS=[os.path.join(BASE_DIR, 'static')]. What's the point ? Couldn't we change that and make it default ?

I mean, it could potentially be as easy as:

drop style.css in your_project/static and use
{{ STATIC_URL }}style.css or {% static 'style.css' %} in the template

(Sorry I had totally forgotten about this and forgot to CC myself
... Note that I've read both document and I can ensure
that every point listed by Zed has a response in the new
tutorial.)

[Jannis Leidel]

A quick discussion about staticfiles from Zed Shaw: ​https://twitter.com/jezdez/statuses/291608100564242432

[Reinout van Rees]

Note: we're sprinting on this in Utrecht at the "Dutch winter sprint" 23/24 feb 2013.

[James Pic]

Proposal for the tutorial06, based on Jannis suggestion to kind of follow the structure of the tutorial about templates (project-specific override first, app templates next)

[James Pic]

Proposal for tutorial06 about staticfiles: with smaller steps but not following the exact same pedagogy used to teach template file management

[James Pic]

On which structure should we base tutorial06 about staticfiles ? proposal_1.rst or proposal_0.rst ?

[Jannis Leidel]

Proposal 0, as it introduces app level static files earlier. I just talked with Aymeric about it and we decided it would be best to move more toward pushing the idea of apps in the tutorial in general, including the part where we point to TEMPLATES_DIRS. This would be another ticket entirely of course.

[Wim Feijen]

We splitted this ticket:

Rewriting the how-to is now done in:

https://code.djangoproject.com/ticket/19897

[James Pic]

After talking with Aymeric, we decided the following plan for tutorial06:

• Using the AppDirectoriesFinder: demonstrates how to use polls/static/polls/style.css with {% static 'polls/style.css' %},
• Relating static files: a simple demonstration of adding a css background image, just to have an opportunity of warning the user that he should not hardcode absolute paths.

[James Pic]

Pull request: ​https://github.com/django/django/pull/795

Rendered version: ​http://yourlabs.org/site_media/django/docs/_build/html/intro/tutorial06.html

[Wim Feijen]

Well written!

[Tim Graham]

This isn't quite RFC, I've left some comments on the pull request.

[Aymeric Augustin]

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

[Tim Graham]

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

[Reinout van Rees]

If you want me (or probably jpic) to do some squish-commits-together work or something like that, just say so :-)

[Tim Graham]

Updated pull request (includes #19897): ​https://github.com/django/django/pull/889
rendered: ​http://techytim.com/django/19897/intro/tutorial06.html

[Tim Graham <timograham@…>]

In c32fc79aa120a0a129680805aef6731c1c2c7aef:

Fixed #19582 - Added a static files tutorial.

Thanks James Pic.

[Tim Graham <timograham@…>]

In 1c42a3ec736f55b79bc1a7b4cad4cbe65b9cb27e:

[1.5.X] Fixed #19582 - Added a static files tutorial.

Thanks James Pic.

Backport of c32fc79aa1 from master