Clarify runserver is overridden for django.contrib.staticfiles

[davidjb]

In the main static files documentation, the serving process is generally explained that runserver will automatically serve files if DEBUG is set to true. This isn't quite the full story because it's not the original runserver that is being used, and rather it's the one from django.contrib.staticfiles. This gets explained if you dig deeper, but it isn't clear what's happening before getting this deep.

This PR makes a clarification to the wording of this section in the docs to explain how runserver is working its magic, and that if you have a custom runserver command (like I did), you need a special strategy.

Trac: https://code.djangoproject.com/ticket/30308

[carltongibson]

Hi @davidjb. My initial take on this is that it's complicating matters for something which will affect >1% of users. (Who's got a custom runserver? 🙂)

I think telling people to collectstatic in development (where using runserver) is not right.

I'm happy to discuss this briefly here but I'm going to close this as wontfix on that basis. I hope that makes sense.

[davidjb]

@carltongibson The bit that was most confusing for me about these docs is that the links to runserver are pointing at the core runserver rather than the one that's provided from staticfiles. To me, this read as though the built-in runserver was responsible for the behaviour when it's actually the overridden version, hence my attempt at clarification. Perhaps the solution is to link to https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/#runserver instead so it's clear which runserver is being used. That said, I still believe that some context is needed in this section about the fact that runserver is being overridden.

The second change clarifies that you need a STATIC_ROOT configured (not just STATIC_URL).

Lastly the third change was that from reading this as a new user, it wasn't clear when or if to run collectstatic. Eventually I figured it out, but from this section of the docs, I was under the impression for a head-scratching while that adding it as an app and adding the URL config would make it work without needing collectstatic.

Happy to reformat into another PR if you have suggestions.

[carltongibson]

Hi @davidjb.

...it wasn't clear when or if to run collectstatic.

I think that's the point. I kind of think it's covered by the note below:

Also this helper function only serves the actual :setting:STATIC_ROOT
folder; it doesn't perform static files discovery like
:mod:django.contrib.staticfiles.

Maybe an addition there saying "so you'll need to run collectstatic but I (also) kind of think better advice it just to use staticfiles, (and hand-route the serve() view if you need to) which I think is explained higher up.