Install docs - admin static files - clarification

[bb42]

Getting django installed easyly is one crucial aspect of making it more popular.
Coming from a PHP background I found getting the demo "polls" application to work quite a challenge. One aspect is the static file handling, that is described as part of the Apache-WSGI installation:
​https://docs.djangoproject.com/en/1.4/howto/deployment/wsgi/modwsgi/#serving-the-admin-files

We _strongly_ recommend using the staticfiles app" might not be valid for people who start with Django, so to clarifiy this paragraph I propose the following new text:

1. As long as you use the development server, you need not care about static files configuration, because these files are served automatically for the admin and any other installed apps.

2. If you use a dedicated web server, like Apache, the easiest way to configure the Admin static files handling is to setup an Alias in Apache's httpd.conf (or apache.conf etc.), similar to the Alias directives described above.

An example from a recent debian installation is:

Alias /static/admin /usr/local/lib/python2.6/dist-packages/django/contrib/admin
<Directory /static/admin/>
    Order deny,allow
    Allow from all
</Directory>

3. In a multi-project environment you will often want to integrate not only the admin files but CSS, Javascript or picture files for other apps from various local or remote sources. The profound solution for this is the 'staticfiles app' (link) which collects copies of all needed files in a local directory from where they are read by the webserver.

[bb42]

• Some filter does not like roman numbers => should be I. - II. - III. -

[Aymeric Augustin]

Deploying Django is more complicated than PHP's "just upload your files in DocumentRoot with FTP" scheme. But this complexity stems mostly from its power — it's a high-level framework. We try to make the learning curve as smooth as possible without compromising on best practices.

Yes, it takes 15 minutes to understand staticfiles: one needs to read ​one page of documentation carefully and type a few commands. These 15 minutes are an excellent investment and that's why the docs recommend that everyone learns staticfiles — especially beginners.

---

In detail:

1. => As explained its first paragraph, this page is about deployment in production. It isn't useful to talk about local development here.

2. => That's what the second bullet point says, in the current version of the docs. I prefer to avoid ready-to-copy-paste examples because a) it doesn't help developers to learn and understand b) it's impossible to make an example that will "just work" on every distro out there, not counting Windows, and people will complain. Sorry if I'm blunt, but I also prefer that people how can't write an Alias directive by themselves (possibly with Apache's docs) don't deploy Django in production on their own servers! Several companies provides turn-key Django hosting for developers without sysadmin experience.

3. => staticfiles isn't a profound and complicated thing that's only useful in industrial-grade projects. Every developer using Django should learn it.

[bb42]

I can not follow your arguments, the current docs are unclear, and the staticfiles app can not be understood completely and configured correctly quickly.
I spent two hours after learning that the apache-alias is the reasonable solution; and I admin and configure web-apps for years. The basic-usage paragraph just did not work for me (debian).
And "people how can't write an Alias directive by themselves" deploy tons of non-django apps on their webserver.
The idea that you should only use what you understand completely is very .. romantic. Did you ever take a plane?
But I understood your point about the Django philosophy, something like "Let's keep it just as complicated so that current PHP users stay away."

[Aymeric Augustin]

If you've followed my work on the docs you know very well that this isn't my philosophy.

Sorry, I shouldn't have spent 10 minutes replying to you. Please just ignore me.