[Django] #19582: Add tutorial on static files
Django
-------------------------------+--------------------
Reporter: jpic | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.4
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/19582>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: jpic | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: docs, static files | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 1
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Changes (by anonymous):
* needs_better_patch: => 0
* needs_tests: => 0
* version: 1.4 => master
* easy: 0 => 1
* keywords: => docs, static files
* needs_docs: => 1
* type: Uncategorized => Cleanup/optimization
* stage: Unreviewed => Accepted
Comment:
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:1>
Django
Reporter: jpic | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: docs, static files | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 1
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by russellm):
Zed Shaw has provided [http://zedshaw.com/static_files_critique.txt 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:2>
Django
Reporter: jpic | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: docs, static files | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 1
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by alecperkins@…):
I took a stab at rewriting the first part of the
[https://github.com/alecperkins/django/blob/60362cf7fda8d0ea3b190d2f7c66f84ac3273c3d/docs/howto
/static-files.txt static files howto] ([http://show-
em.net/b0595da44fc4302ab4d4/howto/static-files.html 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:3>
Django
Reporter: jpic | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: docs, static files | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* needs_docs: 1 => 0
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:4>
Django
Reporter: jpic | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: docs, static files | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* cc: jpic (added)
Comment:
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.)
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:5>
Django
Reporter: jpic | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: docs, static files | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* cc: reinout@… (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:6>
Django
Reporter: jpic | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: docs, static files | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by jezdez):
A quick discussion about staticfiles from Zed Shaw:
https://twitter.com/jezdez/statuses/291608100564242432
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:7>
Django
Reporter: jpic | Owner: reinout
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: docs, static files | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* owner: nobody => reinout
* status: new => assigned
Comment:
Note: we're sprinting on this in Utrecht at the "Dutch winter sprint"
23/24 feb 2013.
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:8>
Django
Reporter: jpic | Owner: reinout
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: docs, static files, | Needs documentation: 0
sprint2013 | Patch needs improvement: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Changes (by reinout):
* keywords: docs, static files => docs, static files, sprint2013
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:9>
Django
Reporter: jpic | Owner: reinout
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: docs, static files, | Needs documentation: 0
sprint2013 | Patch needs improvement: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (by jpic):
On which structure should we base tutorial06 about staticfiles ?
proposal_1.rst or proposal_0.rst ?
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:10>
Django
Reporter: jpic | Owner: reinout
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: docs, static files, | Needs documentation: 0
sprint2013 | Patch needs improvement: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:11>
Django
Reporter: jpic | Owner: reinout
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: docs, static files, | Needs documentation: 0
sprint2013 | Patch needs improvement: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (by wimfeijen):
We splitted this ticket:
Rewriting the how-to is now done in:
https://code.djangoproject.com/ticket/19897
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:12>
Django
Reporter: jpic | Owner: reinout
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: docs, static files, | Needs documentation: 0
sprint2013 | Patch needs improvement: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:13>
Django
Reporter: jpic | Owner: reinout
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: docs, static files, | Needs documentation: 0
sprint2013 | Patch needs improvement: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (by jpic):
Pull request: https://github.com/django/django/pull/795
Rendered version:
http://yourlabs.org/site_media/django/docs/_build/html/intro/tutorial06.html
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:14>
Django
Reporter: jpic | Owner: reinout
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Keywords: docs, static files, | checkin
sprint2013 | Needs documentation: 0
Has patch: 1 | Patch needs improvement: 0
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Changes (by wimfeijen):
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:15>
Django
Reporter: jpic | Owner: reinout
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Ready for
Keywords: docs, static files, | checkin
sprint2013 | Needs documentation: 0
Has patch: 1 | Patch needs improvement: 0
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (by wimfeijen):
Well written!
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:16>
Django
Reporter: jpic | Owner: reinout
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Keywords: docs, static files, | Needs documentation: 0
Has patch: 1 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Changes (by timo):
* needs_better_patch: 0 => 1
* stage: Ready for checkin => Accepted
Comment:
This isn't quite RFC, I've left some comments on the pull request.
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:17>
Django
Reporter: jpic | Owner: reinout
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: docs, static files, | Needs documentation: 0
sprint2013 | Patch needs improvement: 1
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (by aaugustin):
This should be merged simultaneously with #19897 as some bits are moved
from the howto to this new tutorial.
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:18>
Django
Reporter: jpic | Owner: timo
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: docs, static files, | Needs documentation: 0
sprint2013 | Patch needs improvement: 1
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 1 |
-------------------------------------+-------------------------------------
* owner: reinout => timo
Comment:
I'm reviewing this and will merge it when finished.
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:19>
Django
Reporter: jpic | Owner: timo
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: docs, static files, | Needs documentation: 0
sprint2013 | Patch needs improvement: 1
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (by reinout):
If you want me (or probably jpic) to do some squish-commits-together work
or something like that, just say so :-)
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:20>
Django
Reporter: jpic | Owner: timo
Type: | Status: assigned
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: docs, static files, | Needs documentation: 0
sprint2013 | Patch needs improvement: 1
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (by timo):
Updated pull request (includes #19897):
https://github.com/django/django/pull/889
rendered: http://techytim.com/django/19897/intro/tutorial06.html
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:21>
Django
Reporter: jpic | Owner: timo
Component: Documentation | Version: master
Severity: Normal | Resolution:
sprint2013 | Needs documentation: 0
Has patch: 1 | Patch needs improvement: 1
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Changes (by aaugustin):
* type: Cleanup/optimization => New feature
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:22>
Django
Reporter: jpic | Owner: timo
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: docs, static files, | Triage Stage: Accepted
sprint2013 | Needs documentation: 0
Has patch: 1 | Patch needs improvement: 1
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"c32fc79aa120a0a129680805aef6731c1c2c7aef"]:
{{{
#!CommitTicketReference repository=""
revision="c32fc79aa120a0a129680805aef6731c1c2c7aef"
Fixed #19582 - Added a static files tutorial.
Thanks James Pic.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:23>
Django
Reporter: jpic | Owner: timo
Type: New feature | Status: closed
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: docs, static files, | Triage Stage: Accepted
sprint2013 | Needs documentation: 0
Has patch: 1 | Patch needs improvement: 1
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"1c42a3ec736f55b79bc1a7b4cad4cbe65b9cb27e"]:
{{{
#!CommitTicketReference repository=""
revision="1c42a3ec736f55b79bc1a7b4cad4cbe65b9cb27e"
[1.5.X] Fixed #19582 - Added a static files tutorial.
Thanks James Pic.
Backport of c32fc79aa1 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:24>
Django
Reporter: James Pic | Owner: Tim
| Graham
Keywords: docs, static files, | Triage Stage: Accepted
sprint2013 |
Comment (by Mahenth V):
I’d like to work on this issue. Planning to add a beginner-friendly
tutorial section about static files under docs/howto/static-files/
--
Ticket URL: <https://code.djangoproject.com/ticket/19582#comment:25>