Code

Opened 16 months ago

Closed 13 months ago

Last modified 13 months ago

#19582 closed New feature (fixed)

Add tutorial on static files

Reported by: jpic Owned by: timo
Component: Documentation Version: master
Severity: Normal Keywords: docs, static files, sprint2013
Cc: jpic, reinout@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: yes UI/UX: no

Description

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.

Attachments (2)

proposal_1.rst (2.0 KB) - added by jpic 14 months ago.
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)
proposal_0.rst (1.6 KB) - added by jpic 14 months ago.
Proposal for tutorial06 about staticfiles: with smaller steps but not following the exact same pedagogy used to teach template file management

Download all attachments as: .zip

Change History (26)

comment:1 Changed 16 months ago by anonymous

  • Easy pickings set
  • Keywords docs, static files added
  • Needs documentation set
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Type changed from Uncategorized to Cleanup/optimization
  • Version changed from 1.4 to master

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.

comment:2 Changed 15 months ago by russellm

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.

comment:3 Changed 15 months ago by 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.

comment:4 Changed 15 months ago by timo

  • Has patch set
  • Needs documentation unset

comment:5 Changed 14 months ago by jpic

  • Cc jpic added
Last edited 14 months ago by jpic (previous) (diff)

comment:6 Changed 14 months ago by reinout

  • Cc reinout@… added

comment:7 Changed 14 months ago by jezdez

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

comment:8 Changed 14 months ago by reinout

  • Owner changed from nobody to reinout
  • Status changed from new to assigned

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

comment:9 Changed 14 months ago by reinout

  • Keywords files, sprint2013 added; files removed

Changed 14 months ago by jpic

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)

Changed 14 months ago by jpic

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

comment:10 Changed 14 months ago by jpic

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

comment:11 Changed 14 months ago by jezdez

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.

comment:12 Changed 14 months ago by wimfeijen

We splitted this ticket:

Rewriting the how-to is now done in:

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

comment:13 Changed 14 months ago by jpic

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.

comment:15 Changed 14 months ago by wimfeijen

  • Triage Stage changed from Accepted to Ready for checkin

comment:16 Changed 14 months ago by wimfeijen

Well written!

comment:17 Changed 14 months ago by timo

  • Patch needs improvement set
  • Triage Stage changed from Ready for checkin to Accepted

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

comment:18 Changed 14 months ago by aaugustin

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

comment:19 Changed 14 months ago by timo

  • Owner changed from reinout to timo

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

comment:20 Changed 14 months ago by reinout

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

comment:22 Changed 13 months ago by aaugustin

  • Type changed from Cleanup/optimization to New feature

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

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

In c32fc79aa120a0a129680805aef6731c1c2c7aef:

Fixed #19582 - Added a static files tutorial.

Thanks James Pic.

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

In 1c42a3ec736f55b79bc1a7b4cad4cbe65b9cb27e:

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

Thanks James Pic.

Backport of c32fc79aa1 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.