diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/howto/static-files.txt | 41 | ||||
| -rw-r--r-- | docs/man/django-admin.1 | 2 | ||||
| -rw-r--r-- | docs/ref/contrib/staticfiles.txt | 26 | ||||
| -rw-r--r-- | docs/ref/django-admin.txt | 25 | ||||
| -rw-r--r-- | docs/ref/settings.txt | 22 |
5 files changed, 92 insertions, 24 deletions
diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt index 8d27409617..8dca80eb84 100644 --- a/docs/howto/static-files.txt +++ b/docs/howto/static-files.txt @@ -37,7 +37,7 @@ Using ``django.contrib.staticfiles`` Here's the basic usage in a nutshell: - 1. Put your media somewhere that staticfiles will find it.. + 1. Put your media somewhere that staticfiles will find it. Most of the time this place will be in a ``static`` directory within your application, but it could also be a specific directory you've put into @@ -69,12 +69,19 @@ Here's the basic usage in a nutshell: ./manage.py collectstatic This'll churn through your static file storage and move them into the - directory given by :setting:`STATICFILES_ROOT`. + directory given by :setting:`STATICFILES_ROOT`. (This is not necessary + in local development if you are using :djadmin:`runserver` or adding + ``staticfiles_urlpatterns`` to your URLconf; see below). 4. Deploy that media. - If you're using the built-in development server, you can quickly - serve static media locally by adding:: + If you're using the built-in development server (the + :djadmin:`runserver` management command) and have the :setting:`DEBUG` + setting set to ``True``, your staticfiles will automatically be served + from :setting:`STATICFILES_URL` in development. + + If you are using some other server for local development, you can + quickly serve static media locally by adding:: from django.contrib.staticfiles.urls import staticfiles_urlpatterns urlpatterns += staticfiles_urlpatterns() @@ -100,6 +107,18 @@ Those are the basics. For more details on common configuration options, read on; for a detailed reference of the settings, commands, and other bits included with the framework see :doc:`the staticfiles reference </ref/contrib/staticfiles>`. +.. note:: + + In previous versions of Django, it was common to place static assets in + :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both at + :setting:`MEDIA_URL`. Part of the purpose of introducing the ``staticfiles`` + app is to make it easier to keep static files separate from user-uploaded + files. For this reason, you will probably want to make your + :setting:`MEDIA_ROOT` and :setting:`MEDIA_URL` different from your + :setting:`STATICFILES_ROOT` and :setting:`STATICFILES_URL`. You will need to + arrange for serving of files in :setting:`MEDIA_ROOT` yourself; + ``staticfiles`` does not deal with user-uploaded media at all. + .. _staticfiles-in-templates: Referring to static files in templates @@ -192,8 +211,12 @@ media server, which is a lot of overhead to mess with when developing locally. Thus, the ``staticfiles`` app ships with a quick and dirty helper view that you can use to serve files locally in development. -To enable this view, you'll add a couple of lines to your URLconf. The first -line goes at the top of the file, and the last line at the bottom:: +This view is automatically enabled and will serve your static files at +:setting:`STATICFILES_URL` when you use the built-in :djadmin:`runserver`. + +To enable this view if you are using some other server for local development, +you'll add a couple of lines to your URLconf. The first line goes at the top of +the file, and the last line at the bottom:: from django.contrib.staticfiles.urls import staticfiles_urlpatterns @@ -242,7 +265,7 @@ app, the basic outline gets modified to look something like: * On the server, run :djadmin:`collectstatic` to move all the media into :setting:`STATICFILES_ROOT`. * Point your web server at :setting:`STATICFILES_ROOT`. For example, here's - of :ref:`how to do this under Apache and mod_wsgi <serving-media-files>`. + :ref:`how to do this under Apache and mod_wsgi <serving-media-files>`. You'll probably want to automate this process, especially if you've got multiple web servers. There's any number of ways to do this automation, but one option @@ -393,6 +416,10 @@ you'll need to make a few changes: ``staticfiles.storage.StaticFileStorage`` to ``staticfiles.storage.StaticFilesStorage`` + * If using :djadmin:`runserver` for local development (and the + :setting:`DEBUG` setting is ``True``), you no longer need to add + anything to your URLconf for serving static files in development. + Learn more ========== diff --git a/docs/man/django-admin.1 b/docs/man/django-admin.1 index a402bab65a..539d88c5c5 100644 --- a/docs/man/django-admin.1 +++ b/docs/man/django-admin.1 @@ -75,7 +75,7 @@ Runs this project as a FastCGI application. Requires flup. Use .B runfcgi help for help on the KEY=val pairs. .TP -.BI "runserver [" "\-\-noreload" "] [" "\-\-adminmedia=ADMIN_MEDIA_PATH" "] [" "port|ipaddr:port" "]" +.BI "runserver [" "\-\-noreload" "] [" "\-\-nostatic" "] [" "\-\-insecure" "] [" "\-\-adminmedia=ADMIN_MEDIA_PATH" "] [" "port|ipaddr:port" "]" Starts a lightweight Web server for development. .TP .BI "shell [" "\-\-plain" "]" diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index 046e84f8ca..f82fd79024 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -34,13 +34,21 @@ STATICFILES_ROOT Default: ``''`` (Empty string) -The absolute path to the directory that holds static files:: +The absolute path to the directory that the :djadmin:`collectstatic` management +command will collect static files into, for serving from +:setting:`STATICFILES_URL`:: STATICFILES_ROOT = "/home/example.com/static/" This is a **required setting** unless you've overridden :setting:`STATICFILES_STORAGE` and are using a custom storage backend. +This is not a place to store your static files permanently under version +control; you should do that in directories that will be found by your +:setting:`STATICFILES_FINDERS` (by default, per-app ``static/`` subdirectories, +and any directories you include in :setting:`STATICFILES_DIRS`). Files from +those locations will be collected into :setting:`STATICFILES_ROOT`. + .. setting:: STATICFILES_URL STATICFILES_URL @@ -51,7 +59,7 @@ Default: ``'/static/'`` The URL that handles the files served from :setting:`STATICFILES_ROOT`, e.g.:: STATICFILES_URL = '/site_media/static/' - + ... or perhaps:: STATICFILES_URL = 'http://static.example.com/' @@ -130,7 +138,7 @@ your :setting:`STATICFILES_FINDERS` setting, it will look for static files in the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE` setting. -.. note:: +.. note:: When using the :class:`AppDirectoriesFinder` finder, make sure your apps can be found by Django's app loading mechanism. Simply include a ``models`` @@ -271,11 +279,13 @@ This view function serves static files in development. **insecure**. This is only intended for local development, and should **never be used in production**. -To use the view, add the following snippet to the end of your primary URL -configuration:: +This view is automatically enabled by :djadmin:`runserver` (with a +:setting:`DEBUG` setting set to ``True``). To use the view with a different +local development server, add the following snippet to the end of your +primary URL configuration:: from django.conf import settings - + if settings.DEBUG: urlpatterns = patterns('django.contrib.staticfiles.views', url(r'^static/(?P<path>.*)$', 'serve'), @@ -292,8 +302,8 @@ This will return the proper URL pattern for serving static files to your already defined pattern list. Use it like this:: from django.contrib.staticfiles.urls import staticfiles_urlpatterns - + # ... the rest of your URLconf here ... - + urlpatterns += staticfiles_urlpatterns() diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index ea49e2372d..14fc69f99e 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -681,6 +681,31 @@ Example usage:: django-admin.py runserver --noreload +.. django-admin-option:: --nostatic + +Use the ``--nostatic`` option to disable serving of static files with the +:doc:`staticfiles </ref/contrib/staticfiles>` app entirely. + +Example usage:: + + django-admin.py runserver --nostatic + +.. django-admin-option:: --insecure + +Use the ``--insecure`` option to force serving of static files with the +:doc:`staticfiles </ref/contrib/staticfiles>` app even if the :setting:`DEBUG` +setting is ``False``. By using this you acknoledge the fact that it's +**grossly inefficient** and probably **insecure**. This is only intended for +local development, and should **never be used in production**. + +See the :doc:`reference documentation of the app </ref/contrib/staticfiles>` +for more details and learn how to :doc:`manage and deploy static files +</howto/static-files>` correctly. + +Example usage:: + + django-admin.py runserver --insecure + Examples of using different ports and addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 78b5fd995e..2c338df6c7 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -53,7 +53,7 @@ Default: ``'/media/'`` The URL prefix for admin media -- CSS, JavaScript and images used by the Django administrative interface. Make sure to use a trailing -slash, and to have this be different from the ``MEDIA_URL`` setting +slash, and to have this be different from the :setting:`MEDIA_URL` setting (since the same URL cannot be mapped onto two different sets of files). @@ -1104,8 +1104,12 @@ MEDIA_ROOT Default: ``''`` (Empty string) -Absolute path to the directory that holds media for this installation. -Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``. +Absolute path to the directory that holds media for this installation, used +for :doc:`managing stored files </topics/files>`. + +Example: ``"/home/media/media.lawrence.com/"`` + +See also :setting:`MEDIA_URL`. .. setting:: MEDIA_URL @@ -1114,15 +1118,15 @@ MEDIA_URL Default: ``''`` (Empty string) -URL that handles the media served from ``MEDIA_ROOT``. +URL that handles the media served from :setting:`MEDIA_ROOT`, used +for :doc:`managing stored files </topics/files>`. + Example: ``"http://media.lawrence.com"`` Note that this should have a trailing slash if it has a path component. -Good: ``"http://www.example.com/static/"`` -Bad: ``"http://www.example.com/static"`` - -.. setting:: MIDDLEWARE_CLASSES + * Good: ``"http://www.example.com/static/"`` + * Bad: ``"http://www.example.com/static"`` MESSAGE_LEVEL ------------- @@ -1161,6 +1165,8 @@ Default:: Sets the mapping of message levels to message tags. See the :doc:`messages documentation </ref/contrib/messages>` for more details. +.. setting:: MIDDLEWARE_CLASSES + MIDDLEWARE_CLASSES ------------------ |